# ORI Developer Portal

Use this file when you need the shortest reliable agent-facing guidance for integrating ORI.

## Two hosts (do not confuse them)

- **Developer portal (this site):** `https://dev.thynaptic.com` — machine-readable manifests only (`/llms.txt`, `/agent.json`, `/openapi.json`, `/tools.json`, `/requests.json`, MCP HTML). **No chat API here.** Same paths work on any mirror; this is the canonical public beacon.
- **ORI runtime (API):** `https://glm.thynaptic.com/v1` — all `POST /chat/completions`, capabilities, sessions, user skill prefs, etc. Always use the runtime base URL for authenticated calls.

Product docs for humans live on **docs.thynaptic.com**; they are not a substitute for these manifests when building integrations.

## Integration Manifests

Fetch from **dev.thynaptic.com** (or your deployed dev-portal origin) for technical precision:
- `https://dev.thynaptic.com/llms.txt` (This file) — High-level guidance.
- `https://dev.thynaptic.com/agent.json` — Product manifest and surface map.
- `https://dev.thynaptic.com/tools.json` — Full JSON Schemas for `pb_*` and `ask_ori` tools.
- `https://dev.thynaptic.com/openapi.json` — REST API contract (may lag the server; runtime behavior wins).

## Runtime

- **One key, anywhere:** the same `ori.<prefix>.<secret>` works for every integration — web, desktop, mobile, MCP, scripts, and first-party apps. No per-surface or per-product API key variants; pick surfaces with headers (`X-Ori-Context`, etc.), not different keys. Legacy `glm.*` keys still work until rotated.
- Base URL: `https://glm.thynaptic.com/v1`
- Auth: `Authorization: Bearer ori.<prefix>.<secret>`
- Self-hosted (typical VPS): use the public gateway at `http://localhost:8089/v1` (same paths as production). The cognitive backbone listens on `:8088` internally — keep it localhost-only behind your reverse proxy.
- Main chat endpoint: `POST /chat/completions`
- Skill discovery: `GET /modules` — lists builtin `.ori` skills and Go modules (for building UIs and toggles)
- **External / Claude-style skills on chat:** optional JSON field `ori_skills` with `enabled` (builtin ids) and `custom` (inline user skill bodies). Builtin ids must be allowed for the active surface overlay. Headers: `X-Ori-Skill` (comma-separated ids, merged into enabled for this request).
- Feedback endpoint: `POST /feedback` (submit roasts/lessons to improve persona)
- Default strong reasoning lane: `model: "oricli-oracle"`
- Response Metadata: Chat responses include a `meta` block with `provider` and `sass_factor`.
- Surface header: `X-Ori-Context`
- Session header: `X-Session-ID` (client-generated, used to track conversation history)
- **Timezone header**: `X-Timezone` — IANA timezone name (e.g. `America/New_York`). When set, ORI injects the user's local time into temporal awareness and can reason about schedules relative to their clock.
- **Environment headers**: `X-Env-OS`, `X-Env-PWD`, `X-Env-Project`, `X-Env-Shell` (Dynamic proprioception)

## OpenAI SDK Compatibility

ORI is a drop-in replacement for any client that accepts a configurable `base_url`. No code changes needed beyond swapping the base URL and key.

```python
import openai
client = openai.OpenAI(
    base_url="https://glm.thynaptic.com/v1",
    api_key="ori.<prefix>.<secret>",
)
response = client.chat.completions.create(
    model="oricli-oracle",
    messages=[{"role": "user", "content": "What should I focus on today?"}],
    extra_body={"profile": "studio_customer_comms"},
)
```

```typescript
import OpenAI from "openai";
const client = new OpenAI({ baseURL: "https://glm.thynaptic.com/v1", apiKey: "ori.<prefix>.<secret>" });
const res = await client.chat.completions.create({ model: "oricli-oracle", messages: [{ role: "user", content: "Review this plan." }] });
```

Streaming, tool use, and `GET /models` all work with the standard SDK. Use `extra_body` to pass ORI-specific fields (`profile`, `X-Ori-Context` surface, etc.).

## Chat History (REST)

