cogitan 0.1.0__tar.gz

cogitan-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: cogitan
+Version: 0.1.0
+Summary: CLI + SDK for the Cogitan Surrogates API — on-demand physics-simulation surrogate models.
+Project-URL: Homepage, https://cogitan.ai
+Project-URL: Documentation, https://docs.cogitan.ai
+Author: Cogitan
+Keywords: api,fno,neural-operator,physics,simulation,surrogate
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# cogitan
+
+CLI + Python SDK for the **Cogitan Surrogates API** — call on-demand physics-simulation
+surrogate models (heat, water, contaminant transport, materials, …) over HTTP. No models or
+GPUs on your machine: you send inputs, the server runs the surrogate, you get results in ms.
+
+## Install
+
+```bash
+pip install cogitan
+```
+
+This gives you both the `cogitan` command and the `import cogitan` SDK.
+
+## Set up your key (once)
+
+```bash
+cogitan login
+# Paste your Cogitan API key: cog_sk_********
+# ✓ Saved to ~/.cogitan/config.json
+```
+
+Your key is stored in `~/.cogitan/config.json` (locked to your user) and used automatically
+forever. Key resolution order, first match wins:
+
+1. `--api-key` flag (one-off)
+2. `COGITAN_API_KEY` env var (CI / containers)
+3. `~/.cogitan/config.json` (the normal case)
+
+To point at a non-default endpoint (e.g. local testing): `cogitan login --base-url http://localhost:8000`,
+or set `COGITAN_BASE_URL`.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `cogitan login` | Save your API key (prompts; persists forever) |
+| `cogitan logout` | Delete the saved key |
+| `cogitan whoami` | Show the active key (masked), endpoint, connection status |
+| `cogitan models` | List the catalog of available models |
+| `cogitan describe <model>` | Show a model's input schema (what fields to send) |
+| `cogitan run <model>` | Run a prediction (see below) |
+| `cogitan usage` | Current billing-period usage |
+| `cogitan config` | Show config file location + settings |
+| `cogitan version` | Print the version |
+
+Add `--help` to any command for details.
+
+## Running models on your own inputs
+
+Three ways to provide inputs — mix and match:
+
+**1. From a JSON file:**
+```bash
+cogitan run thermal --in my_case.json --out result.json
+```
+`my_case.json`:
+```json
+{
+  "grid_size": 64,
+  "conductivity": 50,
+  "sources": [{"x": 0.5, "y": 0.5, "amplitude": 30000, "width": 0.08}],
+  "boundary": {"left": {"type": "dirichlet", "value": 300}, "right": {"type": "dirichlet", "value": 350}}
+}
+```
+
+**2. Inline params** (repeatable; values are JSON-parsed, so numbers/lists/objects work):
+```bash
+cogitan run thermal -p conductivity=50 -p grid_size=64
+```
+
+**3. Piped from stdin:**
+```bash
+cat my_case.json | cogitan run thermal
+echo '{"conductivity": 50}' | cogitan run thermal --out result.json
+```
+
+Not sure what a model wants? `cogitan describe thermal` prints its input schema.
+Without `--out`, the result prints to stdout (pipe it into `jq`, etc.).
+
+## Python SDK
+
+```python
+import cogitan
+
+client = cogitan.Client()                     # key from config/env automatically
+print(client.models())                         # ["thermal", "groundwater", "contaminant", "mlip", ...]
+
+# run a model
+result = client.run("thermal", {
+    "conductivity": 50,
+    "sources": [{"x": 0.5, "y": 0.5, "amplitude": 30000, "width": 0.08}],
+    "boundary": {"left": {"type": "dirichlet", "value": 300}},
+})
+print(result["max_temperature"])
+
+# namespaced sugar
+result = client.thermal.predict(conductivity=50, sources=[...])
+
+# one-liner with the default client
+result = cogitan.run("thermal", {"conductivity": 50})
+```
+
+Errors raise `cogitan.APIError` (with `.status_code`, `.code`, `.request_id`) or
+`cogitan.NotConfigured` if no key is set.
+
+## Local development
+
+```bash
+pip install -e .                               # from this directory
+COGITAN_BASE_URL=http://localhost:8000 cogitan models
+```

cogitan-0.1.0/README.md

