Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 2 additions & 79 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -113,69 +113,7 @@ Speakeasy's [persistent edits](https://www.speakeasy.com/docs/sdks/customize/cod

## Architecture

### Core Abstractions

**callModel** (`src/funcs/call-model.ts`)
- High-level function for making model requests with tools
- Returns a `ModelResult` wrapper with multiple consumption patterns
- Supports async parameter resolution and automatic tool execution
- Example consumption: `.getText()`, `.getTextStream()`, `.getToolStream()`, etc.

**ModelResult** (`src/lib/model-result.ts`)
- Wraps streaming responses with multiple consumption patterns
- Handles automatic tool execution and turn orchestration
- Uses `ReusableReadableStream` to enable multiple parallel consumers

**Tool System** (`src/lib/tool.ts`, `src/lib/tool-types.ts`, `src/lib/tool-executor.ts`)
- `tool()` helper creates type-safe tools with Zod schemas
- Three tool types:
- **Regular tools** (`execute: function`) - auto-executed, return final result
- **Generator tools** (`execute: async generator`) - stream preliminary results
- **Manual tools** (`execute: false`) - return tool calls without execution
- Tool orchestrator (`src/lib/tool-orchestrator.ts`) manages multi-turn conversations

**Async Parameter Resolution** (`src/lib/async-params.ts`)
- Any parameter in `CallModelInput` can be a function: `(ctx: TurnContext) => value`
- Functions resolved before each turn, allowing dynamic parameter adjustment
- Supports both sync and async functions
- Example: `model: (ctx) => ctx.numberOfTurns > 3 ? 'gpt-4' : 'gpt-3.5-turbo'`

**Next Turn Params** (`src/lib/next-turn-params.ts`)
- Tools can define `nextTurnParams` to modify request parameters after execution
- Functions receive tool input and can return parameter updates
- Applied after tool execution, before next API request
- Example: Increase temperature after seeing tool results

**Stop Conditions** (`src/lib/stop-conditions.ts`)
- Control when tool execution loops terminate
- Built-in helpers: `stepCountIs()`, `hasToolCall()`, `maxTokensUsed()`, `maxCost()`, `finishReasonIs()`
- Custom conditions receive full step history
- Default: `stepCountIs(5)` if not specified

## Message Format Compatibility

The SDK supports multiple message formats:

- **OpenRouter format** (native)
- **Claude format** via `fromClaudeMessages()` / `toClaudeMessage()` (`src/lib/anthropic-compat.ts`)
- **OpenAI Chat format** via `fromChatMessages()` / `toChatMessage()` (`src/lib/chat-compat.ts`)

These converters handle content types, tool calls, and format-specific features.

## Streaming Architecture

**ReusableReadableStream** (`src/lib/reusable-stream.ts`)

- Caches stream events to enable multiple independent consumers
- Critical for allowing parallel consumption patterns (text + tools + reasoning)
- Handles both SSE and standard ReadableStream

**Stream Transformers** (`src/lib/stream-transformers.ts`)

- Extract specific data from response streams
- `extractTextDeltas()`, `extractReasoningDeltas()`, `extractToolDeltas()`
- Build higher-level streams for different consumption patterns
- Handle both streaming and non-streaming responses uniformly
`callModel`, tools, stop conditions and the message-format converters moved to `@openrouter/agent` and are not part of this package.

## Development Workflow

Expand All @@ -194,19 +132,7 @@ These converters handle content types, tool calls, and format-specific features.

### Running Examples

```bash
cd examples
# Set your API key in .env first
node --loader ts-node/esm call-model.example.ts
```

Examples demonstrate:
- `call-model.example.ts` - Basic usage
- `call-model-typed-tool-calling.example.ts` - Type-safe tools
- `anthropic-multimodal-tools.example.ts` - Multimodal inputs with tools
- `anthropic-reasoning.example.ts` - Extended thinking/reasoning
- `chat-reasoning.example.ts` - Reasoning with chat format
- `tools-example.ts` - Comprehensive tool usage
See `examples/README.md`.

## TypeScript Configuration

Expand All @@ -229,10 +155,7 @@ Tests use Vitest with:

E2E tests (`tests/e2e/`) make real API calls and test:
- Basic chat completions
- Tool execution flows
- Streaming responses
- Multi-turn conversations
- Different message formats

## Package Structure

Expand Down
Loading
Loading