Implement API calls and CLI

Author: jsurrea

.github/workflows/python-ci.yml

@@ -33,7 +33,7 @@ jobs:
       - name: Install dependencies
         run: |
           uv pip install --system -e .
-          uv pip install --system pytest pytest-cov mypy ruff build
+          uv pip install --system pytest pytest-cov pytest-mock mypy ruff build
         
 
       - name: Run linters

antares-python/pyproject.toml

@@ -2,17 +2,28 @@
 name = "antares-python"
 version = "0.1.0"
 description = "Python interface for the Antares simulation software"
-authors = [{ name = "Juan Sebastian Urrea-Lopez", email = "[email protected]" }]
+authors = [
+    { name = "Juan Sebastian Urrea-Lopez", email = "[email protected]" },
+]
 readme = "README.md"
 requires-python = ">=3.13"
-dependencies = []
+dependencies = [
+    "pydantic>=2.11.3",
+    "httpx>=0.28.1",
+    "typer>=0.15.2",
+    "rich>=13.0",
+    "tomli>=2.2.1",
+]
+
+[project.scripts]
+antares = "antares.cli:app"
 
 [build-system]
 requires = ["setuptools>=61.0", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [tool.ruff]
-line-length = 88
+line-length = 100
 lint.select = ["E", "F", "I", "UP", "B", "PL"]
 exclude = ["dist", "build"]
 

antares-python/src/antares/__init__.py

@@ -1,3 +1,4 @@
-from .core import saludar
+from .client import AntaresClient
+from .models.ship import ShipConfig
 
-__all__ = ["saludar"]
+__all__ = ["AntaresClient", "ShipConfig"]

antares-python/src/antares/cli.py

@@ -0,0 +1,79 @@
+import asyncio
+
+import typer
+from rich.console import Console
+from rich.theme import Theme
+
+from antares import AntaresClient, ShipConfig
+from antares.config_loader import load_config
+
+app = typer.Typer(help="Antares Simulation CLI")
+
+console = Console(
+    theme=Theme(
+        {
+            "info": "green",
+            "warn": "yellow",
+            "error": "bold red",
+        }
+    )
+)
+
+
+def build_client(config_path: str | None, verbose: bool) -> AntaresClient:
+    settings = load_config(config_path)
+
+    if verbose:
+        console.print(f"[info]Using settings: {settings.model_dump()}")
+
+    return AntaresClient(
+        base_url=settings.base_url,
+        tcp_host=settings.tcp_host,
+        tcp_port=settings.tcp_port,
+        timeout=settings.timeout,
+        auth_token=settings.auth_token,
+    )
+
+
+@app.command()
+def reset(
+    config: str = typer.Option(None, help="Path to config TOML file"),
+    verbose: bool = typer.Option(False, "--verbose", "-v"),
+):
+    """Reset the simulation."""
+    client = build_client(config, verbose)
+    client.reset_simulation()
+    console.print("[info]✅ Simulation reset.")
+
+
+@app.command()
+def add_ship(
+    x: float,
+    y: float,
+    config: str = typer.Option(None, help="Path to config TOML file"),
+    verbose: bool = typer.Option(False, "--verbose", "-v"),
+):
+    """Add a ship to the simulation at (x, y)."""
+    client = build_client(config, verbose)
+    ship = ShipConfig(initial_position=(x, y))
+    client.add_ship(ship)
+    console.print(f"[info]🚢 Added ship at ({x}, {y})")
+
+
+@app.command()
+def subscribe(
+    config: str = typer.Option(None, help="Path to config TOML file"),
+    verbose: bool = typer.Option(False, "--verbose", "-v"),
+):
+    """Subscribe to simulation data stream."""
+    client = build_client(config, verbose)
+
+    async def _sub():
+        async for event in client.subscribe():
+            console.print_json(data=event)
+
+    asyncio.run(_sub())
+
+
+if __name__ == "__main__":
+    app()

antares-python/src/antares/client/__init__.py

@@ -0,0 +1,61 @@
+from collections.abc import AsyncIterator
+
+from antares.client.rest import RestClient
+from antares.client.tcp import TCPSubscriber
+from antares.config import AntaresSettings
+from antares.models.ship import ShipConfig
+
+
+class AntaresClient:
+    def __init__(
+        self,
+        base_url: str | None = None,
+        tcp_host: str | None = None,
+        tcp_port: int | None = None,
+        timeout: float | None = None,
+        auth_token: str | None = None,
+    ) -> None:
+        """
+        Public interface for interacting with the Antares simulation engine.
+        Accepts config overrides directly or falls back to environment-based configuration.
+        """
+
+        # Merge provided arguments with environment/.env via AntaresSettings
+        self._settings = AntaresSettings(
+            base_url=base_url,
+            tcp_host=tcp_host,
+            tcp_port=tcp_port,
+            timeout=timeout,
+            auth_token=auth_token,
+        )
+
+        self._rest = RestClient(
+            base_url=self._settings.base_url,
+            timeout=self._settings.timeout,
+            auth_token=self._settings.auth_token,
+        )
+        self._tcp = TCPSubscriber(
+            host=self._settings.tcp_host, port=self._settings.tcp_port
+        )
+
+    def reset_simulation(self) -> None:
+        """
+        Sends a request to reset the current simulation state.
+        """
+        return self._rest.reset_simulation()
+
+    def add_ship(self, ship: ShipConfig) -> None:
+        """
+        Sends a new ship configuration to the simulation engine.
+        """
+        return self._rest.add_ship(ship)
+
+    async def subscribe(self) -> AsyncIterator[dict]:
+        """
+        Subscribes to live simulation data over TCP.
+
+        Yields:
+            Parsed simulation event data as dictionaries.
+        """
+        async for event in self._tcp.subscribe():
+            yield event

antares-python/src/antares/client/rest.py

@@ -0,0 +1,61 @@
+import httpx
+
+from antares.errors import ConnectionError, SimulationError
+from antares.models.ship import ShipConfig
+
+
+class RestClient:
+    """
+    Internal client for interacting with the Antares simulation REST API.
+    """
+
+    def __init__(
+        self, base_url: str, timeout: float = 5.0, auth_token: str | None = None
+    ) -> None:
+        """
+        Initializes the REST client.
+
+        Args:
+            base_url: The root URL of the Antares HTTP API.
+            timeout: Timeout in seconds for each request.
+            auth_token: Optional bearer token for authentication.
+        """
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.headers = {"Authorization": f"Bearer {auth_token}"} if auth_token else {}
+
+    def reset_simulation(self) -> None:
+        """
+        Sends a request to reset the current simulation state.
+        """
+        try:
+            response = httpx.post(
+                f"{self.base_url}/simulation/reset",
+                headers=self.headers,
+                timeout=self.timeout,
+            )
+            response.raise_for_status()
+        except httpx.RequestError as e:
+            raise ConnectionError(f"Could not reach Antares API: {e}") from e
+        except httpx.HTTPStatusError as e:
+            raise SimulationError(f"Reset failed: {e.response.text}") from e
+
+    def add_ship(self, ship: ShipConfig) -> None:
+        """
+        Sends a ship configuration to the simulation engine.
+
+        Args:
+            ship: A validated ShipConfig instance.
+        """
+        try:
+            response = httpx.post(
+                f"{self.base_url}/simulation/ships",
+                json=ship.model_dump(),
+                headers=self.headers,
+                timeout=self.timeout,
+            )
+            response.raise_for_status()
+        except httpx.RequestError as e:
+            raise ConnectionError(f"Could not reach Antares API: {e}") from e
+        except httpx.HTTPStatusError as e:
+            raise SimulationError(f"Add ship failed: {e.response.text}") from e

antares-python/src/antares/client/tcp.py

@@ -0,0 +1,52 @@
+import asyncio
+import json
+from collections.abc import AsyncIterator
+
+from antares.errors import SubscriptionError
+
+
+class TCPSubscriber:
+    """
+    Manages a TCP connection to the Antares simulation for real-time event streaming.
+    """
+
+    def __init__(self, host: str, port: int, reconnect: bool = True) -> None:
+        """
+        Initializes the TCP subscriber.
+
+        Args:
+            host: The hostname or IP of the TCP server.
+            port: The port number of the TCP server.
+            reconnect: Whether to automatically reconnect on disconnect.
+        """
+        self.host = host
+        self.port = port
+        self.reconnect = reconnect
+
+    async def subscribe(self) -> AsyncIterator[dict]:
+        """
+        Connects to the TCP server and yields simulation events as parsed dictionaries.
+        This is an infinite async generator until disconnected or cancelled.
+
+        Yields:
+            Parsed simulation events.
+        """
+        while True:
+            try:
+                reader, _ = await asyncio.open_connection(self.host, self.port)
+                while not reader.at_eof():
+                    line = await reader.readline()
+                    if line:
+                        yield json.loads(line.decode())
+            except (
+                ConnectionRefusedError,
+                asyncio.IncompleteReadError,
+                json.JSONDecodeError,
+            ) as e:
+                raise SubscriptionError(f"Failed to read from TCP stream: {e}") from e
+
+            if not self.reconnect:
+                break
+
+            # Wait before attempting to reconnect
+            await asyncio.sleep(1)

antares-python/src/antares/config.py

@@ -0,0 +1,18 @@
+from pydantic import BaseSettings, Field
+
+
+class AntaresSettings(BaseSettings):
+    """
+    Application-level configuration for the Antares Python client.
+    Supports environment variables and `.env` file loading.
+    """
+
+    base_url: str = Field(..., env="ANTARES_BASE_URL")
+    tcp_host: str = Field("localhost", env="ANTARES_TCP_HOST")
+    tcp_port: int = Field(9000, env="ANTARES_TCP_PORT")
+    timeout: float = Field(5.0, env="ANTARES_TIMEOUT")
+    auth_token: str | None = Field(None, env="ANTARES_AUTH_TOKEN")
+
+    class Config:
+        env_file = ".env"
+        case_sensitive = False

antares-python/src/antares/config_loader.py

@@ -0,0 +1,20 @@
+from pathlib import Path
+
+import tomli
+
+from antares.config import AntaresSettings
+
+
+def load_config(path: str | Path | None = None) -> AntaresSettings:
+    """Loads AntaresSettings from a TOML config file or defaults to .env + env vars."""
+    if path is None:
+        return AntaresSettings()
+
+    config_path = Path(path).expanduser()
+    if not config_path.exists():
+        raise FileNotFoundError(f"Config file not found: {config_path}")
+
+    with config_path.open("rb") as f:
+        data = tomli.load(f)
+
+    return AntaresSettings(**data.get("antares", {}))