@@ -0,0 +1,112 @@
+# cogitan
+
+CLI + Python SDK for the **Cogitan Surrogates API** — call on-demand physics-simulation
+surrogate models (heat, water, contaminant transport, materials, …) over HTTP. No models or
+GPUs on your machine: you send inputs, the server runs the surrogate, you get results in ms.
+
+## Install
+
+```bash
+pip install cogitan
+```
+
+This gives you both the `cogitan` command and the `import cogitan` SDK.
+
+## Set up your key (once)
+
+```bash
+cogitan login
+# Paste your Cogitan API key: cog_sk_********
+# ✓ Saved to ~/.cogitan/config.json
+```
+
+Your key is stored in `~/.cogitan/config.json` (locked to your user) and used automatically
+forever. Key resolution order, first match wins:
+
+1. `--api-key` flag (one-off)
+2. `COGITAN_API_KEY` env var (CI / containers)
+3. `~/.cogitan/config.json` (the normal case)
+
+To point at a non-default endpoint (e.g. local testing): `cogitan login --base-url http://localhost:8000`,
+or set `COGITAN_BASE_URL`.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `cogitan login` | Save your API key (prompts; persists forever) |
+| `cogitan logout` | Delete the saved key |
+| `cogitan whoami` | Show the active key (masked), endpoint, connection status |
+| `cogitan models` | List the catalog of available models |
+| `cogitan describe <model>` | Show a model's input schema (what fields to send) |
+| `cogitan run <model>` | Run a prediction (see below) |
+| `cogitan usage` | Current billing-period usage |
+| `cogitan config` | Show config file location + settings |
+| `cogitan version` | Print the version |
+
+Add `--help` to any command for details.
+
+## Running models on your own inputs
+
+Three ways to provide inputs — mix and match:
+
+**1. From a JSON file:**
+```bash
+cogitan run thermal --in my_case.json --out result.json
+```
+`my_case.json`:
+```json
+{
+  "grid_size": 64,
+  "conductivity": 50,
+  "sources": [{"x": 0.5, "y": 0.5, "amplitude": 30000, "width": 0.08}],
+  "boundary": {"left": {"type": "dirichlet", "value": 300}, "right": {"type": "dirichlet", "value": 350}}
+}
+```
+
+**2. Inline params** (repeatable; values are JSON-parsed, so numbers/lists/objects work):
+```bash
+cogitan run thermal -p conductivity=50 -p grid_size=64
+```
+
+**3. Piped from stdin:**
+```bash
+cat my_case.json | cogitan run thermal
+echo '{"conductivity": 50}' | cogitan run thermal --out result.json
+```
+
+Not sure what a model wants? `cogitan describe thermal` prints its input schema.
+Without `--out`, the result prints to stdout (pipe it into `jq`, etc.).
+
+## Python SDK
+
+```python
+import cogitan
+
+client = cogitan.Client()                     # key from config/env automatically
+print(client.models())                         # ["thermal", "groundwater", "contaminant", "mlip", ...]
+
+# run a model
+result = client.run("thermal", {
+    "conductivity": 50,
+    "sources": [{"x": 0.5, "y": 0.5, "amplitude": 30000, "width": 0.08}],
+    "boundary": {"left": {"type": "dirichlet", "value": 300}},
+})
+print(result["max_temperature"])
+
+# namespaced sugar
+result = client.thermal.predict(conductivity=50, sources=[...])
+
+# one-liner with the default client
+result = cogitan.run("thermal", {"conductivity": 50})
+```
+
+Errors raise `cogitan.APIError` (with `.status_code`, `.code`, `.request_id`) or
+`cogitan.NotConfigured` if no key is set.
+
+## Local development
+
+```bash
+pip install -e .                               # from this directory
+COGITAN_BASE_URL=http://localhost:8000 cogitan models
+```

cogitan-0.1.0/cogitan/__init__.py

@@ -0,0 +1,36 @@
+"""Cogitan Surrogates API — Python SDK + CLI.
+
+    import cogitan
+    client = cogitan.Client()                 # reads key from ~/.cogitan/config.json or env
+    print(client.models())
+    result = client.run("thermal", {...})
+    # or:
+    result = cogitan.run("thermal", {...})
+"""
+
+from .client import Client
+from .errors import CogitanError, NotConfigured, APIError
+
+__version__ = "0.1.0"
+
+_default_client = None
+
+
+def _default() -> "Client":
+    global _default_client
+    if _default_client is None:
+        _default_client = Client()
+    return _default_client
+
+
+def run(model: str, inputs: dict | None = None, **kwargs):
+    """Convenience: cogitan.run("thermal", {...}) or cogitan.run("thermal", conductivity=50)."""
+    return _default().run(model, inputs if inputs is not None else kwargs)
+
+
+def models():
+    """List the catalog of available models."""
+    return _default().models()
+
+
+__all__ = ["Client", "run", "models", "CogitanError", "NotConfigured", "APIError", "__version__"]

