@odla-ai/ai 0.1.0

package/llms.txt

@@ -0,0 +1,111 @@
+# @odla-ai/ai — LLM context
+
+One general-purpose interface for AI inference across Anthropic (Claude), OpenAI
+(GPT), and Google (Gemini) — text, image, and audio — plus a tool-use agent
+engine and an eval harness. Library-only: import in-process, bring your own keys.
+Isomorphic (Node 20+, Cloudflare Workers, browser). Provider SDKs are lazy-loaded.
+
+## Install
+
+    npm i @odla-ai/ai
+    # provider SDKs are peer-lazy-loaded; install those you use:
+    #   @anthropic-ai/sdk  openai  @google/genai
+    # optional, for odla-db-backed storage + secrets:
+    #   @odla-ai/db
+
+## Core call
+
+    import { init } from "@odla-ai/ai";
+    const ai = init({ keys: { anthropic: KEY, openai: KEY, google: KEY }, defaultModel: "claude-opus-4-8" });
+    const res = await ai.chat({ model: "gpt-5", messages: [{ role: "user", content: "hi" }], maxTokens: 256 });
+    // res.content: OracleContentBlock[]  (text/tool_use/thinking)
+
+- `ai.stream(input)` → async iterable of normalized events: message_start →
+  content_block_start → content_block_delta {text_delta|thinking_delta|input_json_delta}
+  → content_block_stop → message_delta → message_stop (plus `error`).
+- `ai.extract<T>({ model, user, tool })` → forced tool call; returns a parsed object.
+- `ai.search({ model, user })` → web-search-grounded prose.
+
+## Content blocks (multimodal)
+
+text; image { source: base64|url }; audio { source: base64|url }; document (PDF);
+tool_use { id, name, input }; tool_result { toolUseId, content }; thinking.
+Audio input is accepted by OpenAI (`gpt-audio`) and Google, NOT by Claude — an
+audio block to a Claude model throws CapabilityError before any network call.
+
+## Agents
+
+    import { runAgent, type Persona, type ToolDef } from "@odla-ai/ai";
+    const add: ToolDef = { name: "add", description: "add", inputSchema: {...}, handler: (i) => ({ content: String(i.a + i.b) }) };
+    const persona: Persona = { name: "calc", model: "claude-opus-4-8", system: "...", tools: [add], maxSteps: 4 };
+    const run = await runAgent(ai, persona, { input: "what is 21+21?" });
+    // run.finalText, run.toolCalls, run.usage, run.steps, run.stoppedReason
+
+Tools may carry taint labels (outputTaint / acceptsTaint) for a CaMeL-style
+prompt-injection gate. Personas may carry a MemoryScope.
+
+## Skills
+
+A Skill = { name, instructions?, tools: ToolDef[] } is a bundle you attach to a
+persona (persona.skills); its tools merge into the model's tool list and its
+instructions into the system prompt. Turn an odla-db entity into CRUD tools:
+
+    import { entityCrudSkill } from "@odla-ai/ai";
+    const todos = entityCrudSkill({ db, entity: "todos", fields: { text: { type: "string" }, done: { type: "boolean" } }, required: ["text"] });
+    // → tools: list_todos, create_todo, update_todo (partial), delete_todo — handlers write to odla-db
+    const run = await runAgent(ai, { name: "todo-bot", model: "gpt-5", skills: [todos] }, { input: "add buy milk" });
+
+## Evals
+
+    import { evaluate, exactMatch, llmJudge } from "@odla-ai/ai";
+    const report = await evaluate({ inference: ai, model: "claude-opus-4-8", grader: exactMatch(), cases: [{ input, expected }] });
+    // graders: exactMatch, includes, structuredMatch, llmJudge; pass a persona to eval an agent.
+
+## Storage + BYO keys via odla-db (@odla-ai/db) — the handshake
+
+Follows odla-db's model. An agent never takes a platform secret; it does a
+device-authorization handshake for a scoped, revocable token, then provisions.
+
+    import { requestToken, init as odlaInit } from "@odla-ai/db";
+    import { provisionAgentApp, odlaDbKeyResolver, OdlaDbMemory, persistRun, init } from "@odla-ai/ai";
+
+    // 1. Handshake: the human supplies the endpoint and approves a short code in odla-db Studio.
+    const { token } = await requestToken({ endpoint: ODLA_URL, onCode: ({ userCode }) => show(userCode) });
+
+    // 2. Provision: create app, mint app key, push agent schema, store BYO provider keys as secrets.
+    const { appId, appKey } = await provisionAgentApp({ endpoint: ODLA_URL, token, providerKeys: { openai: OPENAI_KEY } });
+
+    // 3. Runtime: read keys from odla-db secrets; persist memory + run traces.
+    const db = odlaInit({ appId, adminToken: appKey, endpoint: ODLA_URL });
+    const ai = init({ resolveKey: odlaDbKeyResolver(db) });
+    const persona = { name: "assistant", model: "gpt-5", memory: new OdlaDbMemory({ db, sessionId: "user-42" }) };
+    const run = await runAgent(ai, persona, { input: "hello" });
+    await persistRun(run, { db, sessionId: "user-42" });
+
+Secrets are read-only from the app key (odlaDbKeyResolver → db.secrets.get); they
+are WRITTEN only with the operator/dev token via provisionAgentApp/putSecret. Keys
+are AES-GCM-encrypted at rest in odla-db and never returned to browser clients.
+
+## Errors
+
+Every error is an OdlaAIError subclass with a stable `code` — branch on err.code:
+config, auth, rate_limit, capability_unsupported, context_window, invalid_request,
+tool_input_invalid, provider_error.
+
+## Models
+
+- `claude-opus-4-8` (anthropic) — text, image, tools, thinking, effort, web-search, structured
+- `claude-sonnet-5` (anthropic) — text, image, tools, thinking, effort, web-search, structured
+- `claude-fable-5` (anthropic) — text, image, tools, thinking, effort, web-search, structured
+- `claude-haiku-4-5` (anthropic) — text, image, tools, structured
+- `gpt-5.5` (openai) — text, image, tools, effort, structured
+- `gpt-5` (openai) — text, image, tools, effort, structured
+- `gpt-5-mini` (openai) — text, image, tools, effort, structured
+- `gpt-4o` (openai) — text, image, tools, structured
+- `gpt-audio` (openai) — text, audio, tools, structured
+- `gemini-2.5-pro` (google) — text, image, audio, tools, thinking, effort, web-search, structured
+- `gemini-2.5-flash` (google) — text, image, audio, tools, thinking, effort, web-search, structured
+- `gemini-2.0-flash` (google) — text, image, audio, tools, web-search, structured
+
+Model ids live in a data catalog and drift — verify against provider docs; extend
+via buildCatalog / init({ catalog }).

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@odla-ai/ai",
+  "version": "0.1.0",
+  "description": "One general-purpose interface for AI inference across Anthropic (Claude), OpenAI, and Google (Gemini) — text, image, and audio — plus a tool-use agent engine and eval harness. The place every odla app reaches for when it needs AI. Isomorphic: Node 20+, Cloudflare Workers, the browser.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "llms.txt"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "odla",
+    "odla-ai",
+    "ai",
+    "llm",
+    "claude",
+    "anthropic",
+    "openai",
+    "gpt",
+    "google",
+    "gemini",
+    "agent",
+    "inference",
+    "multimodal",
+    "tool-use"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "smoke": "tsx scripts/smoke.ts",
+    "gen:llms": "tsx -e \"import('./src/index.ts').then(m => process.stdout.write(m.generateLlmsTxt()))\" > llms.txt",
+    "check:publish": "tsx scripts/check-publish-safety.ts",
+    "prepublishOnly": "npm run build && npm run check:publish"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.70.0",
+    "@google/genai": "^1.0.0",
+    "openai": "^6.0.0"
+  },
+  "peerDependencies": {
+    "@odla-ai/db": "^0.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@odla-ai/db": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@odla-ai/db": "^0.2.1",
+    "@types/node": "^22.10.0",
+    "tsup": "^8.3.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.2",
+    "vitest": "^3.0.0"
+  }
+}