@netscript/ai

The provider-agnostic AI engine core for NetScript: a composition root, a global model registry, the domain vocabulary and capability ports for chat/embeddings/vision/tools/agents/MCP, and a set of opt-in provider adapters. This page is generated from the package's public surface with deno doc (US-2). For the full index of packages and plugins return to the reference overview.

The base @netscript/ai entrypoint takes no @netscript/* runtime dependency and pulls no provider SDK into the module graph. Provider adapters (Anthropic, OpenAI-compatible, OpenRouter, Ollama, OpenAI embeddings/vision) live on separate subpath exports and self-register into the shared registry as a side effect of being imported — so an application chooses its providers with one-line side-effect imports and only those SDKs enter the graph:

import "@netscript/ai/anthropic"; // self-registers the 'anthropic' provider
import { getModel } from "@netscript/ai";

const handle = await getModel("anthropic:claude-sonnet-4-5");

Export map

The package publishes the following entrypoints. Each is generated from its own deno doc surface.

Composition root and model registry (@netscript/ai)

The root entrypoint is the composition root plus the model-registry accessors. Model providers are resolved through a module-level registry (not stored on the runtime), so provider packages self-register independently of runtime construction.

Runtime capability ports and their defaults

createAiRuntime injects each capability port, defaulting any omitted field to a no-op or a throwing "unconfigured" port. Model providers are not on the runtime — they are resolved from the global registry.

Domain contracts (@netscript/ai/contracts)

The provider-neutral vocabulary. The tables below list the primary surface; the module is the source of truth via deno doc packages/ai/src/contracts/mod.ts.

Capability ports (@netscript/ai/ports)

The capability seams the engine is programmed against, their default implementations, and the model/embedding/vision registries. Primary surface:

Model providers

Each provider lives on its own subpath. Importing the subpath self-registers the provider under its stable id and re-exports the adapter class and config type for direct construction. All chat adapters translate the wrapped SDK to the owned chat vocabulary — no provider-SDK type escapes the public surface — and support per-turn cancellation through the chat client's stream(_, { signal }) option.

@netscript/ai/anthropic

Registry id "anthropic". Wraps @tanstack/ai-anthropic; the model catalog is taken verbatim from the wrapped package's ANTHROPIC_MODELS.

@netscript/ai/openai-compatible

Registry id "openai-compatible". Wraps @tanstack/ai-openai/compatible for any endpoint that speaks the OpenAI wire (its own base URL, key, and model list).

When baseURL or apiKey is missing, createChatClient throws AiNotConfiguredError (the provider still lists and reports its configured models).

@netscript/ai/openrouter

Registry id "openrouter". Reuses the OpenAI-compatible transport pinned to OpenRouter, with the one wire divergence being reasoning: OpenRouter expects a top-level reasoning: { effort } object.

@netscript/ai/ollama

Registry id "ollama". Reuses the OpenAI-compatible transport pinned to a local Ollama daemon at {host}/v1, with a reachability preflight and a placeholder key (Ollama ignores authorization).

@netscript/ai/openai-embeddings

Registry id "openai-embeddings", registered for both the embedding and vision capabilities. Speaks the OpenAI-compatible HTTP API directly with Web fetch (no provider SDK).

Tools (@netscript/ai/tools)

Define server-executable (or client-deferred) tools, validate their input with Standard Schema (bring any conforming schema — zod, valibot, arktype, or hand-written), and dispatch them through an in-memory registry that satisfies ToolRegistryPort. The core adds no schema DSL and takes no @netscript/* dependency.

Agent loop (@netscript/ai/agent)

The E3 agent loop drives a bounded, cancellable model/tool interaction and emits AgentChunks. It consumes its collaborators purely by factory injection — importing this subpath pulls no provider SDK.

The subpath also re-exports the seams the loop is programmed against (AgentLoopPort, ChatClientPort / ChatModelProviderPort and their event types, ToolRegistryPort) so it is a self-contained wiring surface.

MCP (@netscript/ai/mcp)

MCP transport adapters and tool registration: stdio, reconnectable Streamable-HTTP, injected auth modes, and lifecycle state.

Testing (@netscript/ai/testing)

Deterministic fakes for unit-testing code built on the ports. This subpath is excluded from the provider dependency graph.

Configuration

@netscript/ai reads no @netscript/* config surface — capabilities are wired through AiRuntimeConfig (see runtime capability ports) and providers through their config bags. Two adapters resolve an API key from the environment when apiKey is omitted:

The openai-compatible, openai-embeddings, and ollama providers do not read the environment. Pass apiKey (and baseURL/host) explicitly — commonly from Deno.env.get(...) in your composition code. Reading a key from the environment requires --allow-env for the variable in question.

Examples

Compose a runtime

import { createAiRuntime } from "@netscript/ai";

const ai = createAiRuntime();
// Telemetry defaults to a no-op port — safe to call with nothing wired.
ai.telemetry.recordEvent("agent.start");

Register a provider and resolve a model

import "@netscript/ai/anthropic"; // self-registers the 'anthropic' provider
import { getModel } from "@netscript/ai";

const handle = await getModel("anthropic:claude-sonnet-4-5");

Configure an OpenAI-compatible endpoint

import "@netscript/ai/openai-compatible"; // self-registers the provider
import { getModelProvider } from "@netscript/ai";

const provider = getModelProvider("openai-compatible", {
  baseURL: "https://api.deepseek.com/v1",
  apiKey: Deno.env.get("DEEPSEEK_KEY"),
  models: ["deepseek-chat", "deepseek-reasoner"],
});

Stream a reasoning turn through OpenRouter

import "@netscript/ai/openrouter"; // self-registers the provider
import { getModelProvider } from "@netscript/ai";

const provider = getModelProvider("openrouter", {
  apiKey: Deno.env.get("OPENROUTER_API_KEY"),
  models: ["anthropic/claude-sonnet-4.5"],
  reasoningEffort: "high",
});

Preflight a local Ollama daemon

import "@netscript/ai/ollama"; // self-registers the provider
import { getModelProvider } from "@netscript/ai";

const provider = getModelProvider("ollama", { models: ["llama3.2"] });
const health = await provider.checkReachable();
if (!health.reachable) {
  console.warn(`Ollama is down: ${health.detail}`);
}

Define, register, and dispatch a tool

import { createToolRegistry, defineAiTool } from "@netscript/ai/tools";

const add = defineAiTool("add")
  .parameters({
    type: "object",
    properties: { a: { type: "number" }, b: { type: "number" } },
    required: ["a", "b"],
  })
  .input(myAddSchema) // any StandardSchemaV1<unknown, { a: number; b: number }>
  .server(({ a, b }) => ({ sum: a + b }));

const registry = createToolRegistry([add]);
const { output } = await registry.dispatch("add", { a: 2, b: 3 });

Drive a bounded, cancellable agent loop

import { createAgentLoop, slidingWindowHistory } from "@netscript/ai/agent";

const loop = createAgentLoop({
  modelProvider, // a ChatModelProviderPort
  tools, // a ToolRegistryPort
  history: slidingWindowHistory({ maxMessages: 12 }),
});

for await (const chunk of loop.run({ model: "anthropic:claude-sonnet-4-5", messages })) {
  if (chunk.type === "text") console.log(chunk.delta);
  if (chunk.type === "done") console.log(chunk.usage);
}

Register MCP tools over Streamable-HTTP

import { createMcpTransport, registerMcpTools } from "@netscript/ai/mcp";
import { createToolRegistry } from "@netscript/ai/tools";

const transport = createMcpTransport({
  kind: "streamable-http",
  serverId: "search",
  url: "https://mcp.example.com",
  auth: { mode: "api-token", token: "injected-at-runtime", scheme: "Bearer" },
});

const registry = createToolRegistry();
await registerMcpTools(registry, transport);

Back to the reference overview.