---
name: inception
description: Use when building AI agents, chat applications, voice assistants,
  code editors, or decision-making workflows. Reach for this skill when you need
  to call Mercury reasoning models via REST API, configure tool-calling agents,
  set up structured outputs, or integrate with voice/code platforms.
metadata:
  mintlify-proj: inception
  version: "1.0"
---

# Inception Platform (Mercury) Skill

## Product Summary

Inception Platform provides Mercury — a family of reasoning models served through an OpenAI-compatible REST API at `https://api.inceptionlabs.ai/v1`. Mercury models use diffusion-based token generation for low-latency, high-quality responses. The platform supports chat completions, tool calling, structured outputs, code editing (FIM/Next Edit), and decision classification. Key endpoints: `/v1/chat/completions`, `/v1/decisions`, `/v1/fim/completions`, `/v1/edit/completions`. SDKs available for Python (`inceptionai`) and TypeScript/JavaScript (`inceptionai`). Authentication via `INCEPTION_API_KEY` environment variable or explicit client construction. Primary docs: https://docs.inceptionlabs.ai

## When to Use

- **Chat agents & reasoning:** Call Mercury 3 for multi-step reasoning, complex problem-solving, or general-purpose chat with reasoning effort control
- **Tool-calling workflows:** Build agents that invoke functions, fetch data, and orchestrate multi-step tasks with parallel or sequential tool calls
- **Structured outputs:** Request typed JSON responses with schema validation for classification, extraction, or data transformation
- **Voice agents:** Use Mercury Voice or Mercury 3 with low/instant reasoning effort for real-time conversational AI with Vapi, ElevenLabs, or LiveKit
- **Code completion:** Use Mercury Edit 2 for inline autocomplete (FIM) or predictive multi-line edits (Next Edit) in editors
- **Routing & classification:** Use Mercury Decide endpoint for binary/categorical/ordinal decisions with probabilities over shared context
- **Streaming responses:** Stream block-by-block output for chat UIs or visualize diffusion denoising steps

## Quick Reference

### Models & Endpoints

| Model | Endpoint | Context | Max Output | Features | Price (Input) |
|-------|----------|---------|-----------|----------|---------------|
| **Mercury 3** | `/v1/chat/completions` | 1M tokens | 131K | Tool calling, structured outputs, reasoning effort | $0.10/1M* |
| **Mercury Voice** | `/v1/chat/completions` | 128K | 50K | Tool calling, structured outputs, voice-optimized | $0.20/1M* |
| **Mercury Decide** | `/v1/decisions` | — | — | Classification, scoring, extraction | $0.02/1M* |
| **Mercury 2.5** | `/v1/chat/completions` | 260K | 65K | Tool calling, structured outputs | $0.20/1M |
| **Mercury Edit 2** | `/v1/fim/completions`, `/v1/edit/completions` | 32K | 8K | Code autocomplete, next-edit | $0.25/1M |

*50% launch discount active

### Reasoning Effort Levels

| Level | Latency | Best For |
|-------|---------|----------|
| `instant` | Lowest | Voice, realtime, high-volume automation |
| `low` | Low | Latency-sensitive chat, tool-calling |
| `medium` | Balanced | General-purpose use (default for Mercury 2.5/2) |
| `high` | Highest | Complex multi-step reasoning |

Mercury 3 defaults to `low` if omitted; Mercury 2.5/2 default to `medium`.

### Essential Parameters

```python
# Chat completions
client.chat.completions.create(
    model="mercury-3",
    messages=[{"role": "user", "content": "..."}],
    reasoning_effort="medium",  # instant, low, medium, high
    temperature=0.75,  # 0.5–1.0
    max_completion_tokens=8192,
    tools=[...],  # optional
    response_format={"type": "json_schema", "json_schema": {...}},  # optional
    stream=True,  # optional
)

# Decisions
requests.post(
    "https://api.inceptionlabs.ai/v1/decisions",
    json={
        "model": "mercury-decide",
        "state": {...},
        "questions": {
            "name": {"type": "noul|choice|score|extract", ...}
        }
    }
)
```

### SDK Installation & Setup

```bash
# Python
pip install inceptionai

# TypeScript/JavaScript
npm install inceptionai

# Set API key
export INCEPTION_API_KEY="your_key_here"
```

### OpenAI-Compatible Clients

Inception works with OpenAI SDK, LangChain, LiteLLM, AISuite, and VercelAI by pointing `base_url` to `https://api.inceptionlabs.ai/v1`.

```python
from openai import OpenAI
client = OpenAI(
    api_key="your_key",
    base_url="https://api.inceptionlabs.ai/v1"
)
```

## Decision Guidance

### When to Use Mercury 3 vs. Mercury 2.5

| Scenario | Mercury 3 | Mercury 2.5 |
|----------|-----------|------------|
| Larger context (>260K tokens) | ✓ | — |
| Instant/low reasoning effort needed | ✓ | — |
| Cost-sensitive, medium reasoning OK | — | ✓ |
| Complex multi-step reasoning | ✓ | — |
| Existing Mercury 2.5 integration | — | ✓ |

### When to Use Tool Calling vs. Structured Outputs

| Use Case | Tool Calling | Structured Outputs |
|----------|--------------|-------------------|
| Multi-step agent workflows | ✓ | — |
| Fetch external data, execute functions | ✓ | — |
| Constrain response to JSON schema | — | ✓ |
| Classification/extraction in one call | — | ✓ |
| Parallel independent operations | ✓ | — |

### When to Use Mercury Decide vs. Chat Completions

