cogitan 0.1.0

CLI + SDK for the Cogitan Surrogates API — on-demand physics-simulation surrogate models.

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

pip install cogitan

This gives you both the cogitan command and the import cogitan SDK.

Set up your key (once)

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:

cogitan run thermal --in my_case.json --out result.json

my_case.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):

cogitan run thermal -p conductivity=50 -p grid_size=64

3. Piped from stdin:

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

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

pip install -e .                               # from this directory
COGITAN_BASE_URL=http://localhost:8000 cogitan models