Sessions are scoped per tenant + surface. **`X-Session-ID` must be set** on every chat request for history to record — if omitted, the message is processed but not stored and the session is not created. Generate a stable UUID per conversation and reuse it across turns.

**Behavior summary:**
- With `X-Session-ID`: message stored, session created/continued, retrievable via the PAD sessions endpoint
- Without `X-Session-ID`: stateless — no history written, no session entry created

Surfaces: `studio` | `dev` | `home` | `android` | `mobile`

## Resonance & Emotional Climate (Public, no auth)

ORI surfaces real-time affective state. These are public endpoints — no auth required.

- `GET /v1/eri` — Ecospheric Resonance Index: `eri`, `ers`, `pacing`, `volatility`, `coherence`, `musical_key`, `bpm`, ARTE cognitive state (`arte_state`, `arte_intensity`, `arte_palette`), drift detection. Used by UIs to drive accent color and surface tone.
- `GET /v1/aeci` — Aurora Emotional Climate Index: weekly climate snapshot — `index`, `category`, `stability_score`, `sentiment_momentum`, `ui_hue_shift`, `tone_bias`.

These feed the WebSocket `resonance_sync` and `sensory_sync` events. Poll if WebSocket is not available.

## Flow Companion (Ambient Reflection, Public, no auth)

- `GET /v1/flow/prompt` — next pending ambient reflection prompt, or `{"prompt": null, "pending": 0}` if none
- `POST /v1/flow/trigger` — manually fire a reflection trigger
- `POST /v1/flow/prompt/dismiss` — dismiss a prompt by ID (`{"id": "<prompt_id>"}`)

## Spaces (auth required, scope: `runtime:spaces`)

Spaces are tenant-scoped document collections for context injection.

- `GET /v1/spaces` — list spaces for the authenticated tenant
- `POST /v1/spaces` — create a space (`{"name": "...", "description": "..."}`)
- `DELETE /v1/spaces/:id` — delete a space
- `POST /v1/spaces/:id/documents` — upload a document to a space
- `GET /v1/spaces/:id/documents` — list documents in a space

ORI Home Spaces belong to the authenticated tenant key — one tenant cannot list or use another tenant's Spaces.

## Parallel Agent Dispatch (PAD, auth required)

Dispatch multiple agents in parallel and collect results. Best for fan-out workloads where independent subtasks can run concurrently.

- `POST /v1/pad/dispatch` — dispatch a batch of agents in parallel
- `GET /v1/pad/sessions` — list PAD sessions
- `GET /v1/pad/sessions/:id` — get a PAD session and its results
- `GET /v1/pad/stats` — throughput metrics

## Sovereign Goals — Tick-Controlled Agent Loops (auth required)

Unlike regular Goals which run autonomously to completion, Sovereign Goals are **step-by-step supervised loops** where each execution step requires an explicit tick. Use these when you need a human-in-the-loop or debuggable agentic workflow.

- `POST /v1/sovereign/goals` — create a sovereign goal
- `GET /v1/sovereign/goals` — list sovereign goals
- `GET /v1/sovereign/goals/:id` — get goal state
- `POST /v1/sovereign/goals/:id/tick` — advance the goal one step
- `DELETE /v1/sovereign/goals/:id` — cancel

**Regular Goals vs Sovereign Goals:**
| | Regular (`/v1/goals`) | Sovereign (`/v1/sovereign/goals`) |
|---|---|---|
| Execution | Autonomous — runs to completion | Tick-controlled — each step requires `POST /:id/tick` |
| Use case | Fire-and-forget long-horizon tasks | Supervised loops, step-debuggable workflows |

## Swarm (auth required)

- `POST /v1/swarm/run` — execute a named swarm operation (`{"operation": "<name>", "params": {...}}`)

## MCP (auth required)

ORI exposes a JSON-RPC 2.0 MCP endpoint for tool-calling agents:

- `POST /v1/mcp` — JSON-RPC 2.0 envelope (`jsonrpc`, `id`, `method`, `params`)

Supported methods: `tools/list`, `tools/call`. Use `tools/list` to discover the current tool set before calling.

## WebSocket Event Types (`GET /v1/ws`, no auth)

