@moikapy/origen 0.3.0

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@moikapy/origen",
+  "version": "0.3.0",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./models": "./src/models.ts",
+    "./soul": "./src/soul.ts",
+    "./adapter": "./src/adapter.ts"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@mariozechner/pi-agent-core": "^0.73.0",
+    "@mariozechner/pi-ai": "^0.73.0",
+    "zod": "^4.4.2"
+  },
+  "devDependencies": {
+    "typescript": "^5",
+    "vitest": "^3"
+  },
+  "license": "MIT"
+}

package/src/adapter.ts

@@ -0,0 +1,364 @@
+/**
+ * Adapter: bridges Origen's simple types to pi-agent-core/pi-ai types.
+ *
+ * - OrigenTool → AgentTool (injects D1Provider)
+ * - pi-ai Model resolution (OpenRouter, Ollama, Anthropic, Google)
+ * - StreamEvent translation (AgentEvent → Origen's StreamEvent)
+ */
+
+import { getModel } from "@mariozechner/pi-ai";
+import type { Model, Api, Message, Context, Tool } from "@mariozechner/pi-ai";
+import type { AgentTool, AgentEvent, AgentMessage } from "@mariozechner/pi-agent-core";
+import type { OrigenTool, StreamEvent } from "./agent";
+import type { D1Provider, Citation, UsageInfo } from "./types";
+
+// ── Tool adapter ─────────────────────────────────────────────────────
+
+/**
+ * Convert an OrigenTool into a pi-agent-core AgentTool.
+ * The D1Provider is captured in closure so the tool's execute gets it.
+ */
+export function adaptTool(tool: OrigenTool, getD1: D1Provider): AgentTool {
+  return {
+    name: tool.name,
+    description: tool.description,
+    // Convert JSON schema to TypeBox format — pi-agent-core uses TypeBox
+    // but accepts plain JSON schemas for the tool definition sent to the LLM.
+    // We provide parameters as a TypeBox-like schema.
+    parameters: {
+      type: "object",
+      ...tool.parameters,
+    } as any,
+    label: tool.name,
+    execute: async (_toolCallId, params, _signal) => {
+      const result = await tool.execute(params as Record<string, unknown>, getD1);
+      return {
+        content: [{ type: "text" as const, text: result }],
+        details: {},
+      };
+    },
+  };
+}
+
+/** Adapt all OrigenTools for an Agent instance. */
+export function adaptTools(tools: OrigenTool[], getD1: D1Provider): AgentTool[] {
+  return tools.map((t) => adaptTool(t, getD1));
+}
+
+// ── Model resolution ──────────────────────────────────────────────────
+
+export interface ModelResolutionOptions {
+  /** Ollama base URL, e.g. "http://localhost:11434/v1" */
+  ollamaBaseUrl?: string;
+}
+
+/** Known Ollama models that don't exist in pi-ai's generated registry. */
+const OLLAMA_MODELS: Record<string, Partial<Model<Api>>> = {
+  "ollama/llama3": {
+    id: "llama3",
+    name: "Llama 3 (Ollama)",
+    api: "openai-completions",
+    provider: "ollama",
+    baseUrl: "http://localhost:11434/v1",
+    reasoning: false,
+    input: ["text"],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8192,
+    maxTokens: 4096,
+  },
+  "ollama/gemma3": {
+    id: "gemma3",
+    name: "Gemma 3 (Ollama)",
+    api: "openai-completions",
+    provider: "ollama",
+    baseUrl: "http://localhost:11434/v1",
+    reasoning: false,
+    input: ["text"],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8192,
+    maxTokens: 4096,
+  },
+  "ollama/mistral": {
+    id: "mistral",
+    name: "Mistral (Ollama)",
+    api: "openai-completions",
+    provider: "ollama",
+    baseUrl: "http://localhost:11434/v1",
+    reasoning: false,
+    input: ["text"],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32768,
+    maxTokens: 4096,
+  },
+  "ollama/qwen3": {
+    id: "qwen3",
+    name: "Qwen 3 (Ollama)",
+    api: "openai-completions",
+    provider: "ollama",
+    baseUrl: "http://localhost:11434/v1",
+    reasoning: false,
+    input: ["text"],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32768,
+    maxTokens: 4096,
+  },
+  "ollama/deepseek-r1": {
+    id: "deepseek-r1",
+    name: "DeepSeek R1 (Ollama)",
+    api: "openai-completions",
+    provider: "ollama",
+    baseUrl: "http://localhost:11434/v1",
+    reasoning: true,
+    input: ["text"],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 65536,
+    maxTokens: 8192,
+  },
+};
+
+const DEFAULT_MODEL: Model<Api> = {
+  id: "openrouter/free",
+  name: "Free (Auto)",
+  api: "openai-completions",
+  provider: "openrouter",
+  baseUrl: "https://openrouter.ai/api/v1",
+  reasoning: false,
+  input: ["text"],
+  cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+  contextWindow: 128000,
+  maxTokens: 4096,
+};
+
+/**
+ * Resolve a model ID string to a pi-ai Model object.
+ * Tries pi-ai's registry first, then falls back to built-in Ollama definitions.
+ */
+export function resolveModel(modelId: string, options?: ModelResolutionOptions): Model<Api> {
+  // Try Ollama models first
+  if (modelId.startsWith("ollama/")) {
+    const ollamaDef = OLLAMA_MODELS[modelId];
+    if (ollamaDef) {
+      const baseUrl = options?.ollamaBaseUrl ?? ollamaDef.baseUrl ?? "http://localhost:11434/v1";
+      return {
+        ...DEFAULT_MODEL,
+        ...ollamaDef,
+        baseUrl,
+        compat: {
+          supportsStore: false,
+          supportsDeveloperRole: false,
+          supportsReasoningEffort: false,
+          supportsUsageInStreaming: false,
+          maxTokensField: "max_tokens",
+          requiresToolResultName: false,
+          requiresAssistantAfterToolResult: false,
+          requiresThinkingAsText: true,
+          requiresReasoningContentOnAssistantMessages: false,
+          thinkingFormat: "openai",
+          supportsStrictMode: false,
+          supportsLongCacheRetention: false,
+        },
+      } as Model<Api>;
+    }
+    // Generic Ollama model: user typed a custom model name
+    const customId = modelId.replace("ollama/", "");
+    return {
+      ...DEFAULT_MODEL,
+      id: customId,
+      name: `${customId} (Ollama)`,
+      provider: "ollama",
+      baseUrl: options?.ollamaBaseUrl ?? "http://localhost:11434/v1",
+      compat: {
+        supportsStore: false,
+        supportsDeveloperRole: false,
+        supportsReasoningEffort: false,
+        supportsUsageInStreaming: false,
+        maxTokensField: "max_tokens",
+        requiresToolResultName: false,
+        requiresAssistantAfterToolResult: false,
+        requiresThinkingAsText: true,
+        requiresReasoningContentOnAssistantMessages: false,
+        thinkingFormat: "openai",
+        supportsStrictMode: false,
+        supportsLongCacheRetention: false,
+      },
+    } as Model<Api>;
+  }
+
+  // Try pi-ai's model registry (OpenRouter, Anthropic, Google, etc.)
+  // pi-ai groups by provider, so we try known providers
+  const providers = ["openrouter", "anthropic", "google", "openai", "deepseek", "groq", "xai"];
+  for (const provider of providers) {
+    try {
+      const model = getModel(provider as any, modelId as any);
+      if (model) return model as Model<Api>;
+    } catch {
+      // Not found in this provider, try next
+    }
+  }
+
+  // Fallback: create a generic OpenRouter-compatible model
+  return {
+    ...DEFAULT_MODEL,
+    id: modelId,
+    name: modelId,
+  };
+}
+
+// ── Message conversion ────────────────────────────────────────────────
+
+/** Convert Origen's simple messages to pi-ai Message format. */
+export function convertMessages(
+  messages: Array<{ role: "user" | "assistant"; content: string }>
+): Message[] {
+  return messages.map((m) => ({
+    role: m.role,
+    content: m.content as any,
+    timestamp: Date.now(),
+  })) as Message[];
+}
+
+// ── Context builder ───────────────────────────────────────────────────
+
+/** Build a pi-ai Context from Origen's config. */
+export function buildContext(
+  systemPrompt: string,
+  messages: Message[],
+  adaptedTools: AgentTool[]
+): Context {
+  return {
+    systemPrompt,
+    messages,
+    tools: adaptedTools.map((t) => ({
+      name: t.name,
+      description: t.description,
+      parameters: t.parameters,
+    })),
+  };
+}
+
+// ── Event translation ─────────────────────────────────────────────────
+
+/** Default citation extractor — [BOOK CHAPTER:VERSE] patterns. */
+function defaultCitationExtractor(text: string): Citation[] {
+  const citations: Citation[] = [];
+  const regex = /\[([A-Z]{3})\s+(\d+):(\d+)\]/g;
+  let match;
+  while ((match = regex.exec(text)) !== null) {
+    citations.push({ book: match[1], chapter: parseInt(match[2]), verse: parseInt(match[3]) });
+  }
+  return citations;
+}
+
+/** Translate a pi-agent-core AgentEvent into an Origen StreamEvent. */
+export function translateEvent(
+  event: AgentEvent,
+  extractCitations?: (text: string) => Citation[]
+): StreamEvent | null {
+  switch (event.type) {
+    case "message_update": {
+      const assistantEvent = event.assistantMessageEvent;
+      if (assistantEvent.type === "text_delta") {
+        return { type: "text" as const, content: assistantEvent.delta };
+      }
+      if (assistantEvent.type === "thinking_delta") {
+        return { type: "reasoning" as const, content: assistantEvent.delta };
+      }
+      return null;
+    }
+    case "tool_execution_start": {
+      return {
+        type: "tool_call" as const,
+        name: event.toolName,
+        args: event.args as Record<string, unknown>,
+      };
+    }
+    case "tool_execution_end": {
+      const resultText = event.result?.content
+        ?.filter((c: any) => c.type === "text")
+        .map((c: any) => c.text)
+        .join("\n") ?? "";
+      return {
+        type: "tool_result" as const,
+        name: event.toolName,
+        result: resultText,
+      };
+    }
+    case "agent_end": {
+      // Find the final assistant message
+      const assistantMsg = event.messages
+        .filter((m): m is any => m.role === "assistant")
+        .pop();
+      const text = assistantMsg?.content
+        ?.filter((c: any) => c.type === "text")
+        .map((c: any) => c.text)
+        .join("") ?? "";
+      const usage: UsageInfo | undefined = assistantMsg?.usage
+        ? {
+            promptTokens: assistantMsg.usage.input,
+            completionTokens: assistantMsg.usage.output,
+            totalCost: assistantMsg.usage.cost?.total,
+          }
+        : undefined;
+      const citFn = extractCitations ?? defaultCitationExtractor;
+      // Check for error
+      if (assistantMsg?.stopReason === "error" || assistantMsg?.stopReason === "aborted") {
+        return {
+          type: "error" as const,
+          message: assistantMsg.errorMessage ?? "Agent encountered an error",
+        };
+      }
+      return {
+        type: "done" as const,
+        message: text,
+        citations: citFn(text),
+        usage,
+      };
+    }
+    default:
+      return null;
+  }
+}
+
+/**
+ * Subscribe to an Agent and yield Origen StreamEvents.
+ * Handles the full lifecycle from agent_start to agent_end.
+ */
+export async function* agentToStreamEvents(
+  agent: any, // Agent from pi-agent-core
+  extractCitations?: (text: string) => Citation[]
+): AsyncGenerator<StreamEvent> {
+  const queue: StreamEvent[] = [];
+  let resolve: (() => void) | null = null;
+  let done = false;
+
+  const unsubscribe = agent.subscribe((event: AgentEvent) => {
+    const translated = translateEvent(event, extractCitations);
+    if (translated) {
+      queue.push(translated);
+      if (resolve) {
+        resolve();
+        resolve = null;
+      }
+    }
+    if (event.type === "agent_end") {
+      done = true;
+      if (resolve) {
+        resolve();
+        resolve = null;
+      }
+    }
+  });
+
+  try {
+    while (!done || queue.length > 0) {
+      if (queue.length > 0) {
+        yield queue.shift()!;
+        continue;
+      }
+      if (done) break;
+      await new Promise<void>((r) => { resolve = r; });
+    }
+  } finally {
+    unsubscribe();
+  }
+}

