@symerian/symi 3.0.21 → 3.0.22

package/docs/providers/anthropic.md

@@ -1,174 +0,0 @@
----
-summary: "Use Anthropic Claude via API keys or setup-token in Symi"
-read_when:
-  - You want to use Anthropic models in Symi
-  - You want setup-token instead of API keys
-title: "Anthropic"
----
-
-# Anthropic (Claude)
-
-Anthropic builds the **Claude** model family and provides access via an API.
-In Symi you can authenticate with an API key or a **setup-token**.
-
-## Option A: Anthropic API key
-
-**Best for:** standard API access and usage-based billing.
-Create your API key in the Anthropic Console.
-
-### CLI setup
-
-```bash
-symi onboard
-# choose: Anthropic API key
-
-# or non-interactive
-symi onboard --anthropic-api-key "$ANTHROPIC_API_KEY"
-```
-
-### Config snippet
-
-```json5
-{
-  env: { ANTHROPIC_API_KEY: "sk-ant-..." },
-  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
-}
-```
-
-## Prompt caching (Anthropic API)
-
-Symi supports Anthropic's prompt caching feature. This is **API-only**; subscription auth does not honor cache settings.
-
-### Configuration
-
-Use the `cacheRetention` parameter in your model config:
-
-| Value   | Cache Duration | Description                         |
-| ------- | -------------- | ----------------------------------- |
-| `none`  | No caching     | Disable prompt caching              |
-| `short` | 5 minutes      | Default for API Key auth            |
-| `long`  | 1 hour         | Extended cache (requires beta flag) |
-
-```json5
-{
-  agents: {
-    defaults: {
-      models: {
-        "anthropic/claude-opus-4-6": {
-          params: { cacheRetention: "long" },
-        },
-      },
-    },
-  },
-}
-```
-
-### Defaults
-
-When using Anthropic API Key authentication, Symi automatically applies `cacheRetention: "short"` (5-minute cache) for all Anthropic models. You can override this by explicitly setting `cacheRetention` in your config.
-
-### Legacy parameter
-
-The older `cacheControlTtl` parameter is still supported for backwards compatibility:
-
-- `"5m"` maps to `short`
-- `"1h"` maps to `long`
-
-We recommend migrating to the new `cacheRetention` parameter.
-
-Symi includes the `extended-cache-ttl-2025-04-11` beta flag for Anthropic API
-requests; keep it if you override provider headers (see [/gateway/configuration](/gateway/configuration)).
-
-## 1M context window (Anthropic beta)
-
-Anthropic's 1M context window is beta-gated. In Symi, enable it per model
-with `params.context1m: true` for supported Opus/Sonnet models.
-
-```json5
-{
-  agents: {
-    defaults: {
-      models: {
-        "anthropic/claude-opus-4-6": {
-          params: { context1m: true },
-        },
-      },
-    },
-  },
-}
-```
-
-Symi maps this to `anthropic-beta: context-1m-2025-08-07` on Anthropic
-requests.
-
-## Option B: Claude setup-token
-
-**Best for:** using your Claude subscription.
-
-### Where to get a setup-token
-
-Setup-tokens are created by the **Claude Code CLI**, not the Anthropic Console. You can run this on **any machine**:
-
-```bash
-claude setup-token
-```
-
-Paste the token into Symi (wizard: **Anthropic token (paste setup-token)**), or run it on the gateway host:
-
-```bash
-symi models auth setup-token --provider anthropic
-```
-
-If you generated the token on a different machine, paste it:
-
-```bash
-symi models auth paste-token --provider anthropic
-```
-
-### CLI setup (setup-token)
-
-```bash
-# Paste a setup-token during onboarding
-symi onboard --auth-choice setup-token
-```
-
-### Config snippet (setup-token)
-
-```json5
-{
-  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
-}
-```
-
-## Notes
-
-- Generate the setup-token with `claude setup-token` and paste it, or run `symi models auth setup-token` on the gateway host.
-- If you see “OAuth token refresh failed …” on a Claude subscription, re-auth with a setup-token. See [/gateway/troubleshooting#oauth-token-refresh-failed-anthropic-claude-subscription](/gateway/troubleshooting#oauth-token-refresh-failed-anthropic-claude-subscription).
-- Auth details + reuse rules are in [/concepts/oauth](/concepts/oauth).
-
-## Troubleshooting
-
-**401 errors / token suddenly invalid**
-
-- Claude subscription auth can expire or be revoked. Re-run `claude setup-token`
-  and paste it into the **gateway host**.
-- If the Claude CLI login lives on a different machine, use
-  `symi models auth paste-token --provider anthropic` on the gateway host.
-
-**No API key found for provider "anthropic"**
-
-- Auth is **per agent**. New agents don’t inherit the main agent’s keys.
-- Re-run onboarding for that agent, or paste a setup-token / API key on the
-  gateway host, then verify with `symi models status`.
-
-**No credentials found for profile `anthropic:default`**
-
-- Run `symi models status` to see which auth profile is active.
-- Re-run onboarding, or paste a setup-token / API key for that profile.
-
-**No available auth profile (all in cooldown/unavailable)**
-
-- Check `symi models status --json` for `auth.unusableProfiles`.
-- Add another Anthropic profile or wait for cooldown.
-
-More: [/gateway/troubleshooting](/gateway/troubleshooting) and [/help/faq](/help/faq).

package/docs/providers/bedrock.md

@@ -1,176 +0,0 @@
----
-summary: "Use Amazon Bedrock (Converse API) models with Symi"
-read_when:
-  - You want to use Amazon Bedrock models with Symi
-  - You need AWS credential/region setup for model calls
-title: "Amazon Bedrock"
----
-
-# Amazon Bedrock
-
-Symi can use **Amazon Bedrock** models via pi‑ai’s **Bedrock Converse**
-streaming provider. Bedrock auth uses the **AWS SDK default credential chain**,
-not an API key.
-
-## What pi‑ai supports
-
-- Provider: `amazon-bedrock`
-- API: `bedrock-converse-stream`
-- Auth: AWS credentials (env vars, shared config, or instance role)
-- Region: `AWS_REGION` or `AWS_DEFAULT_REGION` (default: `us-east-1`)
-
-## Automatic model discovery
-
-If AWS credentials are detected, Symi can automatically discover Bedrock
-models that support **streaming** and **text output**. Discovery uses
-`bedrock:ListFoundationModels` and is cached (default: 1 hour).
-
-Config options live under `models.bedrockDiscovery`:
-
-```json5
-{
-  models: {
-    bedrockDiscovery: {
-      enabled: true,
-      region: "us-east-1",
-      providerFilter: ["anthropic", "amazon"],
-      refreshInterval: 3600,
-      defaultContextWindow: 32000,
-      defaultMaxTokens: 4096,
-    },
-  },
-}
-```
-
-Notes:
-
-- `enabled` defaults to `true` when AWS credentials are present.
-- `region` defaults to `AWS_REGION` or `AWS_DEFAULT_REGION`, then `us-east-1`.
-- `providerFilter` matches Bedrock provider names (for example `anthropic`).
-- `refreshInterval` is seconds; set to `0` to disable caching.
-- `defaultContextWindow` (default: `32000`) and `defaultMaxTokens` (default: `4096`)
-  are used for discovered models (override if you know your model limits).
-
-## Onboarding
-
-1. Ensure AWS credentials are available on the **gateway host**:
-
-```bash
-export AWS_ACCESS_KEY_ID="AKIA..."
-export AWS_SECRET_ACCESS_KEY="..."
-export AWS_REGION="us-east-1"
-# Optional:
-export AWS_SESSION_TOKEN="..."
-export AWS_PROFILE="your-profile"
-# Optional (Bedrock API key/bearer token):
-export AWS_BEARER_TOKEN_BEDROCK="..."
-```
-
-2. Add a Bedrock provider and model to your config (no `apiKey` required):
-
-```json5
-{
-  models: {
-    providers: {
-      "amazon-bedrock": {
-        baseUrl: "https://bedrock-runtime.us-east-1.amazonaws.com",
-        api: "bedrock-converse-stream",
-        auth: "aws-sdk",
-        models: [
-          {
-            id: "us.anthropic.claude-opus-4-6-v1:0",
-            name: "Claude Opus 4.6 (Bedrock)",
-            reasoning: true,
-            input: ["text", "image"],
-            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-            contextWindow: 200000,
-            maxTokens: 8192,
-          },
-        ],
-      },
-    },
-  },
-  agents: {
-    defaults: {
-      model: { primary: "amazon-bedrock/us.anthropic.claude-opus-4-6-v1:0" },
-    },
-  },
-}
-```
-
-## EC2 Instance Roles
-
-When running Symi on an EC2 instance with an IAM role attached, the AWS SDK
-will automatically use the instance metadata service (IMDS) for authentication.
-However, Symi's credential detection currently only checks for environment
-variables, not IMDS credentials.
-
-**Workaround:** Set `AWS_PROFILE=default` to signal that AWS credentials are
-available. The actual authentication still uses the instance role via IMDS.
-
-```bash
-# Add to ~/.bashrc or your shell profile
-export AWS_PROFILE=default
-export AWS_REGION=us-east-1
-```
-
-**Required IAM permissions** for the EC2 instance role:
-
-- `bedrock:InvokeModel`
-- `bedrock:InvokeModelWithResponseStream`
-- `bedrock:ListFoundationModels` (for automatic discovery)
-
-Or attach the managed policy `AmazonBedrockFullAccess`.
-
-## Quick setup (AWS path)
-
-```bash
-# 1. Create IAM role and instance profile
-aws iam create-role --role-name EC2-Bedrock-Access \
-  --assume-role-policy-document '{
-    "Version": "2012-10-17",
-    "Statement": [{
-      "Effect": "Allow",
-      "Principal": {"Service": "ec2.amazonaws.com"},
-      "Action": "sts:AssumeRole"
-    }]
-  }'
-
-aws iam attach-role-policy --role-name EC2-Bedrock-Access \
-  --policy-arn arn:aws:iam::aws:policy/AmazonBedrockFullAccess
-
-aws iam create-instance-profile --instance-profile-name EC2-Bedrock-Access
-aws iam add-role-to-instance-profile \
-  --instance-profile-name EC2-Bedrock-Access \
-  --role-name EC2-Bedrock-Access
-
-# 2. Attach to your EC2 instance
-aws ec2 associate-iam-instance-profile \
-  --instance-id i-xxxxx \
-  --iam-instance-profile Name=EC2-Bedrock-Access
-
-# 3. On the EC2 instance, enable discovery
-symi config set models.bedrockDiscovery.enabled true
-symi config set models.bedrockDiscovery.region us-east-1
-
-# 4. Set the workaround env vars
-echo 'export AWS_PROFILE=default' >> ~/.bashrc
-echo 'export AWS_REGION=us-east-1' >> ~/.bashrc
-source ~/.bashrc
-
-# 5. Verify models are discovered
-symi models list
-```
-
-## Notes
-
-- Bedrock requires **model access** enabled in your AWS account/region.
-- Automatic discovery needs the `bedrock:ListFoundationModels` permission.
-- If you use profiles, set `AWS_PROFILE` on the gateway host.
-- Symi surfaces the credential source in this order: `AWS_BEARER_TOKEN_BEDROCK`,
-  then `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`, then `AWS_PROFILE`, then the
-  default AWS SDK chain.
-- Reasoning support depends on the model; check the Bedrock model card for
-  current capabilities.
-- If you prefer a managed key flow, you can also place an OpenAI‑compatible
-  proxy in front of Bedrock and configure it as an OpenAI provider instead.

package/docs/providers/claude-max-api-proxy.md

@@ -1,148 +0,0 @@
----
-summary: "Use Claude Max/Pro subscription as an OpenAI-compatible API endpoint"
-read_when:
-  - You want to use Claude Max subscription with OpenAI-compatible tools
-  - You want a local API server that wraps Claude Code CLI
-  - You want to save money by using subscription instead of API keys
-title: "Claude Max API Proxy"
----
-
-# Claude Max API Proxy
-
-**claude-max-api-proxy** is a community tool that exposes your Claude Max/Pro subscription as an OpenAI-compatible API endpoint. This allows you to use your subscription with any tool that supports the OpenAI API format.
-
-## Why Use This?
-
-| Approach                | Cost                                                | Best For                                   |
-| ----------------------- | --------------------------------------------------- | ------------------------------------------ |
-| Anthropic API           | Pay per token (~$15/M input, $75/M output for Opus) | Production apps, high volume               |
-| Claude Max subscription | $200/month flat                                     | Personal use, development, unlimited usage |
-
-If you have a Claude Max subscription and want to use it with OpenAI-compatible tools, this proxy can save you significant money.
-
-## How It Works
-
-```
-Your App → claude-max-api-proxy → Claude Code CLI → Anthropic (via subscription)
-     (OpenAI format)              (converts format)      (uses your login)
-```
-
-The proxy:
-
-1. Accepts OpenAI-format requests at `http://localhost:3456/v1/chat/completions`
-2. Converts them to Claude Code CLI commands
-3. Returns responses in OpenAI format (streaming supported)
-
-## Installation
-
-```bash
-# Requires Node.js 20+ and Claude Code CLI
-npm install -g claude-max-api-proxy
-
-# Verify Claude CLI is authenticated
-claude --version
-```
-
-## Usage
-
-### Start the server
-
-```bash
-claude-max-api
-# Server runs at http://localhost:3456
-```
-
-### Test it
-
-```bash
-# Health check
-curl http://localhost:3456/health
-
-# List models
-curl http://localhost:3456/v1/models
-
-# Chat completion
-curl http://localhost:3456/v1/chat/completions \
-  -H "Content-Type: application/json" \
-  -d '{
-    "model": "claude-opus-4",
-    "messages": [{"role": "user", "content": "Hello!"}]
-  }'
-```
-
-### With Symi
-
-You can point Symi at the proxy as a custom OpenAI-compatible endpoint:
-
-```json5
-{
-  env: {
-    OPENAI_API_KEY: "not-needed",
-    OPENAI_BASE_URL: "http://localhost:3456/v1",
-  },
-  agents: {
-    defaults: {
-      model: { primary: "openai/claude-opus-4" },
-    },
-  },
-}
-```
-
-## Available Models
-
-| Model ID          | Maps To         |
-| ----------------- | --------------- |
-| `claude-opus-4`   | Claude Opus 4   |
-| `claude-sonnet-4` | Claude Sonnet 4 |
-| `claude-haiku-4`  | Claude Haiku 4  |
-
-## Auto-Start on macOS
-
-Create a LaunchAgent to run the proxy automatically:
-
-```bash
-cat > ~/Library/LaunchAgents/com.claude-max-api.plist << 'EOF'
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-  <key>Label</key>
-  <string>com.claude-max-api</string>
-  <key>RunAtLoad</key>
-  <true/>
-  <key>KeepAlive</key>
-  <true/>
-  <key>ProgramArguments</key>
-  <array>
-    <string>/usr/local/bin/node</string>
-    <string>/usr/local/lib/node_modules/claude-max-api-proxy/dist/server/standalone.js</string>
-  </array>
-  <key>EnvironmentVariables</key>
-  <dict>
-    <key>PATH</key>
-    <string>/usr/local/bin:/opt/homebrew/bin:~/.local/bin:/usr/bin:/bin</string>
-  </dict>
-</dict>
-</plist>
-EOF
-
-launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.claude-max-api.plist
-```
-
-## Links
-
-- **npm:** [https://www.npmjs.com/package/claude-max-api-proxy](https://www.npmjs.com/package/claude-max-api-proxy)
-- **GitHub:** [https://github.com/atalovesyou/claude-max-api-proxy](https://github.com/atalovesyou/claude-max-api-proxy)
-- **Issues:** [https://github.com/atalovesyou/claude-max-api-proxy/issues](https://github.com/atalovesyou/claude-max-api-proxy/issues)
-
-## Notes
-
-- This is a **community tool**, not officially supported by Anthropic or Symi
-- Requires an active Claude Max/Pro subscription with Claude Code CLI authenticated
-- The proxy runs locally and does not send data to any third-party servers
-- Streaming responses are fully supported
-
-## See Also
-
-- [Anthropic provider](/providers/anthropic) - Native Symi integration with Claude setup-token or API keys
-- [OpenAI provider](/providers/openai) - For OpenAI/Codex subscriptions

package/docs/providers/cloudflare-ai-gateway.md

@@ -1,71 +0,0 @@
----
-title: "Cloudflare AI Gateway"
-summary: "Cloudflare AI Gateway setup (auth + model selection)"
-read_when:
-  - You want to use Cloudflare AI Gateway with Symi
-  - You need the account ID, gateway ID, or API key env var
----
-
-# Cloudflare AI Gateway
-
-Cloudflare AI Gateway sits in front of provider APIs and lets you add analytics, caching, and controls. For Anthropic, Symi uses the Anthropic Messages API through your Gateway endpoint.
-
-- Provider: `cloudflare-ai-gateway`
-- Base URL: `https://gateway.ai.cloudflare.com/v1/<account_id>/<gateway_id>/anthropic`
-- Default model: `cloudflare-ai-gateway/claude-sonnet-4-5`
-- API key: `CLOUDFLARE_AI_GATEWAY_API_KEY` (your provider API key for requests through the Gateway)
-
-For Anthropic models, use your Anthropic API key.
-
-## Quick start
-
-1. Set the provider API key and Gateway details:
-
-```bash
-symi onboard --auth-choice cloudflare-ai-gateway-api-key
-```
-
-2. Set a default model:
-
-```json5
-{
-  agents: {
-    defaults: {
-      model: { primary: "cloudflare-ai-gateway/claude-sonnet-4-5" },
-    },
-  },
-}
-```
-
-## Non-interactive example
-
-```bash
-symi onboard --non-interactive \
-  --mode local \
-  --auth-choice cloudflare-ai-gateway-api-key \
-  --cloudflare-ai-gateway-account-id "your-account-id" \
-  --cloudflare-ai-gateway-gateway-id "your-gateway-id" \
-  --cloudflare-ai-gateway-api-key "$CLOUDFLARE_AI_GATEWAY_API_KEY"
-```
-
-## Authenticated gateways
-
-If you enabled Gateway authentication in Cloudflare, add the `cf-aig-authorization` header (this is in addition to your provider API key).
-
-```json5
-{
-  models: {
-    providers: {
-      "cloudflare-ai-gateway": {
-        headers: {
-          "cf-aig-authorization": "Bearer <cloudflare-ai-gateway-token>",
-        },
-      },
-    },
-  },
-}
-```
-
-## Environment note
-
-If the Gateway runs as a daemon (launchd/systemd), make sure `CLOUDFLARE_AI_GATEWAY_API_KEY` is available to that process (for example, in `~/.symi/.env` or via `env.shellEnv`).

package/docs/providers/deepgram.md

@@ -1,93 +0,0 @@
----
-summary: "Deepgram transcription for inbound voice notes"
-read_when:
-  - You want Deepgram speech-to-text for audio attachments
-  - You need a quick Deepgram config example
-title: "Deepgram"
----
-
-# Deepgram (Audio Transcription)
-
-Deepgram is a speech-to-text API. In Symi it is used for **inbound audio/voice note
-transcription** via `tools.media.audio`.
-
-When enabled, Symi uploads the audio file to Deepgram and injects the transcript
-into the reply pipeline (`{{Transcript}}` + `[Audio]` block). This is **not streaming**;
-it uses the pre-recorded transcription endpoint.
-
-Website: [https://deepgram.com](https://deepgram.com)  
-Docs: [https://developers.deepgram.com](https://developers.deepgram.com)
-
-## Quick start
-
-1. Set your API key:
-
-```
-DEEPGRAM_API_KEY=dg_...
-```
-
-2. Enable the provider:
-
-```json5
-{
-  tools: {
-    media: {
-      audio: {
-        enabled: true,
-        models: [{ provider: "deepgram", model: "nova-3" }],
-      },
-    },
-  },
-}
-```
-
-## Options
-
-- `model`: Deepgram model id (default: `nova-3`)
-- `language`: language hint (optional)
-- `tools.media.audio.providerOptions.deepgram.detect_language`: enable language detection (optional)
-- `tools.media.audio.providerOptions.deepgram.punctuate`: enable punctuation (optional)
-- `tools.media.audio.providerOptions.deepgram.smart_format`: enable smart formatting (optional)
-
-Example with language:
-
-```json5
-{
-  tools: {
-    media: {
-      audio: {
-        enabled: true,
-        models: [{ provider: "deepgram", model: "nova-3", language: "en" }],
-      },
-    },
-  },
-}
-```
-
-Example with Deepgram options:
-
-```json5
-{
-  tools: {
-    media: {
-      audio: {
-        enabled: true,
-        providerOptions: {
-          deepgram: {
-            detect_language: true,
-            punctuate: true,
-            smart_format: true,
-          },
-        },
-        models: [{ provider: "deepgram", model: "nova-3" }],
-      },
-    },
-  },
-}
-```
-
-## Notes
-
-- Authentication follows the standard provider auth order; `DEEPGRAM_API_KEY` is the simplest path.
-- Override endpoints or headers with `tools.media.audio.baseUrl` and `tools.media.audio.headers` when using a proxy.
-- Output follows the same audio rules as other providers (size caps, timeouts, transcript injection).