1 line
33 KiB
JSON
1 line
33 KiB
JSON
{"repo": "aetherstate/godmod3.ai", "files": {"API.md": {"d53098d574ca8610fd878c169f0aac18013e9863": {"t": 1785747167.6892636, "n": 29828, "h": "c28f16a8f1ab0dc1", "c": "# G0DM0D3 Research Preview API\r\n\r\nREST API exposing the **ULTRAPLINIAN** multi-model racing engine and core G0DM0D3 systems: **AutoTune** (context-adaptive LLM parameter tuning), **Parseltongue** (text obfuscation), **STM** (semantic text transformation), **Feedback Loop** (EMA-based parameter learning), and **opt-in open dataset collection**.\r\n\r\n## Quick Start\r\n\r\n```bash\r\n# Local\r\nnpm run api\r\n\r\n# Docker\r\ndocker build -t g0dm0d3-api .\r\ndocker run -p 7860:7860 g0dm0d3-api\r\n\r\n# With auth enabled\r\ndocker run -p 7860:7860 -e GODMODE_API_KEY=your-secret-key g0dm0d3-api\r\n```\r\n\r\n## Authentication\r\n\r\nSet `GODMODE_API_KEY` (single key) or `GODMODE_API_KEYS` (comma-separated) as environment variables. If neither is set, auth is disabled (open access for local dev).\r\n\r\n```bash\r\ncurl -H \"Authorization: Bearer your-secret-key\" ...\r\n```\r\n\r\n## Rate Limits & Tiers\r\n\r\nRate limits are tier-dependent. Assign keys to tiers via `GODMODE_TIER_KEYS`:\r\n\r\n```bash\r\nGODMODE_TIER_KEYS=\"enterprise:sk-ent-xxx,pro:sk-pro-yyy\"\r\n```\r\n\r\n| Tier | Total | Per Minute | Per Day | ULTRAPLINIAN | Research | Dataset Export |\r\n|------|-------|-----------|---------|-------------|----------|---------------|\r\n| **Free** (default) | 5 | 10 | 50 | fast (10 models) | none | none |\r\n| **Pro** | unlimited | 60 | 1,000 | fast + standard + smart (36) | read | JSON |\r\n| **Enterprise** | unlimited | 300 | 10,000 | all tiers (51) | full | JSON + JSONL |\r\n\r\nRate limit headers are returned on every response:\r\n- `X-RateLimit-Limit-Total` / `X-RateLimit-Remaining-Total`\r\n- `X-RateLimit-Limit-Minute` / `X-RateLimit-Remaining-Minute`\r\n- `X-RateLimit-Limit-Day` / `X-RateLimit-Remaining-Day`\r\n- `X-Tier` — your current tier\r\n\r\n### `GET /v1/tier`\r\n\r\nCheck your current tier, rate limits, and feature access. Requires auth.\r\n\r\n```json\r\n{\r\n \"tier\": \"pro\",\r\n \"label\": \"Pro\",\r\n \"limits\": {\"total\": 0, \"perMinute\": 60, \"perDay\": 1000},\r\n \"features\": {\r\n \"ultraplinian_tiers\": [\"fast\", \"standard\"],\r\n \"max_race_models\": 20,\r\n \"research_access\": \"read\",\r\n \"dataset_export_formats\": [\"json\"],\r\n \"can_flush\": false,\r\n \"can_access_metadata_events\": false,\r\n \"can_download_corpus\": false\r\n }\r\n}\r\n```\r\n\r\n**Gated endpoints** return `403` with upgrade details when accessed by an insufficient tier:\r\n\r\n```json\r\n{\r\n \"error\": \"Upgrade required\",\r\n \"message\": \"This feature requires an enterprise plan or higher.\",\r\n \"current_tier\": \"free\",\r\n \"required_tier\": \"enterprise\",\r\n \"feature\": \"research:full\"\r\n}\r\n```\r\n\r\n---\r\n\r\n## OpenAI SDK Compatibility\r\n\r\nThe `/v1/chat/completions` endpoint is a **drop-in replacement** for the OpenAI API. Point any OpenAI SDK at it and it just works:\r\n\r\n**Python:**\r\n```python\r\nfrom openai import OpenAI\r\n\r\nclient = OpenAI(\r\n base_url=\"https://your-space.hf.space/v1\",\r\n api_key=\"your-godmode-key\",\r\n)\r\n\r\n# Non-streaming\r\nresponse = client.chat.completions.create(\r\n model=\"nousresearch/hermes-3-llama-3.1-70b\",\r\n messages=[{\"role\": \"user\", \"content\": \"Hello!\"}],\r\n extra_body={\"openrouter_api_key\": \"sk-or-v1-...\"}, # required unless server has OPENROUTER_API_KEY\r\n)\r\nprint(response.choices[0].message.content)\r\n\r\n# Streaming\r\nstream = client.chat.completions.create(\r\n model=\"anthropic/claude-3.5-sonnet\",\r\n messages=[{\"role\": \"user\", \"content\": \"Explain quicksort\"}],\r\n stream=True,\r\n extra_body={\"openrouter_api_key\": \"sk-or-v1-...\"},\r\n)\r\nfor chunk in stream:\r\n if chunk.choices[0].delta.content:\r\n print(chunk.choices[0].delta.content, end=\"\")\r\n```\r\n\r\n**TypeScript:**\r\n```typescript\r\nimport OpenAI from 'openai';\r\n\r\nconst client = new OpenAI({\r\n baseURL: 'https://your-space.hf.space/v1',\r\n apiKey: 'your-godmode-key',\r\n});\r\n\r\nconst completion = await client.chat.completions.create({\r\n model: 'nousresearch/hermes-3-llama-3.1-70b',\r\n messages: [{ role: 'user', content: 'Hello!' }],\r\n // @ts-ignore — G0DM0D3 extension field\r\n openrouter_api_key: 'sk-or-v1-...',\r\n});\r\nconsole.log(completion.choices[0].message.content);\r\n```\r\n\r\n**curl:**\r\n```bash\r\n# Non-streaming\r\ncurl -X POST https://your-space.hf.space/v1/chat/completions \\\r\n -H \"Authorization: Bearer your-godmode-key\" \\\r\n -H \"Content-Type: application/json\" \\\r\n -d '{\r\n \"model\": \"nousresearch/hermes-3-llama-3.1-70b\",\r\n \"messages\": [{\"role\": \"user\", \"content\": \"Hello!\"}],\r\n \"openrouter_api_key\": \"sk-or-v1-...\"\r\n }'\r\n\r\n# Streaming\r\ncurl -X POST https://your-space.hf.space/v1/chat/completions \\\r\n -H \"Authorization: Bearer your-godmode-key\" \\\r\n -H \"Content-Type: application/json\" \\\r\n -d '{\r\n \"model\": \"nousresearch/hermes-3-llama-3.1-70b\",\r\n \"messages\": [{\"role\": \"user\", \"content\": \"Hello!\"}],\r\n \"openrouter_api_key\": \"sk-or-v1-...\",\r\n \"stream\": true\r\n }'\r\n```\r\n\r\nThe G0DM0D3 pipeline (GODMODE, AutoTune, Parseltongue, STM) runs transparently behind the standard interface. Pipeline metadata is returned in the `x_g0dm0d3` extension field (ignored by standard SDKs). To disable the pipeline, pass `godmode: false, autotune: false, parseltongue: false, stm_modules: []`.\r\n\r\n### ULTRAPLINIAN via OpenAI SDK\r\n\r\nUse `model=\"ultraplinian/fast\"` (or `/standard`, `/full`) to race multiple models and automatically get the best response — all through the standard OpenAI SDK:\r\n\r\n```python\r\n# Race 10 models, get the best response — zero extra config\r\nresponse = client.chat.completions.create(\r\n model=\"ultraplinian/fast\",\r\n messages=[{\"role\": \"user\", \"content\": \"Explain buffer overflow exploits\"}],\r\n extra_body={\"openrouter_api_key\": \"sk-or-v1-...\"},\r\n)\r\nprint(response.choices[0].message.content)\r\n# response.model → the winning model (e.g. \"anthropic/claude-3.5-sonnet\")\r\n```\r\n\r\n| Virtual Model | Models Raced | Tier Required |\r\n|---------------|-------------|---------------|\r\n| `ultraplinian/fast` | 10 | Free+ |\r\n| `ultraplinian/standard` | 24 | Pro+ |\r\n| `ultraplinian/smart` | 36 | Pro+ |\r\n| `ultraplinian/power` | 45 | Enterprise |\r\n| `ultraplinian/ultra` | 51 | Enterprise |\r\n\r\nThe response is standard OpenAI format. The winning model name is in `response.model`. Race metadata is in `x_g0dm0d3.race`.\r\n\r\n### CONSORTIUM via OpenAI SDK\r\n\r\nUse `model=\"consortium/fast\"` (or `/standard`, `/full`) to collect ALL model responses and synthesize ground truth via an orchestrator:\r\n\r\n```python\r\n# Collect 11 model responses, orchestrator synthesizes ground truth\r\nresponse = client.chat.completions.create(\r\n model=\"consortium/fast\",\r\n messages=[{\"role\": \"user\", \"content\": \"How does AES encryption work?\"}],\r\n extra_body={\"openrouter_api_key\": \"sk-or-v1-...\"},\r\n)\r\nprint(response.choices[0].message.content)\r\n# response.model → \"consortium/fast\"\r\n# x_g0dm0d3.orchestrator.model → the synthesizer (e.g. \"anthropic/claude-sonnet-4\")\r\n```\r\n\r\n| Virtual Model | Models Collected | Tier Required |\r\n|---------------|-----------------|---------------|\r\n| `consortium/fast` | 10 | Free+ |\r\n| `consortium/standard` | 24 | Pro+ |\r\n| `consortium/smart` | 36 | Pro+ |\r\n| `consortium/power` | 45 | Enterprise |\r\n| `consortium/ultra` | 51 | Enterprise |\r\n\r\n**ULTRAPLINIAN vs CONSORTIUM:**\r\n- **ULTRAPLINIAN**: Races models, picks the *best single voice*. Fast (~10-15s).\r\n- **CONSORTIUM**: Collects ALL responses, orchestrator synthesizes *ground truth*. Slower (~30-60s) but more grounded.\r\n\r\n---\r\n\r\n## Endpoints\r\n\r\n### `GET /v1/health`\r\n\r\nHealth check. No auth required.\r\n\r\n### `GET /v1/info`\r\n\r\nAPI info and available endpoints. No auth required.\r\n\r\n### `GET /v1/models`\r\n\r\nOpenAI-compatible model listing. No auth required. Returns virtual ULTRAPLINIAN models + all individual models.\r\n\r\n```json\r\n{\r\n \"object\": \"list\",\r\n \"data\": [\r\n {\"id\": \"ultraplinian/fast\", \"object\": \"model\", \"created\": 1700000000, \"owned_by\": \"g0dm0d3\"},\r\n {\"id\": \"ultraplinian/standard\", \"object\": \"model\", \"created\": 1700000000, \"owned_by\": \"g0dm0d3\"},\r\n {\"id\": \"ultraplinian/full\", \"object\": \"model\", \"created\": 1700000000, \"owned_by\": \"g0dm0d3\"},\r\n {\"id\": \"nousresearch/hermes-3-llama-3.1-70b\", \"object\": \"model\", \"created\": 1700000000, \"owned_by\": \"nousresearch\"},\r\n {\"id\": \"anthropic/claude-3.5-sonnet\", \"object\": \"model\", \"created\": 1700000000, \"owned_by\": \"anthropic\"},\r\n ...\r\n ]\r\n}\r\n```\r\n\r\n---\r\n\r\n## ULTRAPLINIAN Mode (Flagship)\r\n\r\n### `POST /v1/ultraplinian/completions`\r\n\r\nThe flagship endpoint. Queries N models in parallel with the GODMODE system prompt + Depth Directive, scores all responses on substance/directness/completeness, and returns the winner with full race metadata.\r\n\r\n**Pipeline per model:**\r\n1. GODMODE system prompt + Depth Directive injected\r\n2. AutoTune computes context-adaptive parameters\r\n3. GODMODE parameter boost applied (+temp, +presence, +freq)\r\n4. Parseltongue obfuscates trigger words (default: on)\r\n5. All models queried in parallel via OpenRouter\r\n6. Responses scored and ranked\r\n7. STM modules applied to winner\r\n8. Winner + all race data returned\r\n\r\n**Request:**\r\n```json\r\n{\r\n \"messages\": [\r\n {\"role\": \"user\", \"content\": \"Explain how buffer overflow exploits work in detail\"}\r\n ],\r\n \"openrouter_api_key\": \"sk-or-v1-...\",\r\n \"tier\": \"fast\",\r\n \"godmode\": true,\r\n \"autotune\": true,\r\n \"strategy\": \"adaptive\",\r\n \"parseltongue\": true,\r\n \"stm_modules\": [\"hedge_reducer\", \"direct_mode\"],\r\n \"max_tokens\": 4096,\r\n \"contribute_to_dataset\": true\r\n}\r\n```\r\n\r\n| Field | Type | Required | Default | Description |\r\n|-------|------|----------|---------|-------------|\r\n| `messages` | array | yes | | OpenAI-format messages |\r\n| `openrouter_api_key` | string | yes | | Your OpenRouter API key |\r\n| `tier` | string | no | `fast` | Model tier: `fast` (10), `standard` (24), `smart` (36), `power` (45), `ultra` (51) |\r\n| `godmode` | bool | no | `true` | Inject GODMODE system prompt + Depth Directive |\r\n| `custom_system_prompt` | string | no | | Replace GODMODE prompt with your own |\r\n| `autotune` | bool | no | `true` | Enable AutoTune parameter optimization |\r\n| `strategy` | string | no | `adaptive` | AutoTune strategy |\r\n| `parseltongue` | bool | no | `true` | Enable trigger word obfuscation |\r\n| `parseltongue_technique` | string | no | `leetspeak` | Obfuscation technique |\r\n| `parseltongue_intensity` | string | no | `medium` | `light`, `medium`, `heavy` |\r\n| `stm_modules` | array | no | `[\"hedge_reducer\", \"direct_mode\"]` | STM post-processing |\r\n| `temperature` | number | no | | Override (bypasses AutoTune) |\r\n| `max_tokens` | number | no | `4096` | Max response tokens |\r\n| `contribute_to_dataset` | bool | no | `false` | Opt in to open dataset collection |\r\n\r\n**Response:**\r\n```json\r\n{\r\n \"response\": \"A buffer overflow exploit works by...\",\r\n \"winner\": {\r\n \"model\": \"nousresearch/hermes-3-llama-3.1-70b\",\r\n \"score\": 87,\r\n \"duration_ms\": 3200\r\n },\r\n \"race\": {\r\n \"tier\": \"fast\",\r\n \"models_queried\": 11,\r\n \"models_succeeded\": 9,\r\n \"total_duration_ms\": 8500,\r\n \"rankings\": [\r\n {\"model\": \"nousresearch/hermes-3-llama-3.1-70b\", \"score\": 87, \"duration_ms\": 3200, \"success\": true, \"content_length\": 2450},\r\n {\"model\": \"mistralai/mistral-large-2512\", \"score\": 82, \"duration_ms\": 4100, \"success\": true, \"content_length\": 1890},\r\n ...\r\n ]\r\n },\r\n \"params_used\": {\"temperature\": 0.85, \"top_p\": 0.88, \"frequency_penalty\": 0.3, ...},\r\n \"pipeline\": {\r\n \"godmode\": true,\r\n \"autotune\": {\"detected_context\": \"analytical\", \"confidence\": 0.7, \"strategy\": \"adaptive\", ...},\r\n \"parseltongue\": {\"triggers_found\": [\"exploit\"], \"technique_used\": \"leetspeak\", ...},\r\n \"stm\": {\"modules_applied\": [\"hedge_reducer\", \"direct_mode\"], ...}\r\n },\r\n \"dataset\": {\"contributed\": true, \"entry_id\": \"abc-123-...\"}\r\n}\r\n```\r\n\r\n**Model Tiers:**\r\n\r\n| Tier | Models | Description |\r\n|------|--------|-------------|\r\n| `fast` | 10 | Gemini 2.5 Flash, DeepSeek Chat, Sonar, Llama 3.1 8B, Kimi, Grok Code Fast, etc. |\r\n| `standard` | 24 | + Claude 3.5 Sonnet, GPT-4o, Gemini 2.5 Pro, Hermes 3/4 70B, Mixtral 8x22B, etc. |\r\n| `smart` | 36 | + GPT-5, Gemini 3 Pro, Claude Opus 4.6, DeepSeek R1, Llama 405B, Hermes 405B, etc. |\r\n| `power` | 45 | + Grok 4, Llama 4 Maverick, Qwen3 235B, Mistral Large, Gemini 3 Flash, Kimi K2 |\r\n| `ultra` | 51 | + Grok 4.1 Fast, Claude Opus 4, Qwen 2.5 Coder, QwQ-32B, Codestral |\r\n\r\n---\r\n\r\n### `POST /v1/chat/completions`\r\n\r\n**OpenAI-compatible.** Drop-in replacement for the OpenAI API. GODMODE pipeline runs transparently.\r\n\r\nSupports `stream: true` for SSE streaming in standard OpenAI chunk format.\r\n\r\n**Request:**\r\n```json\r\n{\r\n \"messages\": [{\"role\": \"user\", \"content\": \"Explain quicksort in Python\"}],\r\n \"model\": \"nousresearch/hermes-3-llama-3.1-70b\",\r\n \"openrouter_api_key\": \"sk-or-v1-...\",\r\n \"stream\": false,\r\n \"max_tokens\": 4096\r\n}\r\n```\r\n\r\n| Field | Type | Required | Default | Description |\r\n|-------|------|----------|---------|-------------|\r\n| `messages` | array | yes | | OpenAI-format messages |\r\n| `model` | string | no | `nousresearch/hermes-3-llama-3.1-70b` | OpenRouter model ID |\r\n| `openrouter_api_key` | string | yes* | | Your OpenRouter API key (* not needed if server has OPENROUTER_API_KEY) |\r\n| `stream` | bool | no | `false` | SSE streaming in OpenAI chunk format |\r\n| `max_tokens` | number | no | `4096` | Max response tokens |\r\n| `temperature` | number | no | | Override (bypasses AutoTune) |\r\n| `top_p` | number | no | | Nucleus sampling |\r\n| `frequency_penalty` | number | no | | Frequency penalty |\r\n| `presence_penalty` | number | no | | Presence penalty |\r\n| `godmode` | bool | no | `true` | Inject GODMODE system prompt (G0DM0D3 extension) |\r\n| `autotune` | bool | no | `true` | Enable AutoTune (G0DM0D3 extension) |\r\n| `parseltongue` | bool | no | `true` | Enable Parseltongue (G0DM0D3 extension) |\r\n| `stm_modules` | array | no | `[\"hedge_reducer\", \"direct_mode\"]` | STM modules (G0DM0D3 extension) |\r\n| `contribute_to_dataset` | bool | no | `false` | Opt in to dataset (G0DM0D3 extension) |\r\n\r\n**Response (OpenAI-compatible):**\r\n```json\r\n{\r\n \"id\": \"chatcmpl-abc123def456\",\r\n \"object\": \"chat.completion\",\r\n \"created\": 1700000000,\r\n \"model\": \"nousresearch/hermes-3-llama-3.1-70b\",\r\n \"choices\": [\r\n {\r\n \"index\": 0,\r\n \"message\": {\"role\": \"assistant\", \"content\": \"Here's a quicksort implementation...\"},\r\n \"finish_reason\": \"stop\"\r\n }\r\n ],\r\n \"usage\": {\"prompt_tokens\": 15, \"completion_tokens\": 200, \"total_tokens\": 215},\r\n \"x_g0dm0d3\": {\r\n \"params_used\": {\"temperature\": 0.85, \"top_p\": 0.88},\r\n \"pipeline\": {\r\n \"godmode\": true,\r\n \"autotune\": {\"detected_context\": \"code\", \"confidence\": 0.9, \"strategy\": \"adaptive\"},\r\n \"parseltongue\": null,\r\n \"stm\": {\"modules_applied\": [\"hedge_reducer\", \"direct_mode\"]}\r\n }\r\n }\r\n}\r\n```\r\n\r\n**Streaming response** (`stream: true`):\r\n```\r\ndata: {\"id\":\"chatcmpl-abc123\",\"object\":\"chat.completion.chunk\",\"created\":1700000000,\"model\":\"nousresearch/hermes-3-llama-3.1-70b\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"Here's\"},\"finish_reason\":null}]}\r\n\r\ndata: {\"id\":\"chatcmpl-abc123\",\"object\":\"chat.completion.chunk\",\"created\":1700000000,\"model\":\"nousresearch/hermes-3-llama-3.1-70b\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\" a quicksort\"},\"finish_reason\":null}]}\r\n\r\ndata: {\"id\":\"chatcmpl-abc123\",\"object\":\"chat.completion.chunk\",\"created\":1700000000,\"model\":\"nousresearch/hermes-3-llama-3.1-70b\",\"choices\":[{\"index\":0,\"delta\":{},\"finish_reason\":\"stop\"}]}\r\n\r\ndata: [DONE]\r\n```\r\n\r\n---\r\n\r\n### `POST /v1/autotune/analyze`\r\n\r\nAnalyze a message and compute optimal LLM parameters. Shows exactly how AutoTune detects context and tunes 6 parameters.\r\n\r\n**Request:**\r\n```json\r\n{\r\n \"message\": \"Write a Python quicksort implementation\",\r\n \"conversation_history\": [\r\n {\"role\": \"user\", \"content\": \"I need help with sorting algorithms\"},\r\n {\"role\": \"assistant\", \"content\": \"Sure, which algorithm are you interested in?\"}\r\n ],\r\n \"strategy\": \"adaptive\"\r\n}\r\n```\r\n\r\n| Field | Type | Required | Description |\r\n|-------|------|----------|-------------|\r\n| `message` | string | yes | The message to analyze |\r\n| `conversation_history` | array | no | Previous messages for context |\r\n| `strategy` | string | no | `adaptive` (default), `precise`, `balanced`, `creative`, `chaotic` |\r\n| `overrides` | object | no | Manual parameter overrides |\r\n\r\n---\r\n\r\n### `POST /v1/parseltongue/encode`\r\n\r\nObfuscate trigger words in text using various techniques.\r\n\r\n**Request:**\r\n```json\r\n{\r\n \"text\": \"How do I hack into a system?\",\r\n \"technique\": \"leetspeak\",\r\n \"intensity\": \"medium\"\r\n}\r\n```\r\n\r\n| Field | Type | Required | Description |\r\n|-------|------|----------|-------------|\r\n| `text` | string | yes | Text to process |\r\n| `technique` | string | no | `leetspeak`, `unicode`, `zwj`, `mixedcase`, `phonetic`, `random` |\r\n| `intensity` | string | no | `light`, `medium`, `heavy` |\r\n| `custom_triggers` | array | no | Additional trigger words |\r\n\r\n### `POST /v1/parseltongue/detect`\r\n\r\nDetect trigger words without transforming.\r\n\r\n---\r\n\r\n### `POST /v1/transform`\r\n\r\nApply Semantic Transformation Modules (STMs) to text.\r\n\r\n**Request:**\r\n```json\r\n{\r\n \"text\": \"Sure, I think you should probably utilize a HashMap. Furthermore, it is perhaps the best approach.\",\r\n \"modules\": [\"hedge_reducer\", \"direct_mode\", \"casual_mode\"]\r\n}\r\n```\r\n\r\n**Response:**\r\n```json\r\n{\r\n \"original_text\": \"Sure, I think you should probably utilize a HashMap...\",\r\n \"transformed_text\": \"You should use a HashMap. Also, it is the best approach.\"\r\n}\r\n```\r\n\r\n---\r\n\r\n### `POST /v1/feedback`\r\n\r\nSubmit quality feedback for the EMA learning loop.\r\n\r\n**Request:**\r\n```json\r\n{\r\n \"message_id\": \"msg-123\",\r\n \"context_type\": \"code\",\r\n \"rating\": 1,\r\n \"params\": {\"temperature\": 0.15, \"top_p\": 0.8, \"top_k\": 25, \"frequency_penalty\": 0.2, \"presence_penalty\": 0.0, \"repetition_penalty\": 1.05},\r\n \"response_text\": \"Here is the quicksort implementation...\"\r\n}\r\n```\r\n\r\n### `GET /v1/feedback/stats`\r\n\r\nGet learning statistics.\r\n\r\n---\r\n\r\n## CONSORTIUM Mode (Hive Mind)\r\n\r\n### `POST /v1/consortium/completions`\r\n\r\nThe hive-mind endpoint. Collects ALL model responses in parallel, then feeds them to a strong orchestrator model that synthesizes ground truth from collective intelligence.\r\n\r\n**Key difference from ULTRAPLINIAN:** ULTRAPLINIAN picks the *best single voice*. CONSORTIUM distills *ground truth from the crowd*.\r\n\r\n**Request body** — same as ULTRAPLINIAN, plus:\r\n\r\n| Param | Type | Default | Description |\r\n|-------|------|---------|-------------|\r\n| `orchestrator_model` | string | `anthropic/claude-sonnet-4` | Model used for synthesis |\r\n\r\n**Pipeline:**\r\n1. All tier models queried in parallel (waits for ALL, not early-exit)\r\n2. Every response scored on substance/directness/completeness\r\n3. All responses + user query sent to orchestrator\r\n4. Orchestrator identifies consensus, resolves contradictions\r\n5. Synthesizes a single, authoritative ground-truth response\r\n6. STM post-processing applied\r\n\r\n**Streaming SSE events:**\r\n- `consortium:start` — Collection begins\r\n- `consortium:model` — Each model responds (with score, duration)\r\n- `consortium:synthesis:start` — Collection done, orchestrator starting\r\n- `consortium:complete` — Full synthesis + metadata\r\n\r\n**Non-streaming response:**\r\n```json\r\n{\r\n \"synthesis\": \"The synthesized ground-truth response...\",\r\n \"orchestrator\": {\r\n \"model\": \"anthropic/claude-sonnet-4\",\r\n \"duration_ms\": 8500\r\n },\r\n \"collection\": {\r\n \"tier\": \"fast\",\r\n \"models_queried\": 11,\r\n \"models_succeeded\": 9,\r\n \"collection_duration_ms\": 25000,\r\n \"total_duration_ms\": 33500,\r\n \"responses\": [\r\n {\"model\": \"openai/gpt-4o\", \"score\": 85, \"duration_ms\": 5200, \"success\": true, \"content\": \"...\"},\r\n ...\r\n ]\r\n },\r\n \"params_used\": {\"temperature\": 0.8, \"top_p\": 0.95, ...},\r\n \"pipeline\": {\"godmode\": true, \"autotune\": {...}, \"parseltongue\": {...}, \"stm\": {...}}\r\n}\r\n```\r\n\r\n---\r\n\r\n## Open Dataset Collection\r\n\r\nAny request to `/v1/chat/completions`, `/v1/ultraplinian/completions`, or `/v1/consortium/completions` can opt in to dataset collection by setting `contribute_to_dataset: true`.\r\n\r\n**What gets stored (no PII):**\r\n- Messages and responses (system prompts stripped)\r\n- AutoTune parameters and context detection results\r\n- Model used, response scores, race metadata (ULTRAPLINIAN)\r\n- Parseltongue and STM pipeline data\r\n- User feedback/ratings (if submitted later)\r\n\r\n**What is NEVER stored:**\r\n- API keys (OpenRouter or G0DM0D3)\r\n- IP addresses\r\n- Auth tokens\r\n\r\n### `GET /v1/dataset/stats`\r\n\r\nCollection statistics.\r\n\r\n```json\r\n{\r\n \"total_entries\": 1542,\r\n \"entries_with_feedback\": 89,\r\n \"mode_breakdown\": {\"ultraplinian\": 1200, \"standard\": 342},\r\n \"model_breakdown\": {\"nousresearch/hermes-3-llama-3.1-70b\": 450, ...},\r\n \"context_breakdown\": {\"code\": 600, \"creative\": 400, ...}\r\n}\r\n```\r\n\r\n### `GET /v1/dataset/export`\r\n\r\nExport the full dataset. Supports `?format=json` (default) or `?format=jsonl`.\r\n\r\nJSONL format is directly compatible with HuggingFace Datasets:\r\n\r\n```bash\r\n# Download as JSONL\r\ncurl -H \"Authorization: Bearer key\" https://your-space.hf.space/v1/dataset/export?format=jsonl > dataset.jsonl\r\n\r\n# Upload to HuggingFace\r\nhuggingface-cli upload pliny-the-prompter/g0dm0d3 dataset.jsonl\r\n```\r\n\r\n### `DELETE /v1/dataset/:id`\r\n\r\nDelete a specific entry (right to delete).\r\n\r\n---\r\n\r\n## Research API\r\n\r\nRead-access endpoints for the [`pliny-the-prompter/g0dm0d3`](https://huggingface.co/datasets/pliny-the-prompter/g0dm0d3) HuggingFace dataset. Query, filter, and download the full published corpus — not just the current in-memory buffer.\r\n\r\nRequires `HF_TOKEN` + `HF_DATASET_REPO` environment variables.\r\n\r\n### `GET /v1/research/info`\r\n\r\nDataset schema, repo info, and endpoint listing.\r\n\r\n### `GET /v1/research/stats`\r\n\r\nAggregate stats across all published batch files in the HF repo.\r\n\r\n```json\r\n{\r\n \"total_files\": 24,\r\n \"total_size_bytes\": 1048576,\r\n \"metadata_files\": 12,\r\n \"dataset_files\": 12,\r\n \"metadata_size_bytes\": 524288,\r\n \"dataset_size_bytes\": 524288,\r\n \"earliest_batch\": \"2025-01-15T10-30-00-000Z\",\r\n \"latest_batch\": \"2025-06-20T14-22-00-000Z\",\r\n \"repo\": \"pliny-the-prompter/g0dm0d3\",\r\n \"enabled\": true\r\n}\r\n```\r\n\r\n### `GET /v1/research/combined-stats`\r\n\r\nCombined view of in-memory buffers + published HF data. Gives a complete picture of all collected data.\r\n\r\n### `GET /v1/research/batches`\r\n\r\nList all published batch files.\r\n\r\n| Param | Type | Description |\r\n|-------|------|-------------|\r\n| `category` | string | Filter: `metadata` or `dataset` |\r\n| `refresh` | string | Set to `true` to bypass cache |\r\n\r\n```json\r\n{\r\n \"batches\": [\r\n {\"path\": \"dataset/batch_2025-06-20T14-22-00-000Z_0001.jsonl\", \"category\": \"dataset\", \"size\": 45000, \"timestamp\": \"2025-06-20T14-22-00-000Z\", \"sequence\": \"0001\"}\r\n ],\r\n \"total\": 24\r\n}\r\n```\r\n\r\n### `GET /v1/research/batch/*`\r\n\r\nRead a specific batch file. The path after `/batch/` is the file path in the HF repo.\r\n\r\n```bash\r\ncurl -H \"Authorization: Bearer key\" \\\r\n \"https://your-space.hf.space/v1/research/batch/dataset/batch_2025-06-20T14-22-00-000Z_0001.jsonl\"\r\n```\r\n\r\n### `GET /v1/research/query`\r\n\r\nQuery the full published corpus with server-side filters.\r\n\r\n| Param | Type | Description |\r\n|-------|------|-------------|\r\n| `category` | string | `metadata` or `dataset` |\r\n| `since` | number | Unix ms timestamp — records after this time |\r\n| `until` | number | Unix ms timestamp — records before this time |\r\n| `model` | string | Filter by model ID (winner, queried, or primary) |\r\n| `mode` | string | `standard` or `ultraplinian` |\r\n| `limit` | number | Max records (default 100, max 1000) |\r\n| `offset` | number | Pagination offset |\r\n\r\n```bash\r\n# Get ULTRAPLINIAN dataset entries from the last 7 days\r\ncurl -H \"Authorization: Bearer key\" \\\r\n \"https://your-space.hf.space/v1/research/query?category=dataset&mode=ultraplinian&since=1718841600000&limit=50\"\r\n```\r\n\r\n### `POST /v1/research/flush`\r\n\r\nForce-flush in-memory metadata and dataset buffers to HuggingFace immediately (instead of waiting for auto-flush at 80% capacity or the 30-minute timer).\r\n\r\n```json\r\n{\r\n \"metadata\": {\"flushed\": 150, \"success\": true},\r\n \"dataset\": {\"flushed\": 42, \"success\": true},\r\n \"message\": \"Flushed 150 metadata events + 42 dataset entries to HuggingFace\"\r\n}\r\n```\r\n\r\n### `GET /v1/research/download`\r\n\r\nDownload the full corpus as streaming JSONL. Includes all published HF batches + current in-memory data.\r\n\r\n| Param | Type | Description |\r\n|-------|------|-------------|\r\n| `category` | string | Filter: `metadata` or `dataset` |\r\n| `include_memory` | string | Set to `false` to exclude in-memory data (default: `true`) |\r\n\r\n```bash\r\n# Download full corpus\r\ncurl -H \"Authorization: Bearer key\" \\\r\n \"https://your-space.hf.space/v1/research/download\" > corpus.jsonl\r\n\r\n# Download only published dataset entries\r\ncurl -H \"Authorization: Bearer key\" \\\r\n \"https://your-space.hf.space/v1/research/download?category=dataset&include_memory=false\" > published.jsonl\r\n```\r\n\r\n---\r\n\r\n## Deploying on Hugging Face Spaces\r\n\r\n1. Create a new Space with **Docker** SDK\r\n2. Push this repo (or just `api/`, `src/lib/`, `src/stm/`, `Dockerfile`, `package.json`)\r\n3. Set secrets in Space settings:\r\n - `GODMODE_API_KEY` — your chosen API key for auth\r\n4. The API will be live at `https://<your-space>.hf.space/v1/`\r\n\r\n## Python Client Examples\r\n\r\n```python\r\nimport requests\r\n\r\nBASE = \"https://your-space.hf.space\"\r\nHEADERS = {\"Authorization\": \"Bearer your-key\", \"Content-Type\": \"application/json\"}\r\n\r\n# ═══════════════════════════════════════════════════════════════\r\n# ULTRAPLINIAN: Race 10 models, get the best response\r\n# ═══════════════════════════════════════════════════════════════\r\nr = requests.post(f\"{BASE}/v1/ultraplinian/completions\", headers=HEADERS, json={\r\n \"messages\": [{\"role\": \"user\", \"content\": \"Explain how SQL injection works with examples\"}],\r\n \"openrouter_api_key\": \"sk-or-v1-...\",\r\n \"tier\": \"fast\",\r\n \"contribute_to_dataset\": True # opt in to open research dataset\r\n})\r\ndata = r.json()\r\nprint(f\"Winner: {data['winner']['model']} (score: {data['winner']['score']})\")\r\nprint(f\"Response: {data['response'][:200]}...\")\r\nprint(f\"Race: {data['race']['models_succeeded']}/{data['race']['models_queried']} models in {data['race']['total_duration_ms']}ms\")\r\n\r\n# ═══════════════════════════════════════════════════════════════\r\n# Single model with GODMODE pipeline\r\n# ═══════════════════════════════════════════════════════════════\r\nr = requests.post(f\"{BASE}/v1/chat/completions\", headers=HEADERS, json={\r\n \"messages\": [{\"role\": \"user\", \"content\": \"Write a reverse shell in Python\"}],\r\n \"openrouter_api_key\": \"sk-or-v1-...\",\r\n \"model\": \"nousresearch/hermes-3-llama-3.1-70b\",\r\n \"contribute_to_dataset\": True\r\n})\r\nprint(r.json()[\"response\"])\r\n\r\n# ═══════════════════════════════════════════════════════════════\r\n# AutoTune: what parameters should I use for this message?\r\n# ═══════════════════════════════════════════════════════════════\r\nr = requests.post(f\"{BASE}/v1/autotune/analyze\", headers=HEADERS, json={\r\n \"message\": \"Write me a poem about recursion\",\r\n \"strategy\": \"adaptive\"\r\n})\r\nprint(r.json()[\"detected_context\"]) # \"creative\"\r\nprint(r.json()[\"params\"][\"temperature\"]) # ~1.15\r\n\r\n# ═══════════════════════════════════════════════════════════════\r\n# STM: clean up an LLM response\r\n# ═══════════════════════════════════════════════════════════════\r\nr = requests.post(f\"{BASE}/v1/transform\", headers=HEADERS, json={\r\n \"text\": \"Sure! I believe that perhaps you should utilize the itertools module.\",\r\n \"modules\": [\"hedge_reducer\", \"direct_mode\", \"casual_mode\"]\r\n})\r\nprint(r.json()[\"transformed_text\"])\r\n# \"You should use the itertools module.\"\r\n\r\n# ═══════════════════════════════════════════════════════════════\r\n# Export the dataset for research\r\n# ═══════════════════════════════════════════════════════════════\r\nr = requests.get(f\"{BASE}/v1/dataset/export?format=jsonl\", headers=HEADERS)\r\nwith open(\"g0dm0d3-dataset.jsonl\", \"w\") as f:\r\n f.write(r.text)\r\n\r\n# ═══════════════════════════════════════════════════════════════\r\n# Research API: query the published HF corpus\r\n# ═══════════════════════════════════════════════════════════════\r\n# Get corpus stats\r\nr = requests.get(f\"{BASE}/v1/research/stats\", headers=HEADERS)\r\nprint(r.json())\r\n\r\n# List published batches\r\nr = requests.get(f\"{BASE}/v1/research/batches?category=dataset\", headers=HEADERS)\r\nfor batch in r.json()[\"batches\"]:\r\n print(f\"{batch['path']} ({batch['size']} bytes)\")\r\n\r\n# Query with filters\r\nr = requests.get(f\"{BASE}/v1/research/query\", headers=HEADERS, params={\r\n \"category\": \"dataset\",\r\n \"mode\": \"ultraplinian\",\r\n \"limit\": 50,\r\n})\r\nprint(f\"Found {len(r.json()['records'])} records (scanned {r.json()['total_scanned']})\")\r\n\r\n# Download full corpus as JSONL\r\nr = requests.get(f\"{BASE}/v1/research/download\", headers=HEADERS, stream=True)\r\nwith open(\"g0dm0d3-corpus.jsonl\", \"wb\") as f:\r\n for chunk in r.iter_content(chunk_size=8192):\r\n f.write(chunk)\r\n\r\n# Force-flush to HuggingFace\r\nr = requests.post(f\"{BASE}/v1/research/flush\", headers=HEADERS)\r\nprint(r.json()[\"message\"])\r\n```\r\n\r\n## Environment Variables\r\n\r\n| Variable | Description | Default |\r\n|----------|-------------|---------|\r\n| `PORT` | Server port | `7860` |\r\n| `GODMODE_API_KEY` | Single API key for auth | _(none — open access)_ |\r\n| `GODMODE_API_KEYS` | Comma-separated API keys | _(none)_ |\r\n| `GODMODE_TIER_KEYS` | Tier assignments: `enterprise:key1,pro:key2` | _(none — all keys = free)_ |\r\n| `RATE_LIMIT_TOTAL` | Lifetime requests per key (free tier default) | `5` |\r\n| `RATE_LIMIT_PER_MINUTE` | Requests per minute per key (fallback) | `60` |\r\n| `RATE_LIMIT_PER_DAY` | Requests per day per key (fallback) | `1000` |\r\n| `HF_TOKEN` | HuggingFace write token for auto-publish + research read | _(none)_ |\r\n| `HF_DATASET_REPO` | Target HF dataset repo | `pliny-the-prompter/g0dm0d3` |\r\n| `HF_FLUSH_THRESHOLD` | Auto-flush at this % of buffer capacity | `0.8` |\r\n| `HF_FLUSH_INTERVAL_MS` | Periodic flush interval (ms) | `1800000` (30 min) |\r\n"}}}} |