package/src/agent.ts

@@ -0,0 +1,219 @@
+/**
+ * Origen — Agent Engine (v0.3)
+ *
+ * Multi-provider agent harness built on pi-ai + pi-agent-core.
+ * Supports OpenRouter, Ollama, Anthropic, Google, and any OpenAI-compatible API.
+ * Soul.md personas, streaming, parallel tool execution, abort support.
+ */
+
+import { Agent } from "@mariozechner/pi-agent-core";
+import { streamSimple } from "@mariozechner/pi-ai";
+import type { AgentEvent } from "@mariozechner/pi-agent-core";
+import { z } from "zod";
+import {
+  adaptTools,
+  convertMessages,
+  buildContext,
+  agentToStreamEvents,
+  resolveModel,
+} from "./adapter";
+import { DEFAULT_MODEL_ID, THINKING_MODELS, type ModelId } from "./models";
+import type { D1Provider, Citation, UsageInfo } from "./types";
+
+// ── Tool definition ───────────────────────────────────────────────────
+
+/**
+ * A tool that the host app registers with Origen.
+ * Simple interface: name, description, JSON schema, and an execute function
+ * that receives (args, getD1). The adapter wraps this into pi-agent-core's AgentTool.
+ */
+export interface OrigenTool {
+  name: string;
+  description: string;
+  /** OpenAI function-calling parameter schema (JSON) */
+  parameters: Record<string, unknown>;
+  /** Zod schema for runtime validation (optional) */
+  inputSchema?: z.ZodType;
+  execute: (args: Record<string, unknown>, getD1: D1Provider) => Promise<string>;
+}
+
+// ── Agent configuration ───────────────────────────────────────────────
+
+export interface AgentConfig {
+  appName?: string;
+  systemPrompt?: string;
+  tools: OrigenTool[];
+  getD1: D1Provider;
+  model?: ModelId;
+  maxSteps?: number;
+  /** Custom citation extractor */
+  extractCitations?: (text: string) => Citation[];
+  /** Dynamic API key resolution per provider (e.g., for expiring OAuth tokens) */
+  getApiKey?: (provider: string) => Promise<string | undefined>;
+  /** Ollama base URL override (default: http://localhost:11434/v1) */
+  ollamaBaseUrl?: string;
+  /** Tool execution mode: "parallel" (default) or "sequential" */
+  toolExecution?: "sequential" | "parallel";
+  /** Abort signal for cancellation */
+  signal?: AbortSignal;
+  /** Reasoning/thinking level for models that support it */
+  thinkingLevel?: "off" | "minimal" | "low" | "medium" | "high";
+}
+
+// ── Auth check ────────────────────────────────────────
+
+export interface AuthCheckResult {
+  authenticated: boolean;
+  apiKey: string | null;
+  provider?: string;
+  error?: string;
+}
+
+/**
+ * Provider-aware auth check. Tests key availability for each provider.
+ * If no provider argument, checks OpenRouter + Ollama availability.
+ */
+export async function checkAuth(
+  getApiKey: ((provider: string) => Promise<string | undefined>) | (() => Promise<string | null>),
+): Promise<AuthCheckResult> {
+  // Normalize to per-provider signature
+  const getProviderKey = getApiKey.length >= 1
+    ? getApiKey as (provider: string) => Promise<string | undefined>
+    : async (provider: string) => {
+        const key = await (getApiKey as () => Promise<string | null>)();
+        return key ?? undefined;
+      };
+
+  // Try OpenRouter first
+  const orKey = await getProviderKey("openrouter");
+  if (orKey) return { authenticated: true, apiKey: orKey, provider: "openrouter" };
+
+  // Try Ollama
+  const ollamaKey = await getProviderKey("ollama");
+  if (ollamaKey) return { authenticated: true, apiKey: ollamaKey, provider: "ollama" };
+
+  // Try Anthropic
+  const anthropicKey = await getProviderKey("anthropic");
+  if (anthropicKey) return { authenticated: true, apiKey: anthropicKey, provider: "anthropic" };
+
+  return {
+    authenticated: false,
+    apiKey: null,
+    error: "Connect your OpenRouter account or configure Ollama to enable AI-powered study.",
+  };
+}
+
+/** Convenience: check OpenRouter auth only (backward compat). */
+export async function checkOpenRouterAuth(
+  getApiKey: () => Promise<string | null>
+): Promise<AuthCheckResult> {
+  const apiKey = await getApiKey();
+  if (!apiKey) {
+    return { authenticated: false, apiKey: null, error: "Connect your OpenRouter account to enable AI-powered study." };
+  }
+  return { authenticated: true, apiKey, provider: "openrouter" };
+}
+
+// ── Stream event types ─────────────────────────────────────────────────
+
+export type StreamEvent =
+  | { type: "reasoning"; content: string }
+  | { type: "tool_call"; name: string; args: Record<string, unknown> }
+  | { type: "tool_result"; name: string; result: string }
+  | { type: "text"; content: string }
+  | { type: "done"; message: string; citations: Citation[]; usage?: UsageInfo }
+  | { type: "error"; message: string };
+
+// ── Streaming agent call ───────────────────────────────────────────────
+
+export async function* streamOrigen(
+  messages: Array<{ role: "user" | "assistant"; content: string }>,
+  context: Record<string, unknown> | undefined,
+  config: AgentConfig,
+  apiKey?: string,
+): AsyncGenerator<StreamEvent> {
+  const systemPrompt = config.systemPrompt ?? `You are ${config.appName ?? "Origen"}, an AI assistant. Use your tools to help the user.`;
+  const modelId = config.model ?? DEFAULT_MODEL_ID;
+  const maxSteps = config.maxSteps ?? 5;
+  const extractCitations = config.extractCitations;
+
+  // Resolve model to pi-ai Model object
+  const model = resolveModel(modelId, { ollamaBaseUrl: config.ollamaBaseUrl });
+
+  // Adapt tools to AgentTool format
+  const adaptedTools = adaptTools(config.tools, config.getD1);
+
+  // Convert messages
+  let piMessages = convertMessages(messages);
+
+  // Inject context into last user message
+  if (context && piMessages.length > 0) {
+    const lastIdx = piMessages.length - 1;
+    const lastMsg = piMessages[lastIdx];
+    if (lastMsg.role === "user") {
+      piMessages[lastIdx] = {
+        ...lastMsg,
+        content: `[Context: ${JSON.stringify(context)}] ${typeof lastMsg.content === "string" ? lastMsg.content : ""}`,
+      };
+    }
+  }
+
+  // Resolve API key per provider
+  const resolveApiKey = async (provider: string): Promise<string | undefined> => {
+    if (config.getApiKey) return config.getApiKey(provider);
+    if (apiKey) return apiKey;
+    return undefined;
+  };
+
+  // Create Agent
+  const agent = new Agent({
+    initialState: {
+      systemPrompt,
+      model,
+      thinkingLevel: config.thinkingLevel ?? (THINKING_MODELS.has(modelId) ? "medium" : "off"),
+      tools: adaptedTools,
+      messages: piMessages as any,
+    },
+    getApiKey: resolveApiKey,
+    toolExecution: config.toolExecution ?? "parallel",
+  });
+
+  // Stream events
+  try {
+    await agent.prompt(piMessages as any);
+
+    yield* agentToStreamEvents(agent, extractCitations);
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    yield { type: "error", message: `Agent error: ${msg}` };
+  }
+}
+
+// ── Non-streaming agent call ──────────────────────────────────────────
+
+export interface AgentResponse {
+  message: string;
+  citations: Citation[];
+  usage?: UsageInfo;
+}
+
+export async function callOrigen(
+  messages: Array<{ role: "user" | "assistant"; content: string }>,
+  context: Record<string, unknown> | undefined,
+  config: AgentConfig,
+  apiKey?: string,
+): Promise<AgentResponse> {
+  let message = "";
+  const citations: Citation[] = [];
+  let usage: UsageInfo | undefined;
+
+  for await (const event of streamOrigen(messages, context, config, apiKey)) {
+    switch (event.type) {
+      case "text": message += event.content; break;
+      case "done": citations.push(...event.citations); usage = event.usage; break;
+      case "error": throw new Error(event.message);
+    }
+  }
+
+  return { message, citations, usage };
+}

