Skip to content
Open
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
11 changes: 11 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,17 @@ All notable changes to Agentling are documented here. The format follows
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project aims
to follow [semantic versioning](https://semver.org/).

## [Unreleased]

### Added

- A copyable native Gemini streaming adapter, recorder integration and an offline
conformance fixture, with tool calling, thought-signature replay and token usage.

### Fixed

- Redact Google's `x-goog-api-key` header when recording HTTP fixtures.

## [0.2.0] - 2026-11-03

**Breaking: Agentling no longer ships a model provider.** Every removed or
Expand Down
9 changes: 7 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -240,10 +240,11 @@ class Model(Protocol):
) -> AsyncIterator[Delta]: ...
```

[`examples/providers/`](examples/providers/) has three adapters to copy:
[`examples/providers/`](examples/providers/) has four adapters to copy:
`openai_chat.py` for OpenAI and compatible servers (LM Studio, vLLM, Ollama's
`/v1`, OpenRouter, Gemini's compatibility endpoint), `anthropic_messages.py`
for Claude, and `ollama_native.py` for Ollama's own API. Point `base_url` at
for Claude, `ollama_native.py` for Ollama's own API, and `gemini_native.py`
for Gemini's native API. Point `base_url` at
your endpoint:

```python
Expand Down Expand Up @@ -274,6 +275,10 @@ the reference adapter closest to your backend:
- [`ollama_native.py`](examples/providers/ollama_native.py): Ollama's
`/api/chat`. Reads newline-delimited JSON, whole tool calls, and usage from
the final chunk.
- [`gemini_native.py`](examples/providers/gemini_native.py): Gemini's native
`streamGenerateContent` API. Maps function calls, cached and thinking tokens,
and replays model parts with their thought signatures through `provider_data`.
Reads `GEMINI_API_KEY` (or `GOOGLE_API_KEY`); `base_url` includes `/v1beta`.

**What you yield.** Each `Delta` carries any of these, all optional:

