Installation

pnpm add subconscious
# or
npm install subconscious
# or
yarn add subconscious

Quick Start

import { Subconscious } from 'subconscious';

const client = new Subconscious({
  apiKey: process.env.SUBCONSCIOUS_API_KEY!,
});

const run = await 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: {} }],
  },
  options: { awaitCompletion: true },
});

console.log(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:

const run = await client.run({
  engine: 'tim-gpt',
  input: {
    instructions: 'Analyze the latest trends in renewable energy',
    tools: [{ type: 'platform', id: 'fast_search', options: {} }],
  },
  options: { awaitCompletion: true },
});

console.log(run.result?.answer);
console.log(run.result?.reasoning); // Structured reasoning nodes

Fire and Forget

Start a run without waiting, then check status later:

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

console.log(`Run started: ${run.runId}`);

// Check status later
const status = await client.get(run.runId);
console.log(status.status); // 'queued' | 'running' | 'succeeded' | 'failed' | 'canceled' | 'timed_out'

Poll with Custom Options

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

// Wait with custom polling options
const result = await client.wait(run.runId, {
  intervalMs: 2000, // Poll every 2 seconds
  maxAttempts: 60, // Give up after 60 attempts
});

Streaming (Text Deltas)

Stream text as it's generated:

const stream = client.stream({
  engine: 'tim-gpt',
  input: {
    instructions: 'Write a short essay about space exploration',
    tools: [{ type: 'platform', id: 'fast_search' }],
  },
});

for await (const event of stream) {
  if (event.type === 'delta') {
    process.stdout.write(event.content);
  } else if (event.type === 'done') {
    console.log('\n\nRun completed:', event.runId);
  } else if (event.type === 'error') {
    console.error('Error:', event.message);
  }
}

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

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)
const fastSearch = {
  type: 'platform',
  id: 'fast_search',
  options: {},
};

// Function tools (your own HTTP endpoints)
const customFunction = {
  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', description: 'City name' },
    },
    required: ['location'],
  },
};

// MCP tools
const mcpTool = {
  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

const toolWithHeadersAndDefaults = {
  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
      sessionId: { type: 'string' },
      apiKey: { 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: {
    sessionId: 'user-session-abc123',
    apiKey: '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.

Structured Output

Get structured responses using JSON Schema. We recommend using Zod to define your schema, then convert it with zodToJsonSchema():

import { z } from 'zod';
import { Subconscious, zodToJsonSchema } from 'subconscious';

const client = new Subconscious({ apiKey: process.env.SUBCONSCIOUS_API_KEY! });

// Define your output schema with Zod
const AnalysisSchema = z.object({
  summary: z.string().describe('A brief summary of the findings'),
  keyPoints: z.array(z.string()).describe('Main takeaways'),
  sentiment: z.enum(['positive', 'neutral', 'negative']),
  confidence: z.number().describe('Confidence score from 0 to 1'),
});

const run = await client.run({
  engine: 'tim-gpt',
  input: {
    instructions: 'Analyze the latest news about electric vehicles',
    tools: [{ type: 'platform', id: 'fast_search', options: {} }],
    answerFormat: zodToJsonSchema(AnalysisSchema, 'Analysis'),
  },
  options: { awaitCompletion: true },
});

// Result is typed according to your schema
const result = run.result?.answer as z.infer<typeof AnalysisSchema>;
console.log(result.summary);
console.log(result.keyPoints);

You can also define a reasoningFormat to structure the agent's reasoning:

const ReasoningSchema = z.object({
  steps: z.array(
    z.object({
      thought: z.string(),
      action: z.string(),
    }),
  ),
  conclusion: z.string(),
});

const run = await client.run({
  engine: 'tim-gpt',
  input: {
    instructions: 'Research and explain quantum computing',
    tools: [{ type: 'platform', id: 'fast_search', options: {} }],
    answerFormat: zodToJsonSchema(AnalysisSchema, 'Analysis'),
    reasoningFormat: zodToJsonSchema(ReasoningSchema, 'Reasoning'),
  },
  options: { awaitCompletion: true },
});

Manual JSON Schema

You can also provide the JSON Schema directly without Zod:

const run = await client.run({
  engine: 'tim-gpt',
  input: {
    instructions: 'Analyze this topic',
    tools: [],
    answerFormat: {
      title: 'Analysis',
      type: 'object',
      properties: {
        summary: { type: 'string', description: 'Brief summary' },
        score: { type: 'number', description: 'Score from 1-10' },
      },
      required: ['summary', 'score'],
    },
  },
  options: { awaitCompletion: true },
});

Error Handling

import { SubconsciousError, AuthenticationError, RateLimitError } from 'subconscious';

try {
  const run = await client.run({
    /* ... */
  });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.error('Rate limited, retry later');
  } else if (error instanceof SubconsciousError) {
    console.error(`API error: ${error.code} - ${error.message}`);
  }
}

Cancellation

// Cancel via AbortController
const controller = new AbortController();
const stream = client.stream(params, { signal: controller.signal });
setTimeout(() => controller.abort(), 30000);

// Or cancel a running run
await client.cancel(run.runId);

API Reference

Subconscious

The main client class.

Constructor Options

| Option | Type | Required | Default | | --------- | -------- | -------- | --------------------------------- | | apiKey | string | Yes | - | | baseUrl | string | No | https://api.subconscious.dev/v1 |

Methods

| Method | Description | | -------------------------- | --------------------- | | run(params) | Create a new run | | stream(params, options?) | Stream text deltas | | get(runId) | Get run status | | wait(runId, options?) | Poll until completion | | cancel(runId) | Cancel a running run |

zodToJsonSchema(schema, title)

Convert a Zod schema to the JSON Schema format expected by answerFormat and reasoningFormat.

| Param | Type | Description | | -------- | ---------- | ---------------------------------- | | schema | Zod object | A Zod object schema (z.object()) | | title | string | Title for the schema |

Returns an OutputSchema compatible with answerFormat and reasoningFormat.

Engines

| Engine | Type | Description | | --------------- | -------- | ------------------------------------------------------------------------------- | | tim | Unified | Our flagship unified agent engine for a wide range of tasks | | tim-edge | Unified | Highly efficient engine tuned for performance with search tools | | timini | Compound | Complex reasoning engine for long-context and tool use backed by Gemini-3 Flash | | tim-gpt | Compound | Complex reasoning engine for long-context and tool use backed by OpenAI GPT-4.1 | | tim-gpt-heavy | Compound | Complex reasoning engine for long-context and tool use backed by OpenAI GPT-5.2 |

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

• Node.js ≥ 18
• ESM only

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

License

Apache-2.0