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
```
