Cogitator Runtime

import { Cogitator, Agent } from '@cogitator-ai/core';

const cog = new Cogitator({
  llm: {
    defaultProvider: 'openai',
    providers: {
      openai: { apiKey: process.env.OPENAI_API_KEY! },
    },
  },
});

const agent = new Agent({
  name: 'assistant',
  model: 'openai/gpt-6.1-sol',
  instructions: 'You are a helpful assistant.',
});

const result = await cog.run(agent, { input: 'Hello!' });
console.log(result.output);

await cog.close();

const cog = new Cogitator(config?: CogitatorConfig);

interface CogitatorConfig {
  llm?: {
    defaultProvider?: LLMProvider; // for model strings without a known provider prefix (default 'ollama')
    defaultModel?: string; // for agents that set no model
    providers?: LLMProvidersConfig; // API keys and URLs per provider
    backends?: Record<string, LLMBackend>; // your own backends, by name
    plugins?: Record<string, unknown>; // config for registerLLMBackend() plugins
    retry?: LLMRetryConfig | false; // default: 2 retries with backoff
    promptCache?: PromptCacheConfig | false; // default: on
  };
  limits?: {
    maxConcurrentRuns?: number; // runs over the limit wait in order
    defaultTimeout?: number; // ms, for agents and runs that set no timeout (default 120000)
    maxTokensPerRun?: number; // checked before each model call
  };
  memory?: MemoryConfig;
  runCheckpoints?: RunCheckpointStore; // where paused runs wait
  prompts?: PromptsConfig; // instruction versions and A/B tests
  sandbox?: SandboxManagerConfig;
  reflection?: ReflectionConfig;
  guardrails?: Partial<GuardrailConfig>;
  costRouting?: CostRoutingConfig;
  security?: { promptInjection?: Partial<PromptInjectionConfig>; pii?: PiiConfig };
  context?: ContextManagerConfig;
  logging?: LoggingConfig; // level, format and destination of the process-wide logger
  deploy?: DeployConfig; // read by `cogitator deploy`
}

const cog = new Cogitator({
  llm: {
    defaultProvider: 'ollama',
    providers: {
      ollama: { baseUrl: 'http://localhost:11434' },
      openai: { apiKey: process.env.OPENAI_API_KEY! },
      anthropic: { apiKey: process.env.ANTHROPIC_API_KEY! },
      google: { apiKey: process.env.GOOGLE_API_KEY! },
    },
  },
});

const result = await cog.run(agent, {
  input: 'Search for TypeScript tutorials',
  threadId: 'session-123',
  stream: true,
  onToken: (token) => process.stdout.write(token),
  onToolCall: (call) => console.log('Tool:', call.name),
  onToolResult: (result) => console.log('Result:', result),
});

interface RunResult {
  output: string; // final answer text
  structured?: unknown; // parsed JSON for json / json_schema agents
  runId: string;
  agentId: string;
  threadId: string;
  modelUsed?: string; // differs from agent.model under cost routing
  usage: {
    inputTokens: number;
    outputTokens: number;
    totalTokens: number;
    cost: number; // USD, from the model registry's prices
    duration: number; // ms
    reasoningTokens?: number;
    cachedInputTokens?: number;
    cacheWriteTokens?: number;
  };
  reasoning?: string; // reasoning summary, when asked for
  prompt?: RunPrompt; // instruction version / A/B variant used
  handoffs?: HandoffEvent[];
  finalAgent?: string; // the agent that answered after handoffs
  status?: 'completed' | 'paused';
  pendingApprovals?: ToolApprovalRequest[]; // when paused
  checkpoint?: RunCheckpoint; // when paused, for cog.resume()
  toolCalls: ToolCall[];
  messages: Message[];
  trace: { traceId: string; spans: Span[] };
  reflections?: Reflection[];
  reflectionSummary?: ReflectionSummary;
}

const paused = await cog.run(agent, { input: 'Refund order 42', threadId, userId });

if (paused.status === 'paused') {
  const result = await cog.resume(agent, threadId, {
    userId,
    decisions: { [paused.pendingApprovals![0].toolCallId]: { approved: true } },
  });
}

await cog.prompts.deploy(agent, 'You write release notes. Lead with what changed for the user.');
const result = await cog.run(agent, { input });
result.prompt; // { key: 'assistant', versionId: '...', version: 2 }

const estimate = await cog.estimateCost({
  agent,
  input: 'Analyze this document and summarize key points',
  options: { assumeIterations: 3, assumeToolCalls: 5 },
});

console.log(`Expected cost: $${estimate.expectedCost.toFixed(4)}`);
console.log(`Confidence: ${(estimate.confidence * 100).toFixed(0)}%`);

cog.tools.register(myGlobalTool);

const memory = await cog.getMemory(); // undefined when memory is not configured

await cog.close();