AHENA
Documentation menu

Providers

AI providers

Uses the Ahena CLI (beta). Install it with npm install -g @ahena/cli, or prefix commands with npx @ahena/cli. See Installation. The dashboard covers projects, connections, Doctor, the Stack Graph, plans and approvals without it.

Provider pages: OpenAI · Anthropic · Ollama. This page covers how they work together.

One generated interface, any provider per environment:

ai: {
  provider: { development: "ollama", production: "openai" },
  model: { development: "llama3.2", production: "gpt-5-mini" },
},
import { ahena } from "./ahena/client";
const { text } = await ahena.ai.generate({ prompt: "Summarize this listing", system: "Be brief" });
const client = ahena.ai.raw; // the active provider's own SDK client

ahena generate -e <env> writes src/ahena/ai/providers/<id>.ts for that environment's provider. src/ahena/ai/index.ts includes every adapter present, and AI_PROVIDER picks one at runtime (required when there's more than one; AI_MODEL overrides the model). Calls go straight from your app to the provider. Ahena is never in the inference path.

Doctor never spends your money

OpenAI and Anthropic checks use only the free model-list endpoints. Ahena never runs a completion or sends a message on your account. Ollama is local, so its checks include one tiny generation for latency.

OpenAI (@ahena/provider-openai)

  • OPENAI_API_KEY: a project key (sk-proj-…) with Models read is enough. User keys get an INFO note.
  • Doctor: key valid, model available, model shutdown date (WARNING over 30 days, FAIL within 30 or after).
  • Adapter: official openai SDK, Responses API (responses.create, output_text).
  • Contract: GET /models, GET /models/{model} pinned to OpenAI's published OpenAPI spec.

Anthropic (@ahena/provider-anthropic)

  • ANTHROPIC_API_KEY (sk-ant-…). Ahena's own checks use the official @anthropic-ai/sdk (Models API: models.list, models.retrieve) through Ahena's controlled fetch.
  • Doctor: key valid, model available, context window and max output.
  • Adapter: official SDK, default model claude-opus-5-5 (override with ai.model). It enables server-side refusal fallbacks (fallbacks: "default" with the server-side-fallback-2026-07-01 beta): if a safety classifier declines a request, the API retries it on a suitable fallback model in the same call. Remove those two lines in the generated file to opt out. A final stop_reason: "refusal" becomes a clear error.

Ollama (@ahena/provider-ollama): a local provider

Ollama runs on your machine, LAN or Tailscale, which Ahena's cloud API can't and shouldn't reach. So Ollama is locality: "local":

  • ahena connect ollama --set OLLAMA_HOST=http://localhost:11434 verifies it on your machine before saving.
  • ahena doctor runs Ollama's checks locally and stores the results with the run. Ahena's servers never fetch the endpoint.
  • The dashboard's Doctor shows "Ollama is checked on your machine" until you run the CLI.
Check Severity Meaning
ollama.endpoint PASS / FAIL Reachable (version), or how to start it.
ollama.exposure INFO / WARNING / FAIL LAN/Tailscale (INFO); public https (WARNING: needs an auth proxy); public plain http (FAIL: Ollama has no authentication).
ollama.model PASS / FAIL Configured model pulled (ollama pull … otherwise).
ollama.capabilities / ollama.context PASS / FAIL / WARNING Model can generate text; context length (WARNING under 8K).
ollama.latency PASS / WARNING / FAIL One-token generation from Ollama's own timings, excluding model load time.

OLLAMA_API_KEY (optional, for authenticating proxies) is read from your local environment when Doctor runs.