| Use Case | Mercury Decide | Chat Completions |
|----------|----------------|------------------|
| Binary/categorical classification | ✓ | — |
| Scoring/ordinal ranking | ✓ | — |
| Extract exact text spans | ✓ | — |
| Needs tool calling | — | ✓ |
| Needs streaming | — | ✓ |
| Cost-sensitive (input-only billing) | ✓ | — |

### When to Use Reasoning Effort Levels

| Effort | Use When |
|--------|----------|
| `instant` | Voice agents, real-time turns, high-volume automations where latency is critical |
| `low` | Latency-sensitive chat, tool-calling workflows, voice with TTFT priority |
| `medium` | General-purpose chat, balanced reasoning and latency (default) |
| `high` | Complex reasoning, multi-step logic, when accuracy matters more than speed |

## Workflow

### 1. Set Up Authentication
- Create account at https://platform.inceptionlabs.ai
- Generate API key in dashboard
- Export as `INCEPTION_API_KEY` environment variable
- Verify key works: `curl -H "Authorization: Bearer $INCEPTION_API_KEY" https://api.inceptionlabs.ai/v1/models`

### 2. Choose Model & Endpoint
- Determine use case: chat, tool-calling, structured output, decision, or code editing
- Select appropriate model from quick reference table
- Confirm endpoint and supported features

### 3. Build Request
- Construct messages array with system/user/assistant roles
- Add tools definition if using tool calling (include `strict: true` for schema enforcement)
- Add response_format if using structured outputs
- Set reasoning_effort, temperature, max_completion_tokens
- For decisions: structure state and questions map

### 4. Call API
- Use official SDK (Python/TypeScript) or OpenAI-compatible client
- Handle streaming if needed (set `stream: true`)
- Implement exponential backoff for rate limits (429 errors)

### 5. Process Response
- For chat: extract `choices[0].message.content`
- For tool calls: parse `tool_calls` array, execute functions, append tool messages, call API again
- For decisions: read `answers` map with probabilities/confidence
- For streaming: iterate chunks and accumulate content

### 6. Verify & Monitor
- Check `usage.input_tokens` and `usage.output_tokens` against rate limits
- Log error codes and retry transient failures (500, 502, 503, 504)
- Test reasoning_effort and temperature on representative prompts before deploying

## Common Gotchas

- **Context window exceeded:** Reduce message history or max_completion_tokens. Mercury 3 has 1M context but reasoning tokens count toward output limit.
- **Tool calls not happening:** Set `tool_choice: "required"` to force tool calling. Use `strict: true` in tool definition for schema enforcement. Provide few-shot examples in system prompt.
- **Structured output validation fails:** Ensure `response_format` JSON schema is valid. Use `strict: true` and test schema against sample data.
- **Rate limit 429:** Implement exponential backoff. Free tier: 1K req/min, 1M input tokens/min, 100K output tokens/min. Pay-as-you-go: 3K req/min, 3M input/min, 300K output/min.
- **API key in client-side code:** Never expose keys in frontend or version control. Use environment variables or secure secrets manager.
- **Mercury Decide doesn't support streaming or tool calling:** Use `/v1/chat/completions` for those features.
- **Reasoning effort defaults differ:** Mercury 3 defaults to `low`; Mercury 2.5/2 default to `medium`. Omitting reasoning_effort changes behavior across models.
- **Voice agents with high reasoning effort:** Use `reasoning_effort: "low"` or `"instant"` for voice. Set `max_completion_tokens` to at least 3000 for medium effort (reasoning tokens included).
- **FIM vs. Next Edit confusion:** FIM answers "what goes between prefix and suffix?" (inline autocomplete). Next Edit answers "what should I change next?" (multi-line edits with history).
- **Streaming with structured outputs:** Structured outputs do not support streaming. Use non-streaming requests.

## Verification Checklist

Before submitting work:

- [ ] API key is set as environment variable and not hardcoded
- [ ] Model name is valid (mercury-3, mercury-2.5, mercury-2, mercury-edit-2, mercury-decide)
- [ ] Endpoint matches model (chat → `/v1/chat/completions`, decisions → `/v1/decisions`, etc.)
- [ ] Messages array has at least one user message
- [ ] Tool definitions include `strict: true` if using tool calling
- [ ] JSON schema is valid if using structured outputs
- [ ] Reasoning effort is one of: instant, low, medium, high (or omitted for defaults)
- [ ] Temperature is between 0.5 and 1.0
- [ ] max_completion_tokens is set (at least 3000 for medium reasoning effort)
- [ ] Rate limits are respected (implement backoff for 429 errors)
- [ ] Error handling covers 400, 401, 402, 404, 413, 422, 429, 500, 502, 503, 504
- [ ] Streaming is disabled if using structured outputs
- [ ] Tool call results are appended as tool messages with matching tool_call_id before next API call
- [ ] System prompt uses XML tags for multi-section prompts (persona, knowledge_base, current_task, etc.)
- [ ] Few-shot examples are included for tool selection or output format control

## Resources

**Comprehensive navigation:** https://docs.inceptionlabs.ai/llms.txt

**Critical pages:**
- [Models & Pricing](https://docs.inceptionlabs.ai/get-started/models) — Compare all Mercury models, endpoints, context windows, pricing
- [Tool Use](https://docs.inceptionlabs.ai/capabilities/tool-use) — Build multi-step agent workflows with tool calling
- [Prompt Guide](https://docs.inceptionlabs.ai/resources/prompt-guide) — Production prompting techniques for voice, tool-calling, search, and code agents

---

> For additional documentation and navigation, see: https://docs.inceptionlabs.ai/llms.txt