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