76 lines
3.4 KiB
Markdown
76 lines
3.4 KiB
Markdown
# AGENTS.md
|
|
|
|
Orientation notes for AI coding assistants working in this repo. Read this first.
|
|
|
|
## What this is
|
|
|
|
`llmorbiter` — a small (v0.1.0, 0BSD) **LLM tool-calling orchestrator with provider
|
|
abstraction**. Pure ES modules (`"type": "module"`). Only runtime dependency is `dotenv`.
|
|
No build step, no test runner, no README (this file is the orientation doc).
|
|
|
|
## Layout
|
|
|
|
```
|
|
src/
|
|
index.js # public entry — re-exports everything
|
|
LLMOrbiter.js # core orchestrator (~364 lines)
|
|
Tool.js # defineTool() + ToolError + DirectReturnError
|
|
providers/
|
|
OpenRouterProvider.js # streaming OpenRouter SSE provider
|
|
|
|
examples/
|
|
weather.js # minimal tool-calling demo
|
|
tool-error-retry.js # tool-error + LLM self-correction demo (has PASS/FAIL asserts)
|
|
pdf-pages.js # PDF -> per-page LLM processing (500 lines, largest)
|
|
tools/weather.js # sample static-data weather tool
|
|
```
|
|
|
|
## Public API (`src/index.js`)
|
|
|
|
Exports: `LLMOrbiter`, `OpenRouterProvider`, `defineTool`, `ToolError`, `DirectReturnError`.
|
|
|
|
- `defineTool({ name, description, parameters, strict=true, invoke })` -> `{ spec, invoke, name }`.
|
|
`spec` is the OpenAI-compatible function schema sent to the LLM; `invoke(args, { signal })`
|
|
is the local implementation.
|
|
- `ToolError(message)` — throw from a tool to signal a recoverable error back to the LLM.
|
|
- `DirectReturnError(data)` — throw from a tool to stop the loop immediately; `run()` resolves
|
|
with `{ directReturn: true, data, ... }`.
|
|
|
|
### `new LLMOrbiter(provider, opts)`
|
|
|
|
`opts` are lifecycle callbacks: `onLLMCall`, `onUsage`, `onToolCall`, `onToolError`,
|
|
`onToolResult`, `onStatus`, `onContent`, `onReasoning`.
|
|
|
|
### `orbiter.run(opts)`
|
|
|
|
`{ prompt, messages, model, tools, maxIterations=10, tool_choice, extraBody, signal }`.
|
|
|
|
Loop: send messages + tool specs -> if `tool_calls` come back, invoke locals and feed results
|
|
back -> repeat until no more tool calls or `maxIterations`. Returns
|
|
`{ content, toolResults, usage, rawUsage, iterations, messages, ... }`; the returned `messages`
|
|
can seed the next `run()` for conversation continuity (a leading `{role:'system'}` entry is the
|
|
system prompt). `orbiter.abort(reason)` cancels the active run; aborts surface as
|
|
`DOMException('...', 'AbortError')`.
|
|
|
|
### `OpenRouterProvider`
|
|
|
|
`new OpenRouterProvider({ apiKey, apiUrl, siteUrl, siteName })`. Method:
|
|
`chatCompletions({ model, messages, tools, tool_choice, signal, extraBody, onStatus, onContent, onReasoning })`
|
|
— streams SSE, assembles `{ content, tool_calls, finish_reason, usage, reasoning_details, reasoning }`.
|
|
`apiUrl` defaults to `https://openrouter.ai/api/v1/chat/completions`.
|
|
|
|
## Gotchas / notes
|
|
|
|
- Examples need `OPENROUTER_API_KEY` (in `examples/.env` or via `--key`). Default model in the
|
|
examples: `deepseek/deepseek-v4-flash-0731`.
|
|
- `.gitignore` ignores `node_modules/`, `examples/.env`, `examples/invoice.pdf`.
|
|
- `pdf-pages.js` shells out to `pdftotext -layout`, splits pages on `\f`, and appends prompts
|
|
to `examples/prompts.log`.
|
|
- `OpenRouterProvider._readStream` currently writes reasoning straight to `process.stdout`
|
|
(debug-style side effect) rather than only via `onReasoning` — worth knowing if refactoring.
|
|
|
|
## Style conventions observed
|
|
|
|
- 4-space indent, single quotes, semicolons, `'use strict';` header.
|
|
- Comments use em dashes (`—`) and `───` section dividers in examples.
|