AskAI.ts ======= AskAI.ts is a TypeScript library providing a unified interface for interacting with various AI language models from providers like OpenAI, Anthropic, Google, and others. It enables stateful chat interactions, allowing users to send messages and receive responses from AI models seamlessly. The library abstracts the complexities of different AI APIs, enabling easy switching between models or providers without code changes. It supports features like streaming responses, temperature control, and system prompts where applicable. Usage ----- ```typescript import { AskAI } from './AskAI'; async function main() { const ai = await AskAI("openai:gpt-6-astra:medium"); // Options const opts = { system: "You are a helpful assistant.", temperature: 0.0, stream: true, }; // Send a message const response1 = await ai.ask("Hello, how are you?", opts); console.log(response1); // Send another message const response2 = await ai.ask("What did I just say?", opts); console.log(response2); // Get conversation history const history = await ai.ask(null, opts); console.log(history); } ``` In this example, we create a chat instance for GPT-6 Astra, send two messages, and then retrieve the conversation history. Models ------ Models are now referenced using the canonical `vendor:official_model_name:thinking_budget` format, for example: - `openai:gpt-6-astra:high` - `anthropic:claude-sonnet-4-5-20250929:medium` - `google:gemini-2.5-pro:medium` - `openrouter:meta-llama/llama-3.3-70b-instruct:auto` - `xai:grok-4-0709:auto` The optional third segment controls the thinking budget (`none | low | medium | high | xhigh | max | auto`). Legacy shortcodes remain available via the `MODELS` export for convenience. Each shortcut follows a consistent pattern: - Each character (`g`, `G`, `c`, `C`, `l`, `L`, etc.) maps directly to a specific vendor/model pairing (e.g., `s` is Claude Sonnet, `o` is Claude Opus, `g` and `G` both map to GPT‑6 Astra, `p` is GPT‑6 Astra in pro mode). - Append `-` to request the low thinking budget, omit it for medium, and append `+` for high (e.g., `g-`, `g`, `g+`, `g++` map to `openai:gpt-6-astra:low|medium|xhigh|max`). API Reference ------------- ### AskAI Creates and returns a chat instance for the specified model. **Signature:** `async function AskAI(modelShortcode: string): Promise` **Parameters:** - `modelShortcode: string` - Model shortcode (e.g., "g") or full model name. **Returns:** A promise resolving to a `ChatInstance`. ### ChatInstance Interface for chat interactions. #### ask **Signature:** `ask(userMessage: string | null, options: AskOptions): Promise` **Parameters:** - `userMessage: string | null` - Message to send. If `null`, returns conversation history. - `options: AskOptions` - Configuration options. **Returns:** - If `userMessage` is a string: AI's response as a string. - If `userMessage` is `null`: Object containing conversation history. **Note:** When `stream` is `true`, the response is streamed to `stdout`, and the full response is still returned as a string. **Inline files:** `///./path/to/file.pdf///` in a user message (of `ask` or `askTools`) sends that pdf or image (png, jpg, gif, webp) to the model at that spot. Paths are relative to the working dir; a missing file throws. #### askTools **Signature:** `askTools(userMessage: string, options: AskToolsOptions): Promise` **Parameters:** - `userMessage: string` - Message to send. - `options: AskToolsOptions` - Same as `AskOptions`, plus a required `tools` list. **Returns:** `AskResult` containing plain text and normalized structured tool calls. ### AskOptions Options for the `ask` method: - `system?: string` - System prompt to set assistant behavior. - `temperature?: number` - Controls response randomness. Omitted by default. - `max_tokens?: number` - Maximum tokens to generate (chat-completions style APIs). - `max_completion_tokens?: number` - Maximum output tokens (Responses API). - `stream?: boolean` - Enable streaming. Default: `true` where supported. - `cacheable?: boolean` - Anthropic prompt caching (default: enabled). Set `false` to disable. - `cache_ttl?: '5m' | '1h'` - Anthropic cache entry lifetime (default `'1h'`). - `cache_cuts?: number[]` - Char offsets into the outgoing user message where stable content ends; Anthropic pins a cache breakpoint exactly there (used by holefill2's file/prompt seam). Other vendors ignore it. - `vendorConfig?: VendorConfig` - Optional per-call overrides for vendor-specific knobs computed in `AskAI.ts` (e.g., reasoning effort, thinking budgets). **Note:** Not all options apply to every model; unsupported options are ignored. ### AskToolsOptions Extends `AskOptions` with: - `tools: ToolDef[]` - Tool definitions to expose to the model. ### ToolDef Tool definition shared across vendors: - `name: string` - Tool name. - `description?: string` - Natural language description. - `inputSchema?: Record` - JSON schema for tool arguments. ### ToolCall Normalized tool call returned by `askTools`: - `id?: string` - Provider call id when available. - `name: string` - Tool name. - `input: Record` - Parsed tool arguments. ### AskResult Structured `askTools` result: - `text: string` - Assistant plain text output. - `toolCalls: ToolCall[]` - Structured calls normalized across vendors. ### MODELS Record mapping shortcodes to model names. See [Models](#models) for details. ### tokenCount Estimates token count using GPT-4o's tokenizer. **Signature:** `function tokenCount(text: string): number` **Parameters:** - `text: string` - Text to analyze. **Returns:** Estimated token count. **Note:** This is an approximation; actual counts may vary by model. Setup ----- Ensure API keys are set in `~/.config/.token` (e.g., `~/.config/openai.token`). Supported vendors are `openai`, `anthropic`, `google`, `openrouter`, and `xai`. For OpenRouter, the library sets the `HTTP-Referer` header to `"https://github.com/OpenRouterTeam/openrouter-examples"`. Additional Notes ---------------- - **Streaming:** When enabled, responses are streamed to `stdout`. When vendors expose explicit thinking traces (OpenAI Responses, Anthropic, Gemini), they are printed in dim gray before the final answer. - **Thinking Budgets:** Thinking levels are centrally managed in `AskAI.ts` and forwarded to each vendor in an idiomatic way (e.g., OpenAI reasoning effort, Anthropic `thinking` blocks, Gemini `thinkingConfig`). - **Token Estimation:** `tokenCount` uses GPT-4o's tokenizer, which may differ from other models' tokenization.