AI - Talos

The @talosjs/ai component is a multi-provider AI toolkit. It exposes a single, consistent API for text generation, streaming, structured output, and function calling across 300+ models (OpenAI, Anthropic, Google, Groq, Ollama, and more) through OpenRouter. You build three kinds of classes (chats, tools, and middleware), register them with a decorator, and resolve them from the container.

What you get

Switching providers is a matter of changing the provider/model string passed to getModel(); nothing else moves. Chats, tools, and middleware are all dependency-injected classes you compose as you like, with TypeScript types throughout, schema-validated tool inputs, and structured run output. Tool and function calling, streaming events, and the agentic loop are supported directly. For operations, the component gives you structured exceptions, input validation, and lifecycle hooks you can use for auditing and metrics.

How it works

A chat is the unit you run. When you call run() or stream(), the component:

Builds the message list from your system prompts, history, and the new prompt.
Resolves the chat’s tool and middleware classes from the container.
Creates an OpenRouter adapter from getModel().
Runs the agentic loop. The model may call tools, whose results feed back into the conversation.
Returns the final text, a validated structured object, or a stream of events.

The three building blocks:

Block	Decorator	Implements	Role
Chat	`@decorator.chat()`	extends `Chat`	Defines the model, system prompts, tools, and middleware; you run it.
Tool	`@decorator.tool()`	`ITool`	A function the model can call (search, fetch, mutate data).
Middleware	`@decorator.middleware()`	`IMiddleware`	Observes or augments the run via lifecycle hooks.

Environment variables

The core API talks to OpenRouter; the bundled tools read their own provider keys from the app environment. Keys are read lazily, so a missing key fails when the tool is called rather than at startup.

Variable	Used by	Purpose
`SEARCH_BRIGHTDATA_API_KEY`	Bright Data search tool	Google SERP access.
`SEARCH_BRIGHTDATA_SERP_ZONE`	Bright Data search tool	Optional zone name (auto-created if omitted).
`SEARCH_EXA_API_KEY`	Exa search tool	Exa web search.
`SEARCH_FIRECRAWL_API_KEY`	Firecrawl search tool	Firecrawl search (optional; free tier available).
`SEARCH_PUBMED_API_KEY`	PubMed search tool	PubMed search (optional for free tier).

Tools read keys through the injected app environment, so define them in your .env and inject AppEnv into the tool class.

Decorators and usage

`@decorator.chat()`

Registers a Chat subclass with the container. You implement four getters: the model, the system prompts, the tools, and the middleware.

import type { AiMiddlewareClassType, AiToolClassType } from "@talosjs/ai";
import { Chat, decorator } from "@talosjs/ai";

@decorator.chat()
export class SupportChat extends Chat {
  public getModel = (): string => "anthropic/claude-sonnet-4.5";

  public getSystemPrompts = (): string[] => [
    "You are a helpful support agent.",
  ];

  public getTools = (): AiToolClassType[] => [];

  public getMiddlewares = (): AiMiddlewareClassType[] => [];
}

Run it by resolving it from the container:

import { container } from "@talosjs/container";

const chat = container.get(SupportChat);
const reply = await chat.run<string>({ prompt: "Help with a billing issue" });

The model id is always in provider/model form, for example anthropic/claude-sonnet-4.5, openai/gpt-4.1, or google/gemini-2.5-pro.

`@decorator.tool()`

Registers a tool the model can call. Implement getName() (snake_case, the name the model sees), getDescription() (tells the model when to call it), getInputSchema() (validated before your handler runs), and handler().

import type { ITool } from "@talosjs/ai";
import { decorator } from "@talosjs/ai";
import { Assert, type AssertType } from "@talosjs/validation";

export type WebSearchToolInputType = {
  query: string;
};

@decorator.tool()
export class WebSearchTool
  implements ITool<WebSearchToolInputType, Promise<unknown>>
{
  public getName = (): string => "web_search";

  public getDescription = (): string =>
    "Search the web for recent information. Call when the user asks about current events.";

  public getInputSchema = (): AssertType =>
    Assert({
      query: "string > 0",
    });

  public handler = async (param: WebSearchToolInputType): Promise<unknown> => {
    const { query } = param;
    // Input is already validated against the schema before this runs.
    return query;
  };
}

Add it to a chat’s getTools():

public getTools = (): AiToolClassType[] => [WebSearchTool];

A set of ready-made tools also ships with the component (Bright Data, Exa, Firecrawl, Wikipedia, PubMed, Linear search/create/update/delete). Drop their classes into getTools() to use them.

`@decorator.middleware()`

Registers middleware that observes the run through lifecycle hooks. Implement only the hooks you need.

import type {
  ChatMiddlewareContext,
  ErrorInfo,
  FinishInfo,
  IMiddleware,
} from "@talosjs/ai";
import { decorator } from "@talosjs/ai";

@decorator.middleware()
export class AuditMiddleware implements IMiddleware {
  public readonly events: string[] = [];

  public getName = (): string => "audit";

  public onStart = (ctx: ChatMiddlewareContext): void => {
    this.events.push(`start: ${ctx.requestId} on ${ctx.model}`);
  };

  public onFinish = (ctx: ChatMiddlewareContext, info: FinishInfo): void => {
    this.events.push(`finish: ${ctx.requestId} in ${info.duration}ms`);
  };

  public onError = (ctx: ChatMiddlewareContext, info: ErrorInfo): void => {
    this.events.push(
      `error: ${ctx.requestId} after ${info.duration}ms (${String(info.error)})`,
    );
  };
}