cogitan-0.1.0/cogitan/cli.py

@@ -0,0 +1,187 @@
+"""Cogitan CLI — `cogitan <command>`."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import List, Optional
+
+import typer
+
+from . import __version__
+from . import config as _config
+from .client import Client
+from .errors import APIError, CogitanError, NotConfigured
+
+app = typer.Typer(
+    add_completion=False,
+    no_args_is_help=True,
+    help="Cogitan Surrogates API — run physics-simulation surrogate models on demand.",
+)
+
+
+def _client() -> Client:
+    try:
+        return Client()
+    except NotConfigured as e:
+        typer.secho(str(e), fg=typer.colors.RED)
+        raise typer.Exit(1)
+
+
+def _mask(key: str) -> str:
+    return (key[:12] + "…") if key and len(key) > 12 else (key or "")
+
+
+# --------------------------------------------------------------------------- auth
+
+@app.command()
+def login(
+    api_key: Optional[str] = typer.Option(None, "--api-key", help="API key (omit to be prompted)"),
+    base_url: Optional[str] = typer.Option(None, "--base-url", help="override the API base URL"),
+):
+    """Save your API key. Persists in ~/.cogitan/config.json — set it once, use it forever."""
+    if not api_key:
+        api_key = typer.prompt("Paste your Cogitan API key", hide_input=True)
+    api_key = api_key.strip()
+
+    # best-effort validation
+    try:
+        Client(api_key=api_key, base_url=base_url).health()
+    except APIError as e:
+        if e.status_code in (401, 403):
+            typer.secho("That key was rejected by the server.", fg=typer.colors.RED)
+            raise typer.Exit(1)
+        typer.secho(f"Note: couldn't verify the key ({e}). Saving anyway.", fg=typer.colors.YELLOW)
+    except CogitanError as e:
+        typer.secho(f"Note: couldn't reach the server ({e}). Saving anyway.", fg=typer.colors.YELLOW)
+
+    _config.set_api_key(api_key, base_url)
+    typer.secho(f"✓ Saved to {_config.CONFIG_FILE}", fg=typer.colors.GREEN)
+
+
+@app.command()
+def logout():
+    """Delete the saved API key."""
+    if _config.clear():
+        typer.secho("✓ Logged out.", fg=typer.colors.GREEN)
+    else:
+        typer.echo("No saved key.")
+
+
+@app.command()
+def whoami():
+    """Show the active key (masked), endpoint, and connection status."""
+    key = _config.resolve_api_key()
+    if not key:
+        typer.secho("Not logged in. Run `cogitan login`.", fg=typer.colors.RED)
+        raise typer.Exit(1)
+    typer.echo(f"key:      {_mask(key)}")
+    typer.echo(f"endpoint: {_config.resolve_base_url()}")
+    try:
+        _client().health()
+        typer.secho("status:   connected ✓", fg=typer.colors.GREEN)
+    except CogitanError as e:
+        typer.secho(f"status:   {e}", fg=typer.colors.YELLOW)
+
+
+# --------------------------------------------------------------------------- catalog
+
+@app.command()
+def models(json_out: bool = typer.Option(False, "--json", help="raw JSON output")):
+    """List the catalog of available models."""
+    ms = _client().models()
+    if json_out:
+        typer.echo(json.dumps(ms, indent=2))
+        return
+    if not ms:
+        typer.echo("(no models)")
+        return
+    for m in ms:
+        avail = "available" if m.get("available") else "unavailable"
+        typer.echo(f"  {str(m.get('name')):<16} {avail:<12} {m.get('description') or ''}")
+
+
+@app.command()
+def describe(model: str = typer.Argument(..., help="model name, e.g. thermal")):
+    """Show a model's input schema (what fields to send)."""
+    m = _client().describe(model)
+    typer.echo(json.dumps(m.get("input_schema") or m, indent=2))
+
+
+@app.command()
+def run(
+    model: str = typer.Argument(..., help="model name, e.g. thermal"),
+    in_: Optional[str] = typer.Option(None, "--in", "-i", help="JSON input file ('-' for stdin)"),
+    out: Optional[Path] = typer.Option(None, "--out", "-o", help="write JSON result to this file"),
+    param: List[str] = typer.Option(None, "--param", "-p", help="inline input key=value (repeatable)"),
+):
+    """Run a model. Inputs come from --in (file/stdin), piped stdin, and/or --param overrides."""
+    inputs: dict = {}
+
+    if in_ is not None:
+        text = sys.stdin.read() if in_ == "-" else Path(in_).read_text()
+        inputs = json.loads(text) if text.strip() else {}
+    elif not sys.stdin.isatty():
+        piped = sys.stdin.read().strip()
+        if piped:
+            inputs = json.loads(piped)
+
+    for p in (param or []):
+        if "=" not in p:
+            typer.secho(f"bad --param '{p}' (expected key=value)", fg=typer.colors.RED)
+            raise typer.Exit(1)
+        k, v = p.split("=", 1)
+        try:
+            inputs[k] = json.loads(v)   # coerce numbers / bools / lists / json objects
+        except Exception:
+            inputs[k] = v               # fall back to a plain string
+
+    try:
+        result = _client().run(model, inputs)
+    except APIError as e:
+        typer.secho(str(e), fg=typer.colors.RED)
+        raise typer.Exit(1)
+
+    text = json.dumps(result, indent=2)
+    if out is not None:
+        Path(out).write_text(text)
+        typer.secho(f"✓ wrote {out}", fg=typer.colors.GREEN)
+    else:
+        typer.echo(text)
+
+
+# --------------------------------------------------------------------------- account / meta
+
+@app.command()
+def usage():
+    """Show your current billing-period usage."""
+    try:
+        typer.echo(json.dumps(_client().usage(), indent=2))
+    except APIError as e:
+        if e.status_code == 404:
+            typer.secho("Usage endpoint not available yet — see the web dashboard.",
+                        fg=typer.colors.YELLOW)
+        else:
+            typer.secho(str(e), fg=typer.colors.RED)
+            raise typer.Exit(1)
+
+
+@app.command()
+def config():
+    """Show the config file location and current settings."""
+    typer.echo(f"config file: {_config.CONFIG_FILE}")
+    data = _config.load()
+    if "api_key" in data:
+        data = {**data, "api_key": _mask(data["api_key"])}
+    typer.echo(json.dumps(data, indent=2))
+
+
+@app.command()
+def version():
+    """Print the cogitan version."""
+    typer.echo(__version__)
+
+
+if __name__ == "__main__":
+    app()