Expand Down
16 changes: 15 additions & 1 deletion examples/providers/fixtures/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ recorded=path)` replays them in order: line 1 answers the text turn, line 2
the tool turn, and line 3, when present, must make the adapter raise a
`ModelError`.

Request headers that carry a key (`authorization`, `x-api-key`, `api-key`)
Request headers that carry a key (`authorization`, `x-api-key`, `api-key`, `x-goog-api-key`)
are stored as `‹redacted›`.

## Where each line came from
Expand All @@ -24,6 +24,20 @@ live recording by running `record.py`, then update this table.
| `openai_chat_lmstudio.jsonl` | hand-written | hand-written, tool call id `""` | none | LM Studio's OpenAI-compatible server, which sends empty tool call ids |
| `anthropic_messages.jsonl` | hand-written | hand-written, a signed thinking block, a redacted thinking block and a tool call | hand-written, 529 `overloaded_error` | Anthropic Messages streaming and errors docs |
| `ollama_native.jsonl` | recorded 3 Nov 2026, Ollama 0.40.14 with `qwen3:8b` | recorded 3 Nov 2026, same server; the call carries `id` and `function.index` | hand-written, 404 model not found | Ollama `/api/chat` docs and `server/routes.go` for line 3 |
| `gemini_native.jsonl` | hand-written | hand-written, thought and function-call signatures, cached and thinking tokens | hand-written, 429 `RESOURCE_EXHAUSTED` with `retry-after` | [Gemini generateContent REST reference](https://ai.google.dev/api/generate-content), including `Part`, `FunctionCall` and `UsageMetadata` |

The Gemini fixture was captured through `record.py` over `httpx.MockTransport`;
it is not a live Gemini recording. Replace it with a free-tier recording when a
key is available:

```bash
uv run python -m examples.providers.record gemini_native \\
--model gemini-2.5-flash --api-key-env GEMINI_API_KEY \\
--out examples/providers/fixtures/gemini_native.jsonl
```

The recorder writes the two successful turns; keep or replace the third error
exchange separately, as described above. Read the request bodies before committing.

Request bodies are recorded as sent. The recorder redacts keys in headers,
not in bodies, so read a new fixture before committing it; the test suite
Expand Down
3 changes: 3 additions & 0 deletions examples/providers/fixtures/gemini_native.jsonl
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
{"request": {"method": "POST", "url": "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:streamGenerateContent?alt=sse", "headers": {"host": "generativelanguage.googleapis.com", "accept": "*/*", "accept-encoding": "identity", "connection": "keep-alive", "user-agent": "python-httpx/0.28.1", "x-goog-api-key": "‹redacted›", "content-length": "181", "content-type": "application/json"}, "body": {"contents": [{"role": "user", "parts": [{"text": "Reply with exactly the word: pong"}]}], "systemInstruction": {"parts": [{"text": "You are a test subject. Follow instructions exactly."}]}}}, "status": 200, "headers": {"content-type": "text/event-stream", "content-length": "191"}, "body_lines": ["data: {\"candidates\": [{\"index\": 0, \"content\": {\"role\": \"model\", \"parts\": [{\"text\": \"pong\"}]}, \"finishReason\": \"STOP\"}], \"usageMetadata\": {\"promptTokenCount\": 16, \"candidatesTokenCount\": 1}}", "", ""]}
{"request": {"method": "POST", "url": "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:streamGenerateContent?alt=sse", "headers": {"host": "generativelanguage.googleapis.com", "accept": "*/*", "accept-encoding": "identity", "connection": "keep-alive", "user-agent": "python-httpx/0.28.1", "x-goog-api-key": "‹redacted›", "content-length": "472", "content-type": "application/json"}, "body": {"contents": [{"role": "user", "parts": [{"text": "Call the echo tool with text set to ping. Do not answer in prose."}]}], "systemInstruction": {"parts": [{"text": "You are a test subject. Follow instructions exactly."}]}, "tools": [{"functionDeclarations": [{"name": "echo", "description": "Echo the given text back.", "parametersJsonSchema": {"type": "object", "properties": {"text": {"type": "string", "description": "The text to echo."}}, "required": ["text"], "additionalProperties": false}}]}]}}, "status": 200, "headers": {"content-type": "text/event-stream", "content-length": "500"}, "body_lines": ["data: {\"candidates\": [{\"index\": 0, \"content\": {\"role\": \"model\", \"parts\": [{\"text\": \"Use echo.\", \"thought\": true, \"thoughtSignature\": \"fixture-signature\"}]}}]}", "", "data: {\"candidates\": [{\"index\": 0, \"content\": {\"role\": \"model\", \"parts\": [{\"functionCall\": {\"name\": \"echo\", \"args\": {\"text\": \"ping\"}}, \"thoughtSignature\": \"fixture-function-signature\"}]}, \"finishReason\": \"STOP\"}], \"usageMetadata\": {\"promptTokenCount\": 28, \"candidatesTokenCount\": 6, \"thoughtsTokenCount\": 4, \"cachedContentTokenCount\": 8}}", "", ""]}
{"request": {"method": "POST", "url": "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:streamGenerateContent?alt=sse", "headers": {"host": "generativelanguage.googleapis.com", "accept": "*/*", "accept-encoding": "identity", "connection": "keep-alive", "user-agent": "python-httpx/0.28.1", "x-goog-api-key": "‹redacted›", "content-length": "181", "content-type": "application/json"}, "body": {"contents": [{"role": "user", "parts": [{"text": "Reply with exactly the word: pong"}]}], "systemInstruction": {"parts": [{"text": "You are a test subject. Follow instructions exactly."}]}}}, "status": 429, "headers": {"content-type": "application/json", "retry-after": "3"}, "body_lines": ["{\"error\": {\"code\": 429, \"status\": \"RESOURCE_EXHAUSTED\", \"message\": \"Quota exceeded.\"}}"]}
Loading
Loading