Hooks fire across the run in order: setup → onConfig → onStart → onBeforeModel → streaming (onChunk) → onToolPhaseComplete → onUsage, then one terminal hook (onFinish, onError, or onAbort). Add the class to a chat’s getMiddlewares().

Running chats

Structured output

Pass a schema and the run returns a validated object instead of free text.

import { Assert } from "@talosjs/validation";

const schema = Assert({
  summary: "string",
  priority: "'high' | 'medium' | 'low'",
});

const result = await chat.run<typeof schema.infer>({
  prompt: "Summarize and categorize this ticket...",
  outputSchema: schema,
});
// result.priority is "high" | "medium" | "low"

Streaming

for await (const event of chat.stream({ prompt: "Explain AI" })) {
  if (event.type === "TEXT_MESSAGE_CONTENT") {
    process.stdout.write(event.delta);
  }
}

Context, history, and sampling

await chat.run<string>({
  prompt: "List my open issues",
  messages: [
    { role: "user", content: "My payment failed" },
    { role: "assistant", content: "Let me help with that." },
  ],
  context: { userId: "user-123" }, // available to tools and middleware
  temperature: 0.7,
  maxTokens: 500,
});

Exceptions

The component throws AiException for AI-specific failures: a tool handler error, an invalid response, a missing key, or a failed run. It carries a machine-readable key, a human-readable message, and a frozen data object.

import { AiException } from "@talosjs/ai";

try {
  await chat.run({ prompt: "..." });
} catch (error) {
  if (error instanceof AiException) {
    logger.error(`AI error [${error.key}]: ${error.message}`, error.data);
  } else {
    throw error;
  }
}

When you throw from inside a tool, follow the same shape so callers can branch on key:

throw new AiException(
  "Search provider returned invalid JSON",
  "SEARCH_INVALID_JSON",
  { query, statusCode: 500 },
);

Working effectively

Keep model selection in getModel() rather than at the call site, so a single edit swaps providers for every caller of that chat. A tool’s getName() and getDescription() are how the model decides when to call it, so write them for the model: be specific about when to call the tool and what it returns. Because getInputSchema() runs before your handler, you can narrow the input type inside the handler without re-validating. Favor single-purpose tools. One tool does one job and the model composes them, which works better than a single multi-mode tool. Cross-cutting concerns (logging, metrics, auditing, per-iteration tweaks) belong in middleware, not inside tools or chats. Pass per-run data through context instead of globals; it reaches every tool and middleware while keeping them stateless. When you throw AiException, keep the key stable so callers can branch on it, and put the variable detail in data. For results a program will consume, an outputSchema beats parsing free text.

CLI commands

Scaffold each building block with its generator. Each command creates the class and a matching test file under the target module, and installs @talosjs/ai if it is missing.

# Chat — modules/<module>/src/ai/chats/<Name>Chat.ts
talos ai:chat:create --name=Support --module=help

# Tool — modules/<module>/src/ai/tools/<Name>Tool.ts
talos ai:tool:create --name=WebSearch --module=help

# Middleware — modules/<module>/src/ai/middlewares/<Name>Middleware.ts
talos ai:middleware:create --name=Audit --module=help

Option	Description	Default
`--name`	Class name. Normalized to PascalCase with the `Chat` / `Tool` / `Middleware` suffix appended.	Prompted if omitted
`--module`	Target module the class is created in.	`shared`
`--override`	Overwrite the files if they already exist.	`false`

See ai:chat:create, ai:tool:create, and ai:middleware:create for full command references.

Use with Claude and Codex

Each generator ships a matching skill that runs the scaffold and then guides your AI agent through completing the class: the chat’s model, prompts, tools, and middleware; a tool’s description, schema, and handler; or a middleware’s lifecycle hooks. Initialize the skills once for your agent:

Claude
Codex

talos agent:skills:create

Then ask Claude in natural language. It maps the request to the right generator, runs it, and fills in the implementation:

Prompt

Create an AI chat that answers support questions using anthropic/claude-sonnet-4.5, with a web_search tool and an audit middleware.

talos agent:skills:create

Then ask Codex the same way; it maps the request to the right generator, runs it, and fills in the implementation:

Prompt

Create an AI chat that answers support questions using anthropic/claude-sonnet-4.5, with a web_search tool and an audit middleware.

For example, the prompt above maps to ai:chat:create --name=Support, then generates the matching ai:tool:create --name=WebSearch and ai:middleware:create --name=Audit classes and wires them into the chat.

Getting Started

AI

Framework

Command Line

AI

What you get

How it works

Environment variables

Decorators and usage

`@decorator.chat()`

`@decorator.tool()`

`@decorator.middleware()`

Running chats

Structured output

Streaming

Context, history, and sampling

Exceptions

Working effectively

CLI commands

Use with Claude and Codex

​What you get

​How it works

​Environment variables

​Decorators and usage

​@decorator.chat()

​@decorator.tool()

​@decorator.middleware()

​Running chats

​Structured output

​Streaming

​Context, history, and sampling

​Exceptions

​Working effectively

​CLI commands

​Use with Claude and Codex

What you get

How it works

Environment variables

Decorators and usage

`@decorator.chat()`

`@decorator.tool()`

`@decorator.middleware()`

Running chats

Structured output

Streaming

Context, history, and sampling

Exceptions

Working effectively

CLI commands

Use with Claude and Codex