@stacksjs/ai 0.70.161 → 0.70.163

package/README.md

@@ -35,6 +35,36 @@ const client = useAI()
 // client...
 ```
 
+## Compact project context
+
+Stacks conventions reduce the amount of application-owned code a coding model
+must generate. A model can describe domain shape once, use known Model-View-Action
+locations, and rely on framework traits and generators for migrations, validation,
+routes, API artifacts, and types where those paths are supported. Installed
+dependencies still exist, but their `node_modules` implementation is package-manager
+state, not application context an LLM should ingest or reproduce.
+
+Generate a deterministic context payload for any coding model or agent:
+
+```bash
+buddy ai:context
+buddy ai:context --json
+buddy ai:context --json --output .stacks/ai-context.json
+buddy ai:context --max-chars 4000 --model claude-sonnet-4
+```
+
+The versioned JSON contract identifies canonical source roles, instruction files,
+available application surfaces, safe package metadata, and representative source
+paths. It excludes dependency, build, cache, lock, environment, credential, key,
+and secret paths by default. Existing Buddy AI calls consume the same compact text
+representation.
+
+Output metrics include the enforced character budget and a heuristic token estimate.
+They also compare the payload with the previous unstructured context shape. This is
+evidence about prompt size only. It is not evidence that a particular model will
+write correct code, and exact billing tokens require the selected provider's
+tokenizer.
+
 Learn more in the docs.
 
 ## 🧪 Testing

package/dist/buddy.js

@@ -1,8 +1,9 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { claudeAgent } from "./agents";
 import { createAnthropicDriver, createClaudeAgentSDKDriver, createOllamaDriver, createOpenAIDriver } from "./drivers";
+import { buildProjectContext } from "./context";
 export const CONFIG = {
   workDir: join(homedir(), "Code", ".buddy-repos"),
   commitMessage: "chore: wip",
@@ -168,26 +169,7 @@ export function getAvailableDrivers() {
   return ["claude-cli-local", "claude-cli-ec2", "claude", "claude-sdk", "openai", "ollama", "mock"];
 }
 export async function getRepoContext(repoPath) {
-  const { $: _$ } = await import("bun"), files = (await _$`cd ${repoPath} && find . -type f -not -path "*/node_modules/*" -not -path "*/.git/*" -not -name "*.lock" | head -50`.quiet()).text().trim();
-  let readme = "";
-  const readmePath = join(repoPath, "README.md");
-  if (existsSync(readmePath))
-    readme = readFileSync(readmePath, "utf-8").slice(0, 2000);
-  let packageJson = "";
-  const packagePath = join(repoPath, "package.json");
-  if (existsSync(packagePath))
-    packageJson = readFileSync(packagePath, "utf-8");
-  return `
-Repository Structure:
-${files}
-
-${readme ? `README.md (excerpt):
-${readme}
-` : ""}
-${packageJson ? `package.json:
-${packageJson}
-` : ""}
-`.trim();
+  return buildProjectContext(repoPath).text;
 }
 export async function openRepository(input) {
   const { $: _$ } = await import("bun");

package/dist/client.d.ts

@@ -0,0 +1,9 @@
+import type { AIProvider, ConfiguredAIClient, ConfiguredAIOptions } from './types';
+declare function parseObject(content: string): unknown;
+declare function validateSchema(value: unknown, schema: Record<string, any>, path?: string): string[];
+/**
+ * Create a provider-neutral AI client from an application's `config/ai.ts`.
+ * Secrets remain server-side and may be supplied by config or provider env vars.
+ */
+export declare function createAIClient(config: ConfiguredAIOptions, override?: AIProvider): ConfiguredAIClient;
+export { parseObject as parseAIObject, validateSchema as validateAISchema };

package/dist/client.js

@@ -0,0 +1,172 @@
+import * as anthropic from "./drivers/anthropic";
+import * as ollama from "./drivers/ollama";
+import * as openai from "./drivers/openai";
+function textContent(content) {
+  if (typeof content === "string")
+    return content;
+  return content.filter((block) => block.type === "text").map((block) => block.text ?? "").join(`
+`);
+}
+function providerFromConfig(config, override) {
+  if (override)
+    return override;
+  const configured = String(config.default || "").toLowerCase();
+  if (configured === "anthropic" || configured.startsWith("anthropic."))
+    return "anthropic";
+  if (configured === "openai" || configured.startsWith("gpt-") || configured.startsWith("o1") || configured.startsWith("o3"))
+    return "openai";
+  if (configured === "ollama")
+    return "ollama";
+  throw Error(`Unsupported configured AI driver: ${config.default || "(empty)"}. Expected anthropic, openai, or ollama.`);
+}
+function parseObject(content) {
+  const unfenced = content.trim().replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "");
+  try {
+    return JSON.parse(unfenced);
+  } catch {
+    const start = unfenced.indexOf("{"), end = unfenced.lastIndexOf("}");
+    if (start >= 0 && end > start)
+      return JSON.parse(unfenced.slice(start, end + 1));
+    throw Error("AI response did not contain a valid JSON object");
+  }
+}
+function typeMatches(value, type) {
+  if (type === "array")
+    return Array.isArray(value);
+  if (type === "integer")
+    return typeof value === "number" && Number.isInteger(value);
+  if (type === "object")
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+  if (type === "null")
+    return value === null;
+  return typeof value === type;
+}
+function validateSchema(value, schema, path = "$") {
+  const errors = [];
+  if (schema.type) {
+    const allowed = Array.isArray(schema.type) ? schema.type : [schema.type];
+    if (!allowed.some((type) => typeMatches(value, type)))
+      return [`${path} must be ${allowed.join(" or ")}`];
+  }
+  if (schema.enum && !schema.enum.some((candidate) => Object.is(candidate, value)))
+    errors.push(`${path} must be one of ${schema.enum.join(", ")}`);
+  if (typeof value === "string") {
+    if (schema.minLength !== void 0 && value.length < schema.minLength)
+      errors.push(`${path} must contain at least ${schema.minLength} characters`);
+    if (schema.maxLength !== void 0 && value.length > schema.maxLength)
+      errors.push(`${path} must contain at most ${schema.maxLength} characters`);
+  }
+  if (typeof value === "number") {
+    if (schema.minimum !== void 0 && value < schema.minimum)
+      errors.push(`${path} must be at least ${schema.minimum}`);
+    if (schema.maximum !== void 0 && value > schema.maximum)
+      errors.push(`${path} must be at most ${schema.maximum}`);
+  }
+  if (Array.isArray(value)) {
+    if (schema.minItems !== void 0 && value.length < schema.minItems)
+      errors.push(`${path} must contain at least ${schema.minItems} items`);
+    if (schema.maxItems !== void 0 && value.length > schema.maxItems)
+      errors.push(`${path} must contain at most ${schema.maxItems} items`);
+    if (schema.items)
+      value.forEach((item, index) => errors.push(...validateSchema(item, schema.items, `${path}[${index}]`)));
+  }
+  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+    const record = value;
+    for (const key of schema.required ?? [])
+      if (!(key in record))
+        errors.push(`${path}.${key} is required`);
+    for (const [key, child] of Object.entries(schema.properties ?? {}))
+      if (key in record)
+        errors.push(...validateSchema(record[key], child, `${path}.${key}`));
+    if (schema.additionalProperties === !1) {
+      const known = new Set(Object.keys(schema.properties ?? {}));
+      for (const key of Object.keys(record))
+        if (!known.has(key))
+          errors.push(`${path}.${key} is not allowed`);
+    }
+  }
+  return errors;
+}
+function createGenerate(config, provider) {
+  if (provider === "anthropic") {
+    const driver = config.drivers?.anthropic ?? {};
+    anthropic.configure({
+      apiKey: driver.apiKey || process.env.ANTHROPIC_API_KEY || "",
+      model: driver.model,
+      maxTokens: driver.maxTokens,
+      anthropicVersion: driver.anthropicVersion
+    });
+    return async (messages, options = {}) => {
+      const systemMessages = messages.filter((message) => message.role === "system").map((message) => textContent(message.content)), nonSystem = messages.filter((message) => message.role !== "system");
+      return anthropic.chat(nonSystem, {
+        ...options,
+        system: [options.system, ...systemMessages].filter(Boolean).join(`
+
+`) || void 0
+      });
+    };
+  }
+  if (provider === "openai") {
+    const driver = config.drivers?.openai ?? {};
+    openai.configure({
+      apiKey: driver.apiKey || process.env.OPENAI_API_KEY || "",
+      model: driver.model,
+      maxTokens: driver.maxTokens,
+      baseUrl: driver.baseUrl,
+      embeddingModel: driver.embeddingModel
+    });
+    return (messages, options = {}) => {
+      const finalMessages = options.system ? [{ role: "system", content: options.system }, ...messages] : messages;
+      return openai.chat(finalMessages, options);
+    };
+  }
+  const driver = config.drivers?.ollama ?? {};
+  ollama.configure({
+    host: driver.host || driver.baseUrl,
+    model: driver.model,
+    embeddingModel: driver.embeddingModel
+  });
+  return (messages, options = {}) => {
+    const finalMessages = options.system ? [{ role: "system", content: options.system }, ...messages] : messages;
+    return ollama.chat(finalMessages, options);
+  };
+}
+export function createAIClient(config, override) {
+  const provider = providerFromConfig(config, override), generate = createGenerate(config, provider);
+  return {
+    provider,
+    generate,
+    async generateObject(messages, schema, options = {}) {
+      const { attempts = 2, system, ...completionOptions } = options, history = [...messages];
+      let lastError;
+      for (let attempt = 1;attempt <= Math.max(1, attempts); attempt++) {
+        const result = await generate(history, {
+          ...completionOptions,
+          system,
+          responseFormat: {
+            type: "json_schema",
+            json_schema: { name: "structured_output", schema, strict: !0 }
+          }
+        });
+        try {
+          const data = parseObject(result.content), errors = validateSchema(data, schema);
+          if (errors.length)
+            throw Error(`AI response failed schema validation: ${errors.slice(0, 8).join("; ")}`);
+          return { data, result };
+        } catch (error) {
+          lastError = error instanceof Error ? error : Error(String(error));
+          if (attempt < attempts) {
+            history.push({ role: "assistant", content: result.content });
+            history.push({
+              role: "user",
+              content: `Return only a corrected JSON object. Validation error: ${lastError.message}`
+            });
+          }
+        }
+      }
+      throw lastError ?? Error("AI object generation failed");
+    }
+  };
+}
+
+export { parseObject as parseAIObject, validateSchema as validateAISchema };

package/dist/context.d.ts

@@ -0,0 +1,53 @@
+declare function representativeFiles(files: string[], maxFiles: number): string[];
+export declare function buildProjectContext(repoPath: string, options?: ProjectContextOptions): ProjectContextResult;
+export declare const STACKS_PROJECT_CONTEXT_SCHEMA: 'https://stacksjs.org/schemas/ai-project-context/v1';
+export declare interface ProjectContextOptions {
+  maxChars?: number
+  maxFiles?: number
+  model?: string
+}
+export declare interface ProjectContextSurface {
+  id: string
+  purpose: string
+  paths: string[]
+}
+export declare interface StacksProjectContext {
+  schema: typeof STACKS_PROJECT_CONTEXT_SCHEMA
+  schemaVersion: '1.0.0'
+  framework: 'stacks'
+  architecture: {
+    pattern: 'Model-View-Action'
+    overrideRule: string
+    authoringOrder: string[]
+    principles: string[]
+  }
+  project: {
+    name: string | null
+    version: string | null
+    scripts: string[]
+    dependencies: string[]
+  }
+  instructionFiles: string[]
+  surfaces: ProjectContextSurface[]
+  representativeFiles: string[]
+  exclusions: string[]
+}
+export declare interface ProjectContextMetrics {
+  candidateFiles: number
+  includedFiles: number
+  maxCharacters: number
+  outputCharacters: number
+  estimatedTokens: number
+  model: string
+  truncated: boolean
+  baselineMethod: 'sorted-first-50-paths+readme-2000+package-json'
+  baselineCharacters: number
+  baselineEstimatedTokens: number
+  estimatedTokenReductionPercent: number | null
+  tokenEstimateIsHeuristic: true
+}
+export declare interface ProjectContextResult {
+  context: StacksProjectContext
+  text: string
+  metrics: ProjectContextMetrics
+}

package/dist/context.js

@@ -0,0 +1,200 @@
+import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
+import { basename, relative, resolve, sep } from "node:path";
+import { estimateTokens } from "./utils/tokens";
+export const STACKS_PROJECT_CONTEXT_SCHEMA = "https://stacksjs.org/schemas/ai-project-context/v1";
+const DEFAULT_MAX_CHARS = 4000, DEFAULT_MAX_FILES = 30, excludedSegments = new Set([
+  ".git",
+  ".bun",
+  ".cache",
+  ".next",
+  ".output",
+  ".turbo",
+  ".vite",
+  "build",
+  "coverage",
+  "dist",
+  "node_modules",
+  "tmp",
+  "vendor"
+]), sensitiveNames = /^(?:\.env(?:\..*)?|\.npmrc|\.pypirc|credentials(?:\..*)?|id_(?:rsa|ed25519)(?:\.pub)?|secrets?(?:\..*)?)$/i, lockNames = /(?:^|\.)(?:bun|package-lock|pnpm-lock|yarn|pantry)\.?(?:lock|yaml)?$/i, surfaceDefinitions = [
+  { id: "models", purpose: "Domain schema, validation, relationships, factories, and traits.", prefixes: ["app/Models/", "storage/framework/defaults/app/Models/"] },
+  { id: "actions", purpose: "Transport-independent application behavior.", prefixes: ["app/Actions/", "storage/framework/defaults/app/Actions/"] },
+  { id: "routes", purpose: "HTTP and API route registration.", prefixes: ["routes/", "app/Routes.ts"] },
+  { id: "jobs", purpose: "Background and inline work.", prefixes: ["app/Jobs/", "storage/framework/defaults/app/Jobs/"] },
+  { id: "configuration", purpose: "Typed application and provider configuration.", prefixes: ["config/"] },
+  { id: "views", purpose: "STX views, layouts, components, and client functions.", prefixes: ["resources/"] },
+  { id: "database", purpose: "Reviewable migrations and seed data.", prefixes: ["database/"] },
+  { id: "tests", purpose: "Unit, feature, contract, and end-to-end evidence.", prefixes: ["tests/", "storage/framework/core/"] }
+];
+function normalizePath(path) {
+  return path.split(sep).join("/");
+}
+function isExcluded(path) {
+  const segments = path.split("/"), name = basename(path);
+  return segments.some((segment) => excludedSegments.has(segment)) || sensitiveNames.test(name) || lockNames.test(name) || name.endsWith(".lock");
+}
+function collectFiles(root) {
+  const files = [];
+  function visit(directory) {
+    const entries = readdirSync(directory, { withFileTypes: !0 }).sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      const fullPath = resolve(directory, entry.name), projectPath = normalizePath(relative(root, fullPath));
+      if (isExcluded(projectPath))
+        continue;
+      if (entry.isDirectory())
+        visit(fullPath);
+      else if (entry.isFile() && !lstatSync(fullPath).isSymbolicLink())
+        files.push(projectPath);
+    }
+  }
+  visit(root);
+  return files.sort((a, b) => a.localeCompare(b));
+}
+function readPackageSummary(root) {
+  const packagePath = resolve(root, "package.json");
+  if (!existsSync(packagePath))
+    return { name: null, version: null, scripts: [], dependencies: [] };
+  try {
+    const manifest = JSON.parse(readFileSync(packagePath, "utf8")), dependencies = [
+      ...Object.keys(manifest.dependencies || {}),
+      ...Object.keys(manifest.devDependencies || {}),
+      ...Object.keys(manifest.peerDependencies || {})
+    ];
+    return {
+      name: typeof manifest.name === "string" ? manifest.name : null,
+      version: typeof manifest.version === "string" ? manifest.version : null,
+      scripts: Object.keys(manifest.scripts || {}).sort().slice(0, 25),
+      dependencies: [...new Set(dependencies)].sort().slice(0, 30)
+    };
+  } catch {
+    return { name: null, version: null, scripts: [], dependencies: [] };
+  }
+}
+function filePriority(path) {
+  if (/^(?:AGENTS|CLAUDE)\.md$|^\.github\/copilot-instructions\.md$/.test(path))
+    return 0;
+  if (path === "package.json" || path === "app/Routes.ts" || path === "app/Commands.ts")
+    return 1;
+  if (/^(?:app|routes|config)\//.test(path))
+    return 2;
+  if (/^(?:resources|database|tests)\//.test(path))
+    return 3;
+  if (/^docs\//.test(path))
+    return 4;
+  if (/^storage\/framework\/defaults\//.test(path))
+    return 5;
+  return 6;
+}
+function representativeFiles(files, maxFiles) {
+  return [...files].sort((a, b) => filePriority(a) - filePriority(b) || a.localeCompare(b)).slice(0, maxFiles).sort((a, b) => a.localeCompare(b));
+}
+function surfacePaths(files, prefixes) {
+  return files.filter((file) => prefixes.some((prefix) => prefix.endsWith("/") ? file.startsWith(prefix) : file === prefix)).slice(0, 4);
+}
+function renderContext(context) {
+  return [
+    "Stacks AI Project Context v1",
+    "",
+    `Project: ${context.project.name || "unnamed"}${context.project.version ? `@${context.project.version}` : ""}`,
+    "Architecture: Model-View-Action",
+    `Override rule: ${context.architecture.overrideRule}`,
+    `Authoring order: ${context.architecture.authoringOrder.join(" -> ")}`,
+    "",
+    "Authoring principles:",
+    ...context.architecture.principles.map((principle) => `- ${principle}`),
+    "",
+    "Instruction files:",
+    ...context.instructionFiles.length ? context.instructionFiles.map((file) => `- ${file}`) : ["- none detected"],
+    "",
+    "Available surfaces:",
+    ...context.surfaces.flatMap((surface) => [
+      `- ${surface.id}: ${surface.purpose}`,
+      ...surface.paths.map((path) => `  - ${path}`)
+    ]),
+    "",
+    `Scripts: ${context.project.scripts.join(", ") || "none detected"}`,
+    `Dependencies: ${context.project.dependencies.join(", ") || "none detected"}`,
+    "",
+    "Representative files:",
+    ...context.representativeFiles.map((file) => `- ${file}`)
+  ].join(`
+`);
+}
+function fitToBudget(text, maxChars) {
+  if (text.length <= maxChars)
+    return { text, truncated: !1 };
+  const marker = `
+[context truncated by character budget]`;
+  if (maxChars <= marker.length)
+    return { text: marker.slice(0, maxChars), truncated: !0 };
+  const available = maxChars - marker.length, prefix = text.slice(0, available), lastLine = prefix.lastIndexOf(`
+`);
+  return {
+    text: `${prefix.slice(0, lastLine > 0 ? lastLine : available)}${marker}`,
+    truncated: !0
+  };
+}
+function unstructuredBaseline(root, files) {
+  const readmePath = resolve(root, "README.md"), packagePath = resolve(root, "package.json"), readme = existsSync(readmePath) ? readFileSync(readmePath, "utf8").slice(0, 2000) : "", packageJson = existsSync(packagePath) ? readFileSync(packagePath, "utf8") : "";
+  return [
+    "Repository Structure:",
+    files.slice(0, 50).join(`
+`),
+    readme ? `README.md (excerpt):
+${readme}` : "",
+    packageJson ? `package.json:
+${packageJson}` : ""
+  ].filter(Boolean).join(`
+
+`);
+}
+export function buildProjectContext(repoPath, options = {}) {
+  const root = resolve(repoPath), maxChars = options.maxChars ?? DEFAULT_MAX_CHARS, maxFiles = options.maxFiles ?? DEFAULT_MAX_FILES, model = options.model || "gpt-4o";
+  if (!Number.isInteger(maxChars) || maxChars < 256)
+    throw Error("maxChars must be an integer of at least 256");
+  if (!Number.isInteger(maxFiles) || maxFiles < 1)
+    throw Error("maxFiles must be a positive integer");
+  const files = collectFiles(root), included = representativeFiles(files, maxFiles), context = {
+    schema: STACKS_PROJECT_CONTEXT_SCHEMA,
+    schemaVersion: "1.0.0",
+    framework: "stacks",
+    architecture: {
+      pattern: "Model-View-Action",
+      overrideRule: "Application files under app/ override matching framework defaults; do not edit defaults for application customization.",
+      authoringOrder: ["model", "migration", "action", "route", "test"],
+      principles: [
+        "Prefer conventional paths and framework generators over bespoke glue code.",
+        "Declare domain shape once and derive validation, migrations, API surfaces, and types where supported.",
+        "Keep Actions transport-independent and make unsupported drivers fail loudly.",
+        "Read repository instruction files before changing source."
+      ]
+    },
+    project: readPackageSummary(root),
+    instructionFiles: files.filter((file) => /(?:^|\/)(?:AGENTS|CLAUDE)\.md$|^\.github\/copilot-instructions\.md$/.test(file)),
+    surfaces: surfaceDefinitions.map((surface) => ({ id: surface.id, purpose: surface.purpose, paths: surfacePaths(files, surface.prefixes) })).filter((surface) => surface.paths.length > 0),
+    representativeFiles: included,
+    exclusions: [
+      "dependency, build, cache, coverage, temporary, and vendor directories",
+      "lockfiles",
+      "environment, credential, private-key, and secret files"
+    ]
+  }, fitted = fitToBudget(renderContext(context), maxChars), baseline = unstructuredBaseline(root, files), outputTokens = estimateTokens(fitted.text, model), baselineTokens = estimateTokens(baseline, model), reduction = baselineTokens > 0 ? Math.round((1 - outputTokens / baselineTokens) * 1000) / 10 : null;
+  return {
+    context,
+    text: fitted.text,
+    metrics: {
+      candidateFiles: files.length,
+      includedFiles: included.length,
+      maxCharacters: maxChars,
+      outputCharacters: fitted.text.length,
+      estimatedTokens: outputTokens,
+      model,
+      truncated: fitted.truncated,
+      baselineMethod: "sorted-first-50-paths+readme-2000+package-json",
+      baselineCharacters: baseline.length,
+      baselineEstimatedTokens: baselineTokens,
+      estimatedTokenReductionPercent: reduction,
+      tokenEstimateIsHeuristic: !0
+    }
+  };
+}

package/dist/drivers/ollama/index.js

@@ -107,14 +107,16 @@ export async function chat(messages, options = {}) {
     model = config.model,
     temperature,
     topP,
-    stop
-  } = options, response = await fetch(`${config.host}/api/chat`, {
+    stop,
+    responseFormat
+  } = options, format = responseFormat?.type === "json_schema" ? responseFormat.json_schema.schema : responseFormat?.type === "json_object" ? "json" : void 0, response = await fetch(`${config.host}/api/chat`, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify({
       model,
       messages,
       stream: !1,
+      format,
       options: {
         temperature,
         top_p: topP,

package/dist/drivers/openai/index.js

@@ -142,21 +142,38 @@ export async function chat(messages, options = {}) {
     maxTokens = DEFAULT_MAX_TOKENS,
     temperature,
     topP,
-    stop
-  } = options, normalizedMessages = normalizeMessagesForProvider(messages, "openai"), startedAt = Date.now(), response = await fetchWithRetry(`${config.baseUrl || DEFAULT_BASE_URL}/chat/completions`, {
+    stop,
+    tools,
+    toolChoice,
+    responseFormat
+  } = options, normalizedMessages = normalizeMessagesForProvider(messages, "openai"), startedAt = Date.now(), body = {
+    model,
+    max_tokens: maxTokens,
+    temperature,
+    top_p: topP,
+    stop,
+    messages: normalizedMessages
+  };
+  if (tools?.length)
+    body.tools = tools.map((tool) => ({
+      type: "function",
+      function: {
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.parameters ?? { type: "object", properties: {} }
+      }
+    }));
+  if (toolChoice !== void 0)
+    body.tool_choice = typeof toolChoice === "object" ? { type: "function", function: { name: toolChoice.name } } : toolChoice;
+  if (responseFormat && responseFormat.type !== "text")
+    body.response_format = responseFormat;
+  const response = await fetchWithRetry(`${config.baseUrl || DEFAULT_BASE_URL}/chat/completions`, {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
       Authorization: `Bearer ${config.apiKey}`
     },
-    body: JSON.stringify({
-      model,
-      max_tokens: maxTokens,
-      temperature,
-      top_p: topP,
-      stop,
-      messages: normalizedMessages
-    })
+    body: JSON.stringify(body)
   });
   if (!response.ok) {
     const error = await response.text();

package/dist/index.d.ts

@@ -5,10 +5,14 @@ export type { SanitizeResult } from './utils/tokens';
 export * from './types';
 // Drivers
 export * from './drivers/index';
+// Provider-neutral, config-driven client
+export * from './client';
 // Agents
 export * from './agents/index';
 // Buddy - Voice AI Code Assistant
 export * from './buddy';
+// Deterministic, budgeted project context for coding models and agents
+export * from './context';
 // Text utilities
 export * from './text';
 // Image generation & vision

package/dist/index.js

@@ -1,7 +1,9 @@
 export * from "./types";
 export * from "./drivers";
+export * from "./client";
 export * from "./agents";
 export * from "./buddy";
+export * from "./context";
 export * from "./text";
 export * from "./image";
 export * from "./search";

package/dist/types.d.ts

@@ -157,7 +157,7 @@ export declare interface MCPConfig {
 }
 // AI module config (used by @stacksjs/config)
 export declare interface AIConfig {
-  default?: string
+  default?: AIProvider | string
   models?: string[]
   drivers?: {
     anthropic?: AIDriverConfig & { anthropicVersion?: string }
@@ -168,6 +168,26 @@ export declare interface AIConfig {
   search?: SearchConfig
   mcp?: MCPConfig
 }
+export declare interface ConfiguredAIOptions extends AIConfig {
+  drivers?: {
+    anthropic?: AIDriverConfig & { anthropicVersion?: string }
+    openai?: AIDriverConfig & { embeddingModel?: string }
+    ollama?: AIDriverConfig & { host?: string, embeddingModel?: string }
+  }
+}
+export declare interface GenerateObjectOptions extends ChatCompletionOptions {
+  attempts?: number
+  system?: string
+}
+export declare interface ConfiguredAIClient {
+  provider: AIProvider
+  generate: (messages: AIMessage[], options?: ChatCompletionOptions & { system?: string }) => Promise<AIResult>
+  generateObject: <T>(
+    messages: AIMessage[],
+    schema: Record<string, unknown>,
+    options?: GenerateObjectOptions,
+  ) => Promise<{ data: T, result: AIResult }>
+}
 /**
  * Structured-output / JSON-mode response format. Modeled after
  * OpenAI's `response_format` but the Anthropic driver maps it to
@@ -183,3 +203,4 @@ export type AIResponseFormat = | { type: 'text' }
         strict?: boolean
       }
     }
+export type AIProvider = 'anthropic' | 'openai' | 'ollama';

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/ai",
   "type": "module",
   "sideEffects": false,
-  "version": "0.70.161",
+  "version": "0.70.163",
   "description": "Stacks Artificial Intelligence.",
   "author": "Chris Breuer",
   "contributors": [
@@ -60,7 +60,7 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/ts-cloud": "^0.7.49"
+    "@stacksjs/ts-cloud": "^0.7.56"
   },
   "peerDependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.79"