Metadata-Version: 2.4
Name: cogitan
Version: 0.1.5
Summary: CLI + SDK for the Cogitan Surrogates API — on-demand physics-simulation surrogate models.
Project-URL: Homepage, https://cogitan.ai
Author: Cogitan
License: MIT
License-File: LICENSE
Keywords: api,fno,neural-operator,physics,simulation,surrogate
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
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** — run physics-simulation surrogate
models on demand over HTTP. No models, solvers, or GPUs on your machine: you send inputs,
our GPUs run a trained neural-operator surrogate, you get results back.

Cogitan is built for **volume** — sweeps of **thousands to hundreds of thousands** of
simulations, run in seconds. If you need one answer, run a solver. If you need a parameter
sweep, an optimization loop, or a design-space search, that's what this is for.

## The thermal surrogate (live today)

Transient 2-D heat conduction. A Fourier Neural Operator trained on synthetic finite-element
data (so no client data, no client IP touches the model):

- **~0.04% accuracy** — validation relative-L2 of 0.000409 vs the full FEM solver.
- **21.8× faster than FEM on CPU, 100×+ on GPU** — and it batches, so a whole sweep runs at once.
- **~500 simulations/second** on the Economy tier; a 50,000-case sweep in well under two minutes.
- **Valid envelope:** conductivity 1–100 W/(m·K), boundary temperature 273–373 K, 0–4 heat
  sources, on a 64×64 grid.

## 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.
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)

Point at a non-default endpoint with `cogitan login --base-url ...` or `COGITAN_BASE_URL`.

## Pick your speed (once)

Sweeps run on a **speed tier**. You choose the speed; we handle the hardware. Your choice is
saved like your API key and used for every sweep:

```bash
cogitan speed              # show the current tier
cogitan speed fast         # set it
```

| Tier | Feel | Price / simulation |
|---|---|---|
| `economy` | cheapest, far faster than CPU | $0.0005 |
| `fast` | several times faster | $0.0015 |
| `max` | fastest, for the biggest jobs | $0.003 |

Override per-run with `cogitan sweep --tier ...` or the `COGITAN_SPEED` env var.

Pricing is a **fixed quote** = price/sim × N, shown before you run and **held against your
prepaid balance**. You're charged only on success; failures are refunded automatically.
A 50,000-case Economy sweep is **$25**.

## Run a batch sweep

Not sure where to start? Get ready-made starter files for any model:

```bash
cogitan template thermal
# ✓ wrote sweep.json   ✓ wrote cases.json   ✓ wrote cases.csv
```

Two ways to describe the work:

**1. A sweep spec** — give parameter *ranges* and a count; we generate N cases by
Latin-hypercube sampling (compact, best for large N):

```bash
cogitan sweep thermal --spec sweep.json --out results.json
```
`sweep.json`:
```json
{
  "n": 50000,
  "params": { "conductivity": [1, 100] },
  "base": { "sources": [{"x": 0.5, "y": 0.5, "amplitude": 30000, "width": 0.08}] }
}
```
`params` entries that are `[lo, hi]` are swept; anything else is held fixed. `base` is merged
into every case. Add `"seed": 123` for reproducibility.

**2. An explicit list of cases** — one simulation per entry (your own design matrix),
as JSON **or CSV straight from a spreadsheet**:

```bash
cogitan sweep thermal --params cases.json --out results.json
cogitan sweep thermal --params cases.csv  --out results.csv     # Excel-friendly both ways
```
`cases.json`:
```json
[
  { "conductivity": 12, "sources": [{"x": 0.5, "y": 0.5, "amplitude": 30000, "width": 0.08}] },
  { "conductivity": 47, "sources": [{"x": 0.3, "y": 0.7, "amplitude": 25000, "width": 0.10}] }
]
```
`cases.csv` — one row per simulation, columns = field names (cells containing JSON
like `[...]` are parsed; empty cells are skipped):
```csv
conductivity,sources
12,"[{""x"":0.5,""y"":0.5,""amplitude"":30000,""width"":0.08}]"
47,
```
Fixed fields a CSV can't hold (nested sources/boundary shared by every case) go in a
small JSON file merged into every row: `--base base.json`.

**Results as a spreadsheet:** pass `--out results.csv` and the per-simulation results
flatten into columns (`param.conductivity, max_temperature, ...`) — opens directly in
Excel. `--out results.json` keeps the full JSON.

`cogitan sweep` submits the job, shows the quote, then polls until it finishes and writes the
results. To submit without waiting, add `--no-wait` and check on it later:

```bash
cogitan sweep thermal --spec sweep.json --no-wait
cogitan job <job_id> --out results.json
```

## Run a single case

For one-off predictions (small jobs), `cogitan run`:

```bash
cogitan run thermal --in case.json --out result.json     # from a file
cogitan run thermal -p conductivity=50                   # inline params (JSON-parsed)
echo '{"conductivity": 50}' | cogitan run thermal        # piped stdin
```

`cogitan describe thermal` prints the model's input schema.

## Commands

| Command | What it does |
|---|---|
| `cogitan login` / `logout` / `whoami` | Manage and check your saved API key |
| `cogitan speed [tier]` | Get or set your default speed tier |
| `cogitan template <model>` | Write ready-made starter files (sweep.json, cases.json, cases.csv) |
| `cogitan sweep <model>` | Run a batch sweep (`--spec`, or `--params` JSON/CSV; `--out` .json/.csv) |
| `cogitan job <id>` | Check a sweep's status / download its result |
| `cogitan run <model>` | Run a single prediction |
| `cogitan models` / `describe <model>` | List the catalog / show a model's input schema |
| `cogitan usage` | Current credit balance + pricing |
| `cogitan config` / `version` | Show settings / print the version |

Add `--help` to any command for details.

## Python SDK

```python
import cogitan

client = cogitan.Client()                      # key + speed from config/env automatically

# --- a batch sweep: submit and block until done ---
job = client.sweep("thermal", sweep={
    "n": 10000,
    "params": {"conductivity": [1, 100]},
    "base": {"sources": [{"x": 0.5, "y": 0.5, "amplitude": 30000, "width": 0.08}]},
}, tier="economy")
results = client.fetch_result(job)             # download the result JSON
print(results["sims_per_sec"])
for row in results["results"][:3]:             # one entry per simulation, params echoed
    print(row["params"]["conductivity"], row["max_temperature"])

# --- or drive the lifecycle yourself ---
job = client.submit_job("thermal", params=[{"conductivity": 12}, {"conductivity": 47}])
print(job["quote_usd"], job["balance_usd"])
final = client.wait_job(job["job_id"], on_poll=lambda j: print(j["status"]))

# --- a single case ---
result = client.run("thermal", {
    "conductivity": 50,
    "sources": [{"x": 0.5, "y": 0.5, "amplitude": 30000, "width": 0.08}],
})
result = client.thermal.predict(conductivity=50)        # namespaced sugar
```

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