cogitan-0.1.0/cogitan/client.py

@@ -0,0 +1,99 @@
+"""The Cogitan SDK — a thin HTTP client over the Surrogates API gateway."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from . import config as _config
+from .errors import APIError, NotConfigured
+
+_USER_AGENT = "cogitan-python/0.1.0"
+
+
+class _ModelProxy:
+    """Sugar so `client.thermal.predict(conductivity=50)` == `client.run("thermal", {...})`."""
+
+    def __init__(self, client: "Client", model: str):
+        self._client = client
+        self._model = model
+
+    def predict(self, **inputs) -> dict:
+        return self._client.run(self._model, inputs)
+
+
+class Client:
+    """Talks to the Cogitan gateway with your API key.
+
+    Args:
+        api_key: overrides the resolved key (else env / config file).
+        base_url: overrides the API base URL (else env / config / default).
+    """
+
+    def __init__(self, api_key: str | None = None, base_url: str | None = None, timeout: float = 60.0):
+        key = _config.resolve_api_key(api_key)
+        if not key:
+            raise NotConfigured()
+        self.api_key = key
+        self.base_url = _config.resolve_base_url(base_url).rstrip("/")
+        self._http = httpx.Client(
+            timeout=timeout,
+            headers={"Authorization": f"Bearer {key}", "User-Agent": _USER_AGENT},
+        )
+
+    # -------------------------------------------------------------- lifecycle
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+    # -------------------------------------------------------------- transport
+    def _request(self, method: str, path: str, json: Any = None) -> Any:
+        try:
+            r = self._http.request(method, self.base_url + path, json=json)
+        except httpx.HTTPError as e:
+            raise APIError(0, "connection_error", f"could not reach {self.base_url}: {e}")
+        if r.status_code >= 400:
+            code = message = request_id = None
+            try:
+                err = r.json().get("error", {})
+                code, message, request_id = err.get("code"), err.get("message"), err.get("request_id")
+            except Exception:
+                message = (r.text or "")[:300]
+            raise APIError(r.status_code, code, message, request_id)
+        return r.json() if r.content else {}
+
+    # -------------------------------------------------------------- endpoints
+    def health(self) -> dict:
+        return self._request("GET", "/health")
+
+    def models(self) -> list[dict]:
+        """List the catalog: [{name, available, description, input_schema}, ...]."""
+        return self._request("GET", "/v1/models").get("models", [])
+
+    def describe(self, model: str) -> dict:
+        """Full metadata (incl. input_schema) for one model."""
+        for m in self.models():
+            if m.get("name") == model:
+                return m
+        raise APIError(404, "not_found", f"model '{model}' not found in the catalog")
+
+    def run(self, model: str, inputs: dict | None = None) -> dict:
+        """Run a prediction. Returns the model's response dict."""
+        return self._request("POST", f"/v1/models/{model}/predict", json=inputs or {})
+
+    def usage(self) -> dict:
+        """Current billing-period usage."""
+        return self._request("GET", "/v1/usage")
+
+    # -------------------------------------------------------------- sugar
+    def __getattr__(self, name: str) -> _ModelProxy:
+        # only reached for unknown attributes; enables client.<model>.predict(...)
+        if name.startswith("_"):
+            raise AttributeError(name)
+        return _ModelProxy(self, name)