package/src/index.ts

@@ -0,0 +1,58 @@
+/**
+ * @moikapy/origen — Multi-Provider Agent Engine
+ *
+ * Generic agent harness with Soul.md personas, streaming, tool calling.
+ * Supports OpenRouter, Ollama, Anthropic, Google, and any OpenAI-compatible API.
+ *
+ * Domain-specific tools live in their own packages (e.g., @moikapy/scholar-tools).
+ *
+ * Usage:
+ *   import { streamOrigen } from "@moikapy/origen";
+ *   import { allBibleTools, buildScholarPrompt } from "@moikapy/scholar-tools";
+ *
+ *   const config = {
+ *     systemPrompt: buildScholarPrompt(),
+ *     tools: allBibleTools(),
+ *     getD1: async () => myD1,
+ *     model: "openrouter/free",
+ *     getApiKey: async (provider) => resolveKey(provider),
+ *   };
+ */
+
+export type {
+  D1Like,
+  D1Provider,
+  ReadingContext,
+  Citation,
+  UsageInfo,
+  ModelConfig as OrigenModelConfig,
+} from "./types";
+
+export {
+  MODELS,
+  DEFAULT_MODEL_ID,
+  DEFAULT_MODEL,
+  THINKING_MODELS,
+  supportsThinking,
+  isOllamaModel,
+  getModelsByProvider,
+  getModelsForUI,
+  type ModelId,
+  type ModelConfig,
+  type UIModelConfig,
+} from "./models";
+
+export {
+  streamOrigen,
+  callOrigen,
+  checkAuth,
+  checkOpenRouterAuth,
+  type AgentConfig,
+  type OrigenTool,
+  type AuthCheckResult,
+  type AgentResponse,
+  type StreamEvent,
+} from "./agent";
+
+export { resolveModel } from "./adapter";
+export type { ModelResolutionOptions } from "./adapter";