subconscious-sdk 0.2.1

The official Python SDK for the Subconscious API

Subconscious SDK

The official Python SDK for the Subconscious API

---

Installation

pip install subconscious-sdk
# or
uv add subconscious-sdk
# or
poetry add subconscious-sdk

Note: The package name is subconscious-sdk but you import it as subconscious.

Quick Start

from subconscious import Subconscious

client = Subconscious(api_key="your-api-key")

run = client.run(
    engine="tim-gpt",
    input={
        "instructions": "Search for the latest AI news and summarize the top 3 stories",
        "tools": [{"type": "platform", "id": "fast_search"}],
    },
    options={"await_completion": True},
)

print(run.result.answer)

Get Your API Key

Create an API key in the Subconscious dashboard.

Usage

Run and Wait

The simplest way to use the SDK—create a run and wait for completion:

run = client.run(
    engine="tim-gpt",
    input={
        "instructions": "Analyze the latest trends in renewable energy",
        "tools": [{"type": "platform", "id": "fast_search"}],
    },
    options={"await_completion": True},
)

print(run.result.answer)
print(run.result.reasoning)  # Structured reasoning nodes

Fire and Forget

Start a run without waiting, then check status later:

run = client.run(
    engine="tim-gpt",
    input={
        "instructions": "Generate a comprehensive report",
        "tools": [],
    },
)

print(f"Run started: {run.run_id}")

# Check status later
status = client.get(run.run_id)
print(status.status)  # 'queued' | 'running' | 'succeeded' | 'failed' | 'canceled' | 'timed_out'

Poll with Custom Options

run = client.run(
    engine="tim-gpt",
    input={
        "instructions": "Complex task",
        "tools": [{"type": "platform", "id": "fast_search"}],
    },
)

# Wait with custom polling options
result = client.wait(
    run.run_id,
    options={
        "interval_ms": 2000,  # Poll every 2 seconds
        "max_attempts": 60,   # Give up after 60 attempts
    },
)

Streaming (Text Deltas)

Stream text as it's generated:

for event in client.stream(
    engine="tim-gpt",
    input={
        "instructions": "Write a short essay about space exploration",
        "tools": [{"type": "platform", "id": "fast_search"}],
    },
):
    if event.type == "delta":
        print(event.content, end="", flush=True)
    elif event.type == "done":
        print(f"\n\nRun completed: {event.run_id}")
    elif event.type == "error":
        print(f"Error: {event.message}")

Note: Rich streaming events (reasoning steps, tool calls) are coming soon. Currently, the stream provides text deltas as they're generated.

Structured Output

Get responses in a specific JSON schema format using Pydantic models:

from pydantic import BaseModel
from subconscious import Subconscious

class AnalysisResult(BaseModel):
    summary: str
    key_points: list[str]
    sentiment: str

client = Subconscious(api_key="your-api-key")

run = client.run(
    engine="tim-gpt",
    input={
        "instructions": "Analyze the latest news about electric vehicles",
        "tools": [{"type": "platform", "id": "fast_search"}],
        "answerFormat": AnalysisResult,  # Pass the Pydantic class directly
    },
    options={"await_completion": True},
)

# The answer will conform to your schema
print(run.result.answer)  # JSON string matching AnalysisResult

The SDK automatically converts your Pydantic model to JSON Schema. You can also pass a raw JSON Schema dict if preferred.

For advanced use cases, you can also specify a reasoningFormat to structure the agent's reasoning output.

Tools

Simple Search Tools — Use these tools to get started quickly in our playground or with our API. For example: {"type": "platform", "id": "fast_search"}.

Tool Name	API Name	Description
Fast Search	fast_search	Extremely fast search for simple factual lookups
Web Search	web_search	Comprehensive web search for detailed research
Fresh Search	fresh_search	Search the web for content from the last 7 days
Page Reader	page_reader	Extract content from a specific webpage URL
Find Similar	find_similar	Find similar links to a given URL
People Search	people_search	Search for people, profiles, and bios
Company Search	company_search	Search for companies, funding info, and business details
News Search	news_search	Search for news articles and press coverage
Tweet Search	tweet_search	Search for tweets and Twitter/X discussions
Research Paper Search	research_paper_search	Search for academic research papers and studies
Google Search	google_search	Search the web using Google