cogitan-0.1.0/cogitan/config.py

@@ -0,0 +1,73 @@
+"""Config + credential resolution.
+
+API-key resolution order (first match wins):
+    1. explicit api_key argument / --api-key flag
+    2. COGITAN_API_KEY environment variable        (CI, containers, temporary)
+    3. ~/.cogitan/config.json                       (written by `cogitan login` — the normal case)
+
+So a user runs `cogitan login` once and the key persists forever, while CI can override via env.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+from pathlib import Path
+
+CONFIG_DIR = Path.home() / ".cogitan"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+DEFAULT_BASE_URL = "https://api.cogitan.ai"
+
+ENV_API_KEY = "COGITAN_API_KEY"
+ENV_BASE_URL = "COGITAN_BASE_URL"
+
+
+def load() -> dict:
+    if CONFIG_FILE.exists():
+        try:
+            return json.loads(CONFIG_FILE.read_text())
+        except Exception:
+            return {}
+    return {}
+
+
+def save(data: dict) -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    CONFIG_FILE.write_text(json.dumps(data, indent=2))
+    try:
+        # 0600 — owner read/write only (best-effort; no-op on some Windows filesystems)
+        CONFIG_FILE.chmod(stat.S_IRUSR | stat.S_IWUSR)
+    except Exception:
+        pass
+
+
+def set_api_key(api_key: str, base_url: str | None = None) -> None:
+    data = load()
+    data["api_key"] = api_key
+    if base_url:
+        data["base_url"] = base_url
+    save(data)
+
+
+def clear() -> bool:
+    if CONFIG_FILE.exists():
+        CONFIG_FILE.unlink()
+        return True
+    return False
+
+
+def resolve_api_key(explicit: str | None = None) -> str | None:
+    if explicit:
+        return explicit
+    if os.environ.get(ENV_API_KEY):
+        return os.environ[ENV_API_KEY]
+    return load().get("api_key")
+
+
+def resolve_base_url(explicit: str | None = None) -> str:
+    if explicit:
+        return explicit
+    if os.environ.get(ENV_BASE_URL):
+        return os.environ[ENV_BASE_URL]
+    return load().get("base_url") or DEFAULT_BASE_URL

cogitan-0.1.0/cogitan/errors.py

@@ -0,0 +1,31 @@
+"""Exceptions for the Cogitan client."""
+
+from __future__ import annotations
+
+
+class CogitanError(Exception):
+    """Base class for all Cogitan client errors."""
+
+
+class NotConfigured(CogitanError):
+    """No API key available."""
+
+    def __init__(self, message: str | None = None):
+        super().__init__(
+            message
+            or "No API key found. Run `cogitan login` (or set the COGITAN_API_KEY env var)."
+        )
+
+
+class APIError(CogitanError):
+    """The API returned an error (or could not be reached)."""
+
+    def __init__(self, status_code: int, code: str | None = None,
+                 message: str | None = None, request_id: str | None = None):
+        self.status_code = status_code
+        self.code = code
+        self.request_id = request_id
+        text = f"[{status_code}] {code or 'error'}: {message or ''}".rstrip()
+        if request_id:
+            text += f"  (request_id={request_id})"
+        super().__init__(text)

cogitan-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cogitan"
+version = "0.1.0"
+description = "CLI + SDK for the Cogitan Surrogates API — on-demand physics-simulation surrogate models."
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [{ name = "Cogitan" }]
+keywords = ["surrogate", "simulation", "physics", "neural-operator", "fno", "api"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Intended Audience :: Science/Research",
+]
+dependencies = [
+  "typer>=0.12",
+  "httpx>=0.27",
+]
+
+[project.scripts]
+cogitan = "cogitan.cli:app"
+
+[project.urls]
+Homepage = "https://cogitan.ai"
+Documentation = "https://docs.cogitan.ai"
+
+[tool.hatch.build.targets.wheel]
+packages = ["cogitan"]