Connect to `wss://glm.thynaptic.com/v1/ws`. Receive JSON frames with a `type` field:

| Event | Key fields | Description |
|---|---|---|
| `resonance_sync` | `eri`, `ers`, `key`, `bpm` | Emotional Resonance Index, score, musical key, tempo |
| `sensory_sync` | `hex`, `opacity`, `pulse` | UI accent colour, opacity, pulse rate |
| `health_sync` | `cpu`, `ram`, `cognitive_health` | Substrate diagnostics and cognitive health label |
| `audio_sync` | `wav_b64` | Base64-encoded WAV from Affective Voice Synthesis |
| `curiosity_sync` | `target`, `priority` | Live epistemic foraging target and priority score |
| `agent_dispatch` | `action` | Signals an active capability/agent is running |
| `token` | `content` | Streaming token from an active generation |
| `done` | — | Generation complete |
| `reform_proposal` | `diff`, `auto_deploy` | ReformDaemon proposed code diff |
| `reform_rollback` | `reason`, `reverted_to` | Binary rollback event |

Async job completion (goals, enterprise learn, finetune) does **not** currently push a WS event — use the poll pattern on the job endpoints.

## Browser Automation (browserd, auth required)

- `GET /v1/browser/health`
- `POST /v1/browser/sessions` — create session
- `DELETE /v1/browser/sessions` — close session
- `POST /v1/browser/open` — navigate to URL
- `GET /v1/browser/snapshot` — DOM snapshot
- `POST /v1/browser/action` — interact (click, type, etc.)
- `POST /v1/browser/screenshot` — capture screenshot
- `POST /v1/browser/state/save` — persist browser state
- `POST /v1/browser/state/load` — restore browser state

## Task Platform (auth required)

Persistent, cross-session task DAGs with relational entity history. Tenant-scoped. Available to any surface or external integration.

**Step actions:** `research` | `fetch` | `summarize` | `compare` | `draft` | `generate` | `save` | `webhook`

Steps form a DAG via `depends_on` — dependency-free steps run in parallel. The execute endpoint runs the DAG and streams SSE step updates.

### Tasks
- `POST /v1/tasks` — create task (optional inline steps)
- `GET /v1/tasks` — list (`?status=&surface=&session_id=&limit=&offset=`)
- `GET /v1/tasks/:id` — get task + steps
- `PATCH /v1/tasks/:id` — update (`title`, `description`, `status`, `priority`, `surface`)
- `DELETE /v1/tasks/:id` — delete (cascades steps)
- `POST /v1/tasks/:id/steps` — append step
- `PATCH /v1/tasks/:id/steps/:step_id` — update step status/result
- `DELETE /v1/tasks/:id/steps/:step_id` — remove step
- `POST /v1/tasks/:id/execute` — run step DAG. Set `Accept: text/event-stream` for SSE. Each event: `{step_id, status, snippet}`. Final event: `{done: true, task: {...}}`
- `GET /v1/tasks/:id/execute` — poll execution status without triggering a run

### Entities (relational history backbone)

Entities are named real-world things (people, vendors, businesses) that recur across tasks. Recording events against them enables relational recall — "the plumber" resolves to a person with invoice history, past messages, and booking records.

- `POST /v1/entities` — upsert entity (`name`, `kind`, `aliases[]`)
- `GET /v1/entities` — list/search (`?search=&kind=&limit=`)
- `GET /v1/entities/:id` — get entity + full event history (`?event_limit=50`)
- `POST /v1/entities/:id/events` — record event (`kind`, `content`, `metadata`, `occurred_at`)

**Event kinds:** `message` | `invoice` | `booking` | `call` | `note` | `event`

**Entity kinds:** `person` | `business` | `vendor` | `account` | `unknown`

---

## Memory, Tools, and Identity (auth required)