# Platform tools (hosted by Subconscious)
fast_search = {
    "type": "platform",
    "id": "fast_search",
}

# Function tools (your own HTTP endpoints)
custom_function = {
    "type": "function",
    "name": "get_weather",
    "description": "Get current weather for a location",
    "url": "https://api.example.com/weather",
    "method": "GET",
    "timeout": 30,
    "parameters": {
        "type": "object",
        "properties": {
            "location": {"type": "string"},
        },
        "required": ["location"],
    },
}

# MCP tools
mcp_tool = {
    "type": "mcp",
    "url": "https://mcp.example.com",
    "allow": ["read", "write"],
}

Tool Headers & Default Arguments

Function tools support two powerful features for injecting data at call time:

• headers: HTTP headers sent with the request to your tool endpoint
• defaults: Parameter values hidden from the model and injected automatically

tool_with_headers_and_defaults = {
    "type": "function",
    "name": "search_database",
    "description": "Search the database",
    "url": "https://api.example.com/search",
    "method": "POST",
    "parameters": {
        "type": "object",
        "properties": {
            "query": {"type": "string", "description": "Search query"},
            # Define these for validation, but they'll be hidden from the model
            "session_id": {"type": "string"},
            "api_key": {"type": "string"},
        },
        "required": ["query"],  # Only query is required - model generates this
    },

    # HEADERS: Sent as HTTP headers when this tool's endpoint is called
    "headers": {
        "x-custom-auth": "my-secret-token",
        "x-request-source": "my-app",
    },

    # DEFAULTS: Injected into parameters, hidden from model
    "defaults": {
        "session_id": "user-session-abc123",
        "api_key": "secret-api-key",
    },
}

How it works:

Feature	Where it goes	When
headers	HTTP request headers	Sent to your tool's URL
defaults	Merged into request body parameters	At tool call time

Default arguments flow:

1. Define all parameters in properties (required for validation)
2. Parameters with defaults are stripped from the schema before the model sees them
3. Model only generates values for non-defaulted parameters (e.g., query)
4. At call time, defaults are merged into the request body
5. Default values always take precedence over model-generated values

Each tool can have its own headers and defaults - they're only applied when that specific tool is called.

Error Handling

from subconscious import (
    Subconscious,
    SubconsciousError,
    AuthenticationError,
    RateLimitError,
)

try:
    run = client.run(...)
except AuthenticationError:
    print("Invalid API key")
except RateLimitError:
    print("Rate limited, retry later")
except SubconsciousError as e:
    print(f"API error: {e.code} - {e}")

Cancellation

# Cancel a running run
client.cancel(run.run_id)

API Reference

Subconscious

The main client class.

Constructor Options

Option	Type	Required	Default
api_key	str	Yes	-
base_url	str	No	https://api.subconscious.dev/v1

Methods

Method	Description
run(engine, input, options)	Create a new run
stream(engine, input)	Stream text deltas
get(run_id)	Get run status
wait(run_id, options)	Poll until completion
cancel(run_id)	Cancel a running run

Engines

Engine	Type	Description	Input	Output
tim	Unified	Our flagship unified agent engine for a wide range of tasks	$2.00/1M	$8.00/1M
tim-edge	Unified	Highly efficient engine tuned for performance with search tools	$0.50/1M	$2.00/1M
timini	Compound	Complex reasoning engine for long-context and tool use backed by Gemini-3 Flash	$2.00/1M	$12.00/1M
tim-gpt	Compound	Complex reasoning engine for long-context and tool use backed by OpenAI GPT-4.1	$2.00/1M	$8.00/1M
tim-gpt-heavy	Compound	Complex reasoning engine for long-context and tool use backed by OpenAI GPT-5.2	$2.00/1M	$15.00/1M

Run Status

Status	Description
queued	Waiting to start
running	Currently executing
succeeded	Completed successfully
failed	Encountered an error
canceled	Manually canceled
timed_out	Exceeded time limit

Requirements

• Python ≥ 3.8
• requests

Contributing

Contributions are welcome! Please feel free to submit a pull request.

License

Apache-2.0

Support

For support and questions:

• Documentation: https://docs.subconscious.dev
• Email: {hongyin,jack}@subconscious.dev