The official Python SDK for the Subconscious API
pip install subconscious-sdk
# or
uv add subconscious-sdk
# or
poetry add subconscious-sdk
Note: The package name is
subconscious-sdkbut you import it assubconscious.
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)
Create an API key in the Subconscious dashboard.
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
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'
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
},
)
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.
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.
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"],
}
Function tools support two powerful features for injecting data at call time:
headers: HTTP headers sent with the request to your tool endpointdefaults: 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:
- Define all parameters in
properties(required for validation) - Parameters with defaults are stripped from the schema before the model sees them
- Model only generates values for non-defaulted parameters (e.g.,
query) - At call time, defaults are merged into the request body
- 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.
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}")
# Cancel a running run
client.cancel(run.run_id)
The main client class.
| Option | Type | Required | Default |
|---|---|---|---|
api_key |
str |
Yes | - |
base_url |
str |
No | https://api.subconscious.dev/v1 |
| 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 |
| 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 |
| Status | Description |
|---|---|
queued |
Waiting to start |
running |
Currently executing |
succeeded |
Completed successfully |
failed |
Encountered an error |
canceled |
Manually canceled |
timed_out |
Exceeded time limit |
- Python ≥ 3.8
- requests
Contributions are welcome! Please feel free to submit a pull request.
Apache-2.0
For support and questions:
- Documentation: https://docs.subconscious.dev
- Email: {hongyin,jack}@subconscious.dev