- `GET /v1/memories` / `GET /v1/memories/knowledge` — memory fragments
- `GET /v1/sovereign/identity` / `PUT /v1/sovereign/identity` — active profile management
- `GET /v1/daemons` — background daemon health
- `GET /v1/tools` / `POST /v1/tools/plan` / `POST /v1/tools/execute-plan` — tool discovery and planning
- `POST /v1/vision/analyze` — image analysis via Oracle
- `POST /v1/images/generations` — image generation
- `POST /v1/workspaces/run` — agentic workspace task execution (SSE, requires `runtime:workspaces`)
- `POST /v1/agents/vibe` — natural language agent creation
- `POST /v1/ingest` / `POST /v1/ingest/web` — text and URL ingestion
- `POST /v1/documents/upload` / `GET /v1/documents` — document management
- `POST /v1/share` / `GET /v1/shares` — canvas share links
- Goals CRUD: `GET/POST /v1/goals` | `GET/PUT/DELETE /v1/goals/:id`
- Enterprise RAG: `POST /v1/enterprise/learn` | `GET /v1/enterprise/learn/:job_id` | `GET /v1/enterprise/knowledge/search` | `DELETE /v1/enterprise/knowledge`

## Public Endpoints (no auth)

- `GET /v1/health` — readiness probe
- `GET /v1/ws` — WebSocket event stream
- `GET /v1/metrics` — Prometheus metrics
- `GET /v1/eri` — live resonance state
- `GET /v1/aeci` — weekly emotional climate
- `GET /v1/flow/prompt` — ambient reflection prompt
- `POST /v1/flow/trigger` — manual reflection trigger
- `POST /v1/flow/prompt/dismiss` — dismiss reflection prompt
- `POST /v1/waitlist` — waitlist sign-up
- `POST /v1/app/register` — first-party app self-registration (requires internal `registration_token`, not a public flow)
- `GET /share/:id` — public share render (no /v1 prefix)

## Core Rule

Do not treat ORI like a raw model with a giant persona prompt.

ORI has a default persona: direct, confident, and a little sharp (The Big Sister).
Do not attempt to override it with system prompts that redefine her identity — they will be ignored.
Surface and working style selection is the correct lever for behavioral tuning.

Pass:

- the real user task
- the right surface
- an optional working style only when needed

Let ORI carry:

- identity
- routing
- memory
- product behavior

## Safe Default

Use:

- `model: "oricli-oracle"`
- `X-Ori-Context: <surface>`

Do not pass `profile` unless you want a specific lane.

If no profile is passed, ORI stays on her default baseline for that surface.

Plain chat requests go Oracle-first by default. Local SLMs are fully deprecated.

## Build Flow

1. Ingest manifests from `https://dev.thynaptic.com/` (this portal).
2. Point your HTTP client at the runtime base URL (`https://glm.thynaptic.com/v1`).
3. Acquire an ORI API key (`ori.<prefix>.<secret>`).
4. Select the surface and optional profile.
5. Set `X-Env-*` headers for environment awareness.
6. Use `POST /chat/completions`.
7. Add streaming only when needed.

Defaults:

- `model: "oricli-oracle"`
- `surface`: optional
- `profile`: optional

## Invariants

- ORI is always the entrypoint.
- Oracle is mandatory; local SLMs are deprecated.
- Public default model is `oricli-oracle`.
- Surface modifies behavior, not identity.
- Profile is optional and only works when it belongs to the chosen surface.

## Failure Modes

- Missing auth → `401`
- Missing required scope → `403`
- Invalid surface → ignored
- Invalid profile → ignored
- Internal-only lanes → not accessible via the public API

## Scopes

- `runtime:chat`
- `runtime:models`
- `runtime:spaces`
- `runtime:workspaces`
- `runtime:pocketbase` — direct collection and record management

First-party app registration is product-scoped:

- `POST /app/register` is for trusted first-party bootstrap only
- it requires an internal `registration_token`
- it is not a public self-serve developer key flow

- `ORI Home` → `runtime:chat`, `runtime:models`, `runtime:spaces`, `runtime:workspaces`
- `ORI Studio` / `ORI Mobile` → `runtime:chat`, `runtime:models`
- `ORI Dev` → `runtime:chat`, `runtime:models`

Spaces are tenant-scoped:

- ORI Home Spaces belong to the authenticated tenant key
- one tenant cannot list or use another tenant's Spaces
- legacy unowned Spaces are hidden until explicitly migrated