Compare commits
+11
-9
@@ -8,17 +8,19 @@ API_HOST=0.0.0.0
|
||||
API_PORT=8000
|
||||
API_PREFIX=/v1
|
||||
|
||||
# Anthropic Configuration (Claude - preferred backend)
|
||||
# Set ANTHROPIC_API_KEY to enable Claude as the default backend
|
||||
# Without an API key, Tatlock uses Ollama exclusively
|
||||
# ANTHROPIC_API_KEY=sk-ant-api03-your-key-here
|
||||
ANTHROPIC_MODEL=claude-sonnet-4-20250514
|
||||
PREFER_CLOUD_BACKEND=true
|
||||
|
||||
# Ollama Configuration (local fallback when Claude unavailable)
|
||||
# Ollama Configuration (local - primary backend)
|
||||
OLLAMA_HOST=http://localhost:11434
|
||||
OLLAMA_DEFAULT_MODEL=mistral-nemo:latest
|
||||
OLLAMA_DEFAULT_MODEL=gemma4:e2b
|
||||
OLLAMA_TIMEOUT=120
|
||||
STEWARD_TIMEOUT=60
|
||||
|
||||
# Anthropic Configuration (Claude - cloud fallback)
|
||||
# Set ANTHROPIC_API_KEY to keep the Claude fallback available: it is used
|
||||
# automatically when Ollama is down, or exclusively when PREFER_CLOUD_BACKEND=true
|
||||
# Without an API key, Tatlock uses Ollama only
|
||||
# ANTHROPIC_API_KEY=sk-ant-api03-your-key-here
|
||||
ANTHROPIC_MODEL=claude-sonnet-5
|
||||
PREFER_CLOUD_BACKEND=false
|
||||
|
||||
# SearXNG Configuration
|
||||
SEARXNG_HOST=http://localhost:8087
|
||||
|
||||
@@ -25,7 +25,7 @@ jobs:
|
||||
- name: Login to Gitea Registry
|
||||
uses: docker/login-action@v3
|
||||
with:
|
||||
registry: git.schweitz.internal
|
||||
registry: git.schweitz.net
|
||||
username: ${{ secrets.REGISTRY_USER }}
|
||||
password: ${{ secrets.REGISTRY_PASSWORD }}
|
||||
|
||||
@@ -37,8 +37,8 @@ jobs:
|
||||
provenance: false
|
||||
sbom: false
|
||||
tags: |
|
||||
git.schweitz.internal/jpmschweitzer/tatlock:latest
|
||||
git.schweitz.internal/jpmschweitzer/tatlock:${{ github.ref_name }}
|
||||
git.schweitz.net/jpmschweitzer/tatlock:latest
|
||||
git.schweitz.net/jpmschweitzer/tatlock:${{ github.ref_name }}
|
||||
|
||||
- name: Trigger Watchtower update
|
||||
if: success()
|
||||
|
||||
+11
-6
@@ -46,27 +46,32 @@ ENV/
|
||||
.ipynb_checkpoints/
|
||||
*.ipynb
|
||||
|
||||
# Testing & Coverage
|
||||
# Caches (pytest, mypy, ruff)
|
||||
.cache/
|
||||
|
||||
# Build output (coverage, logs)
|
||||
build/
|
||||
|
||||
# Legacy cache/output locations (in case tools fall back)
|
||||
.pytest_cache/
|
||||
.mypy_cache/
|
||||
.ruff_cache/
|
||||
.coverage
|
||||
.coverage.*
|
||||
coverage.xml
|
||||
htmlcov/
|
||||
|
||||
# Testing
|
||||
.tox/
|
||||
.nox/
|
||||
*.cover
|
||||
.hypothesis/
|
||||
|
||||
# Type checking
|
||||
.mypy_cache/
|
||||
.dmypy.json
|
||||
dmypy.json
|
||||
.pyre/
|
||||
.pytype/
|
||||
|
||||
# Linting
|
||||
.ruff_cache/
|
||||
|
||||
# Logs
|
||||
logs/*
|
||||
!logs/traces/
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
This document contains instructions and documentation references for AI assistants working with this codebase.
|
||||
|
||||
> **📖 Important**: Before working on this project, read [PHILOSOPHY.md](PHILOSOPHY.md) to understand the system vision, architectural patterns, and design goals. All development should work towards realizing those patterns.
|
||||
> **📖 Important**: Before working on this project, read [docs/philosophy.md](docs/philosophy.md) to understand the system vision, architectural patterns, and design goals. All development should work towards realizing those patterns.
|
||||
# AGENTS.md
|
||||
|
||||
> **Start every session by reading this file.**
|
||||
@@ -17,8 +17,8 @@ This document contains instructions and documentation references for AI assistan
|
||||
|
||||
### 🧪 Local Development Setup
|
||||
* **Always test locally first** before committing and deploying. The build-deploy loop is slow.
|
||||
* **Start the local server** with `./wakeup.sh` - logs are written to `logs/server.log` for easy tailing
|
||||
* **Auto-reload**: The wakeup script runs uvicorn in reload mode - code changes are picked up automatically without restart (except for requirements.txt changes)
|
||||
* **Start the local server** with `make run` - logs are written to `build/logs/server.log` for easy tailing
|
||||
* **Auto-reload**: `make run` runs uvicorn in reload mode - code changes are picked up automatically without restart (except for dependency changes)
|
||||
* **Test REST endpoints** against `http://localhost:8777` using curl or similar tools
|
||||
* **Only deploy** when a phase or feature is complete and tested locally
|
||||
* **Environment**: Copy `.env.example` to `.env` and configure for your local setup (Ollama, Redis, Qdrant hosts)
|
||||
|
||||
+109
-1
@@ -7,6 +7,112 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
## [2.4.3] - 2026-08-08
|
||||
|
||||
### Fixed
|
||||
|
||||
- Steward routing no longer triggers on words inside its own explanation. Capability
|
||||
extraction reads the declared `DELEGATE:` line instead of substring-matching
|
||||
capability domains across the whole response, where ordinary English routed
|
||||
requests — "description" contains the housekeeper domain "script", "acknowledge"
|
||||
contains "knowledge" and "know". A spurious capability meant a real agent call,
|
||||
including web searches, on queries that needed none.
|
||||
|
||||
## [2.4.2] - 2026-07-19
|
||||
|
||||
### Fixed
|
||||
|
||||
- Container crash-loop on fresh builds: cap `opentelemetry-api` below 1.44,
|
||||
which removed the private `_events` module that pydantic-ai 1.27 imports
|
||||
|
||||
## [2.4.1] - 2026-07-19
|
||||
|
||||
### Changed
|
||||
|
||||
- **Container-name network defaults** - `SEARXNG_HOST`, `LIBRARY_DESK_HOST`, and `CORE_API_HOST` now default to docker container names on the docker-dataplane network (`http://searxng:8080`, `http://library-desk:8089`, `http://core-api:8083`) instead of host `localhost` ports, ahead of the loopback port rebinding; this also fixes `CORE_API_HOST` pointing at port 8090 (the Scheduler's host port) rather than Core-API's 8083. `scripts/test_housekeeper.sh` now reaches Core-API via `localhost:8083` instead of the LAN IP. Local development against host-published ports still works via `.env` overrides
|
||||
|
||||
## [2.4.0] - 2026-07-14
|
||||
|
||||
### Removed
|
||||
|
||||
- **Dead delegation stack** - deleted the duplicate, never-wired coordination layer so exactly ONE delegation implementation remains (`src/agents/delegation.py`): `src/agents/coordination.py` (`CoordinationEngine`, its own `delegate_to_librarian`, `AGENT_EXECUTORS`/`AGENT_STREAM_EXECUTORS`), the broken-by-design `run_librarian_stream` path it used (Ollama streaming + tool call bug), the `stream_delegate_to_*` wrappers with their never-parsed `__DELEGATION_RESULT__` marker, and `HouseholdRegistry.get_streaming_delegation_tools()` (no callers)
|
||||
- **Orphaned agent protocol models** - `src/agents/protocol.py` now contains only the live `AgentError`; the coordination wire protocol it carried (`AgentRequest`, `AgentResponse`, `DelegationIntent`, `CoordinationResult`, `DelegationReason`, `TaskComplexity`, `ToolCallRecord`, `AgentTimeoutError`, `AgentUnavailableError`, `DelegationError`) had no importer left outside its own tests after the coordination stack removal
|
||||
|
||||
### Added
|
||||
|
||||
- **Test-suite tenant guard** - `tests/conftest.py` hard-fails the whole pytest session (exit code 1, zero tests run) if the effective tenant resolves to the production tenant `jpmschweitzer`, mirroring the guard library-desk applies on its side. Suite-level assertions pin that the session runs under `llm_tester` namespaces (Qdrant `memories_llm_tester`, Redis `session:llm_tester:*`), and the e2e isolation constants now derive from the shared `TEST_TENANT`/`PRODUCTION_TENANT` config constants instead of string literals
|
||||
- **Explicit tenant on every library-desk request** - the librarian client now resolves and sends the `user` parameter explicitly on every request (library-desk is removing its server-side default; a missing user would 422). The content extraction endpoints now carry the tenant too, `search_web` no longer falls back to a phantom `tatlock-librarian` user, and a client-level assertion rejects an empty/whitespace tenant before any bytes hit the wire. A parametrized sweep pins the wire contract for all 15 tenant-scoped client methods
|
||||
- **Tenant isolation guard** - non-production environments (development/testing) now FORCE the effective tenant to the reserved test tenant `llm_tester` (only `llm_tester` itself or a `test_`-prefixed override is accepted), regardless of `DEFAULT_USER` misconfiguration, at both config resolution and request-context resolution (`get_user()`). Startup refuses (clear error) when a non-production environment is explicitly configured with the production tenant `jpmschweitzer`, and one loud startup log line states the effective/forced tenant
|
||||
|
||||
- **Conversation context for experts + real-time think messages** - direct delegation (streaming and non-streaming) now passes a trimmed conversation history (last 6 turns) as expert context, so follow-up questions keep their referent; `_stream_direct_delegation` is now an async generator, so butler think messages ("Allow me to consult the archives, sir.") stream BEFORE the research runs instead of after it completes
|
||||
- **Bounded retries and connection reuse for library-desk** - GETs and the read-only `POST /query/*` and `POST /rag/search` endpoints retry once (2 attempts, short backoff) on transport errors and retryable 5xx; wiki writes are never retried. The client now honors `LIBRARY_DESK_TIMEOUT` instead of hardcoded 60s/30s, a librarian run holds one shared HTTP connection instead of constructing a client per tool call, and read tools raise `ModelRetry` on transient HTTP errors so the agent's retry budget engages
|
||||
- **One librarian timeout budget** - new `LIBRARIAN_TIMEOUT` (default 180s) enforced with `asyncio.wait_for` inside `delegate_to_librarian`, capping the previously uncapped live paths (steward direct delegation and streaming). The Ollama provider's AsyncOpenAI client now carries an explicit `OLLAMA_TIMEOUT` instead of the SDK's ~600s default, and the contradictory unused 60s default in `AgentRequest.timeout_seconds` was removed (None defers to the configured budget)
|
||||
- **Search degradation signaling** - The librarian client parses `source_counts` (plus the additive `source_status`/`degraded` fields when a newer library-desk sends them; absence is tolerated), and `hybrid_search` appends a one-line coverage note when a search is degraded or an enabled source leg contributed nothing, so outages are visible to the model and the user. When `source_status` is present it is used exclusively; without it, count-absence is only inferred for the optional legs the request explicitly enabled (web/documents/volatile) - never the always-on vector/graph legs, whose absence from the top-N counts is normal ranking behavior, so healthy searches no longer emit warnings
|
||||
|
||||
### Fixed
|
||||
|
||||
- **Clearing all wiki-page tags is possible again** - the Ollama-safe empty-list sentinel in `update_wiki_page` means "leave unchanged", which made it impossible to remove all tags; passing exactly `["__CLEAR__"]` now sends an empty tag list to library-desk (documented in the tool docstring for the local model)
|
||||
- **Text-delegation fallback pairs results strictly** - the parallel branch now verifies `asyncio.gather` returned one result per parsed delegation (`zip(..., strict=True)`); a count mismatch fails loudly with a curated apology instead of silently attributing outputs to the wrong agent
|
||||
- **Ollama-safe librarian tool schemas** - `update_wiki_page` and `smart_create_wiki_page` no longer use `X | None` parameters (Ollama's OpenAI-compatible API mishandles `anyOf[X, null]`); empty-string/empty-list sentinels are translated to `None` inside the tools, matching the biographer pattern. A snapshot test pins every librarian tool schema to contain no nullable `anyOf`
|
||||
- **Honest expert failures** - `run_librarian` now raises a structured `AgentError` instead of returning error text as if it were research output, so delegation correctly reports `success=False` and the streaming error branch is reachable. Failures surface to the user as curated butler-toned sentences; exception detail (including internal URLs) stays in the logs only. Librarian tool errors no longer leak `str(e)` into synthesis
|
||||
|
||||
- **HybridRAG response mapping** - The librarian client now parses the field names library-desk actually returns (`source_type`/`sources`, `rrf_score`, `context`, per-item `related_dossiers`, synonyms nested in the `keywords` dict); previously every result rendered as "unknown (score: 0.00)". Source icons now key off the per-item `sources` list. Requests no longer send zero limits (the service rejects them with 422); legs are disabled via `enable_*` flags. Pinned by a contract test against a recorded live response (`tests/agents/librarian/fixtures/`)
|
||||
|
||||
## [2.3.0] - 2026-07-13
|
||||
|
||||
### Changed
|
||||
|
||||
- **Local-first backend (claudification rollback)** - Ollama/gemma4 is now the primary backend; Claude remains as fallback. `PREFER_CLOUD_BACKEND` defaults to `false`, Claude is used automatically when the Ollama startup health check fails, and the Steward retries mid-request failures on the other backend in both directions
|
||||
- **Default Claude model `claude-sonnet-5`** - `claude-sonnet-4-20250514` was retired by Anthropic on 2026-06-15 and would 404, leaving the fallback dead
|
||||
- **Dedicated orchestration prompt** - `orchestrate_tool_calls()` now uses a terse tool-execution prompt (`TATLOCK_ORCHESTRATION_PROMPT`); the butler persona prompt suppressed gemma4 tool calling (the model reasoned about the calculator, then answered from memory with wrong arithmetic). Synthesis keeps the persona prompt, so user-visible voice is unchanged
|
||||
|
||||
### Fixed
|
||||
|
||||
- **Startup crash with broken anthropic package** - Anthropic SDK imports in the model selector are now lazy, so an incompatible `anthropic` install degrades to Ollama-only operation instead of crashing the app at import time (root cause of the production outage since April)
|
||||
- **Claude Sonnet 5 rejects sampling parameters** - removed `temperature` from the Steward's direct Claude call and made the Housekeeper's temperature setting backend-conditional via `get_sampling_settings()`
|
||||
- **Pin `anthropic>=0.77,<1.0`** - the April image resolved an anthropic version incompatible with pydantic-ai 1.27
|
||||
- **Steward timeout configurable** - new `STEWARD_TIMEOUT` (default 60s) replaces the hardcoded 30s, which gemma4 chronically exceeded (~35s warm analysis), causing every request to fail or fall back
|
||||
|
||||
### Added
|
||||
|
||||
- **Ollama startup health check** - verifies the server is reachable and `OLLAMA_DEFAULT_MODEL` is pulled; feeds backend resolution and `get_model_info()`
|
||||
- **Contract tests** (`tests/contracts/`, `make test-contracts`) - wire-level tests that send the raw requests the code sends to Ollama (native + OpenAI-compat tool calling), Anthropic (including the pinned temperature-rejection contract), Qdrant, SearXNG, library-desk, and Redis; unreachable services skip, wrong response shapes fail
|
||||
- **Backend resolution unit tests** (`tests/anthropic/`)
|
||||
|
||||
## [2.2.0] - 2026-04-04
|
||||
|
||||
### Changed
|
||||
|
||||
- **Switch default Ollama model to gemma4:e2b** - Replaces mistral-nemo as the local LLM backend; gemma4:e2b has native function calling support, faster tool calling (2-4s vs 15-20s), better parameter accuracy on word problems, and uses less VRAM (8GB vs 9.2GB)
|
||||
|
||||
### Added
|
||||
|
||||
- **Tool calling benchmark script** (`scripts/benchmark_tool_calling.py`) - Compares tool calling accuracy and latency across Ollama models via the Tatlock API
|
||||
|
||||
## [2.1.0] - 2026-02-05
|
||||
|
||||
### Fixed
|
||||
|
||||
- **Streaming SSE compatibility with Open WebUI** - Switch from `exclude_none=True` to `exclude_unset=True` for SSE chunk serialization; `exclude_none` was too aggressive — it stripped `finish_reason: null` from intermediate chunks (which OpenAI includes), while `exclude_unset` correctly omits only fields never passed to the constructor (like `reasoning_content` on content-only chunks) while preserving explicitly-set `finish_reason: null`
|
||||
|
||||
### Changed
|
||||
|
||||
- **Project structure consolidation** - Moved documentation to `docs/`, consolidated all config into `pyproject.toml`, replaced `wakeup.sh`/`pytest.ini`/`requirements*.txt` with `Makefile` + `pyproject.toml`
|
||||
- **CI test gate** - Unit tests now gate release and build jobs in Gitea Actions workflow
|
||||
- **Build output organization** - Tool caches in `.cache/`, generated output (coverage, logs) in `build/`
|
||||
|
||||
## [2.0.5] - 2026-02-05
|
||||
|
||||
### Fixed
|
||||
|
||||
- **Streaming JSON compatibility** - Exclude null fields from streaming chunks using `exclude_none=True`; OpenAI's API omits null fields entirely, and including them (e.g., `content: null`, `reasoning_content: null`) caused parsing issues in Open WebUI
|
||||
|
||||
## [2.0.4] - 2026-02-05
|
||||
|
||||
### Fixed
|
||||
|
||||
- **Open WebUI streaming compatibility** - Replaced `sse_starlette` `EventSourceResponse` with plain `StreamingResponse` for chat completions; `sse_starlette` added `\r\n` line endings and extra SSE fields that Open WebUI couldn't parse
|
||||
|
||||
## [2.0.3] - 2026-02-05
|
||||
|
||||
### Fixed
|
||||
@@ -909,7 +1015,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
||||
- CORS middleware
|
||||
- Exception handlers (OpenAI-compatible error format)
|
||||
|
||||
[Unreleased]: https://git.schweitz.net/jpmschweitzer/tatlock/compare/v2.0.0...main
|
||||
[Unreleased]: https://git.schweitz.net/jpmschweitzer/tatlock/compare/v2.1.0...main
|
||||
[2.1.0]: https://git.schweitz.net/jpmschweitzer/tatlock/compare/v2.0.5...v2.1.0
|
||||
[2.0.5]: https://git.schweitz.net/jpmschweitzer/tatlock/compare/v2.0.0...v2.0.5
|
||||
[2.0.0]: https://git.schweitz.net/jpmschweitzer/tatlock/compare/v1.11.0...v2.0.0
|
||||
[1.11.0]: https://git.schweitz.net/jpmschweitzer/tatlock/compare/v1.10.0...v1.11.0
|
||||
[1.10.0]: https://git.schweitz.net/jpmschweitzer/tatlock/compare/v1.9.0...v1.10.0
|
||||
|
||||
@@ -0,0 +1,34 @@
|
||||
# CLAUDE.md
|
||||
|
||||
Claude Code-specific notes for this project. For general development instructions, architecture, coding standards, and deployment — see [AGENTS.md](AGENTS.md).
|
||||
|
||||
## Setup & Commands
|
||||
|
||||
```bash
|
||||
make setup # Create venv and install all dependencies
|
||||
make test # Unit tests (no external services)
|
||||
make test-integration # Integration tests (needs Claude/Ollama)
|
||||
make test-contracts # Wire-level contract tests against live service boundaries
|
||||
make run # Start dev server on port 8777
|
||||
make lint # Ruff linter + formatter check
|
||||
make typecheck # Mypy
|
||||
make clean # Remove caches and build artifacts
|
||||
```
|
||||
|
||||
Dependencies are in `pyproject.toml` (`[project.dependencies]` and `[project.optional-dependencies.dev]`).
|
||||
|
||||
## Critical Gotchas
|
||||
|
||||
**ASGITransport does NOT trigger FastAPI lifespan events.** The session-scoped `_initialize_app` fixture in `tests/conftest.py` calls `initialize_application()` explicitly via `asyncio.run()`. Without this, the Ollama/Claude health checks never run: `_ollama_available` stays `None` (treated as available, so requests go to Ollama) and `_claude_available` stays `None` (treated as unavailable, so the Claude fallback never engages).
|
||||
|
||||
**AsyncIO scope mismatch.** `asyncio_default_fixture_loop_scope = function` is set in `pyproject.toml`. Session-scoped async fixtures cause `ScopeMismatch` errors. The fix is to use a sync fixture with `asyncio.run()` for session-scoped initialization.
|
||||
|
||||
**The butler persona prompt suppresses local-model tool calling.** With `TATLOCK_SYSTEM_PROMPT` attached, gemma4 reasons about calling the calculator, then answers from memory with wrong arithmetic (a different wrong product each run). `orchestrate_tool_calls()` therefore uses the terse `TATLOCK_ORCHESTRATION_PROMPT`; the persona is applied in `synthesize_from_results()`. Do not reattach the persona prompt to a tool-phase agent. `tool_choice: "required"` via extra_body does NOT force Ollama to call tools — it is advisory at best.
|
||||
|
||||
**Claude Sonnet 5+ rejects sampling parameters.** `temperature`/`top_p`/`top_k` return a 400. Use `get_sampling_settings()` from the model selector instead of passing `ModelSettings(temperature=...)` directly to agents that can run on the Claude fallback. The contract test suite pins this (`make test-contracts`).
|
||||
|
||||
**Integration test timeouts.** Set to 120s to match `OLLAMA_TIMEOUT` config (300s for the pure-Ollama fallback test, which cannot be rescued by Claude). Current GPU-resident numbers (measured 2026-08-07, gemma4:e2b at ~95 tok/s): full Steward → orchestrate → synthesize flow ~10–13s for simple turns; librarian-routed queries ~20-25s (not re-measured). A single turn costs **3 sequential Ollama calls and ~710 generated tokens** even for "what is 61 plus 12?" — most of it the model's own reasoning, paid three times. Cold model load is ~36s, avoided while the model is pinned with `keep_alive: -1`; the `OLLAMA_KEEP_ALIVE=2h` default otherwise reintroduces it. The old "~35s steward / ~2 min flow" and "11–25s flow" figures are superseded — do not plan against them. `STEWARD_TIMEOUT` defaults to 60s.
|
||||
|
||||
**`get_benchmark_store` does not exist.** The benchmarking module (`src/core/benchmarks.py`) was never implemented. `scripts/benchmark_analysis.py` also references it and is broken. Do not add mocks for it in tests.
|
||||
|
||||
**Steward tests need household registry.** Use `register_household_members()` (sync) in fixtures, not `initialize_application()` (async). The steward extracts capabilities from the registry.
|
||||
+2
-2
@@ -5,8 +5,8 @@ WORKDIR /app
|
||||
RUN apt-get update && apt-get install -y curl \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
|
||||
COPY requirements.txt pyproject.toml ./
|
||||
RUN pip install --no-cache-dir -r requirements.txt
|
||||
COPY pyproject.toml ./
|
||||
RUN pip install --no-cache-dir .
|
||||
|
||||
COPY src/ ./src/
|
||||
|
||||
|
||||
@@ -1,920 +0,0 @@
|
||||
# Tatlock Implementation Roadmap
|
||||
|
||||
> **Reference**: See [PHILOSOPHY.md](PHILOSOPHY.md) for the target architecture and vision
|
||||
|
||||
This document outlines the phased implementation plan to transform the current OpenAI-compatible API into the full Tatlock household butler system.
|
||||
|
||||
## Current State (v1.2.0 - Phase F Complete)
|
||||
|
||||
**What we have**:
|
||||
- ✅ **The Orchestrator** - FastAPI infrastructure layer
|
||||
- OpenAI-compatible API endpoints (Responses API + Chat Completions)
|
||||
- Streaming coordination and conversation management
|
||||
- Response format with reasoning support
|
||||
- Test infrastructure (~400 tests)
|
||||
- ✅ **Two-Tier Architecture**
|
||||
- The Steward analyzes requests and recommends capabilities
|
||||
- Tatlock coordinates execution with scoped tools
|
||||
- Real-time streaming of analysis and reasoning
|
||||
- ✅ **Household Staff**
|
||||
- **Tatlock** (Butler): Primary interface with witty personality
|
||||
- **The Steward**: Request analysis and capability recommendation
|
||||
- **The Librarian**: Research via library-desk HybridRAG + wiki
|
||||
- **The Biographer**: User memory, profiles, preferences, semantic recall
|
||||
- ✅ **Core Tools**
|
||||
- Calculator, Date/Time toolkit, Web search (SearXNG)
|
||||
- ✅ **Memory System**
|
||||
- Direct access layer (memory_service) for fast lookups
|
||||
- Vector storage (Qdrant) for semantic recall
|
||||
- Session cache (Redis) with 24h TTL
|
||||
- Multi-tenancy via ContextVar
|
||||
- ✅ Mock agent (lorem-tester for testing)
|
||||
|
||||
**What we need**:
|
||||
- More household staff (Developer, Secretary, Handyman, Housekeeper)
|
||||
- MCP (Model Context Protocol) integration
|
||||
- Dynamic model switching for specialized tasks
|
||||
- Full multi-tenant database (PostgreSQL)
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Real LLM Integration - PydanticAI + Tools
|
||||
|
||||
**Goal**: Connect to actual language models and establish the base plumbing
|
||||
|
||||
**Note**: Ollama is an external service dependency (already running separately)
|
||||
|
||||
### Deliverables
|
||||
|
||||
1. **PydanticAI Integration** ✅
|
||||
- PydanticAI → Ollama connection ✅
|
||||
- Agent creation patterns ✅
|
||||
- Streaming response handling ✅
|
||||
- Error handling and retries ✅
|
||||
|
||||
2. **Convert Tatlock Agent** ✅
|
||||
- Convert Tatlock agent from mock to PydanticAI ✅
|
||||
- British butler personality prompt ✅
|
||||
- Research-oriented mindset ✅
|
||||
- Streaming to reasoning output ✅
|
||||
- Tool calling framework setup ✅
|
||||
|
||||
3. **Permanent Tools** ✅
|
||||
- Calculator: Safe mathematical expression evaluation ✅
|
||||
- Date/Time toolkit: Current time, relative dates, time differences ✅
|
||||
- Web search: SearXNG integration (external service) ✅
|
||||
- Tool registration with PydanticAI ✅
|
||||
|
||||
4. **Testing Infrastructure** ✅
|
||||
- Integration tests with real LLM ✅
|
||||
- Tool functionality tests ✅
|
||||
- Response quality validation ✅
|
||||
- 131 tests, 81.78% coverage ✅
|
||||
|
||||
### Success Criteria
|
||||
- [x] **PydanticAI agents can call Ollama** (mistral-nemo:latest)
|
||||
- [x] **Streaming works end-to-end**
|
||||
- [x] **Tool calling framework functional**
|
||||
- [x] **Permanent tools working** (calculator, date/time, search)
|
||||
- [x] **Tests pass with real LLM**
|
||||
- [ ] Can switch models dynamically (e.g., Codestral for code)
|
||||
|
||||
### Status
|
||||
**✅ MOSTLY COMPLETE** - Tatlock agent functional with permanent tools
|
||||
|
||||
### Remaining Work
|
||||
- Dynamic model switching for specialized tasks (e.g., Codestral for coding)
|
||||
|
||||
### Why First?
|
||||
Without real LLM integration, we can't meaningfully implement the Steward/Butler pattern. Everything else depends on having actual AI agents working.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Orchestration Layer - The Steward
|
||||
|
||||
**Goal**: Implement the first-tier LLM call for tool/agent selection
|
||||
|
||||
**Purpose**: The Steward performs crucial preparatory work before Tatlock engages with a request. By analyzing incoming requests and determining which tools, services, and household staff members will be needed, the Steward creates a curated recommendation that streamlines Tatlock's work and prevents cognitive overload.
|
||||
|
||||
### Core Architecture
|
||||
|
||||
The Steward operates as the first tier in the two-tier request flow:
|
||||
|
||||
```
|
||||
User Request → Orchestrator → Steward Analysis → Recommendations → Tatlock (with scoped tools/agents)
|
||||
```
|
||||
|
||||
**Key Principle**: The Steward narrows the scope to only relevant capabilities, making Tatlock's decision-making cleaner and more focused.
|
||||
|
||||
### Deliverables
|
||||
|
||||
#### 1. Tool & Agent Registry System
|
||||
|
||||
**Purpose**: Centralized catalog of all available capabilities for the Steward to recommend
|
||||
|
||||
**Implementation Details**:
|
||||
- **Registry Module** (`src/core/registry.py`)
|
||||
- Tool registration decorator pattern
|
||||
- Agent registration with capability metadata
|
||||
- Category-based organization (computation, information, automation, communication)
|
||||
- Dynamic tool/agent discovery and loading
|
||||
|
||||
- **Tool Metadata Schema**
|
||||
```python
|
||||
{
|
||||
"name": "calculator",
|
||||
"category": "computation",
|
||||
"description": "Safe mathematical expression evaluation",
|
||||
"capabilities": ["arithmetic", "algebra", "trigonometry"],
|
||||
"cost": "low", # computational cost indicator
|
||||
"requires_network": false
|
||||
}
|
||||
```
|
||||
|
||||
- **Agent Metadata Schema**
|
||||
```python
|
||||
{
|
||||
"name": "developer",
|
||||
"role": "The Developer",
|
||||
"category": "technical",
|
||||
"description": "Software development assistance",
|
||||
"domains": ["code_generation", "debugging", "architecture"],
|
||||
"specialized_model": "codestral", # optional
|
||||
"cost": "high"
|
||||
}
|
||||
```
|
||||
|
||||
- **Registry API**
|
||||
- `get_all_tools()` - List all available tools
|
||||
- `get_all_agents()` - List all expert agents
|
||||
- `get_by_category(category)` - Filter by category
|
||||
- `search_by_capability(query)` - Semantic search (future: vector search)
|
||||
|
||||
**Testing**:
|
||||
- Unit tests for registration and retrieval
|
||||
- Test dynamic loading of new tools/agents
|
||||
- Validate metadata schemas
|
||||
|
||||
#### 2. Steward PydanticAI Agent
|
||||
|
||||
**Purpose**: First-tier LLM that analyzes requests and recommends relevant tools/agents
|
||||
|
||||
**Implementation Details**:
|
||||
|
||||
- **Agent Module** (`src/agents/steward.py`)
|
||||
```python
|
||||
from pydantic_ai import Agent, RunContext
|
||||
from pydantic import BaseModel
|
||||
|
||||
class StewardRecommendation(BaseModel):
|
||||
"""Structured output from Steward analysis"""
|
||||
recommended_tools: list[str]
|
||||
recommended_agents: list[str]
|
||||
reasoning: str
|
||||
estimated_complexity: str # "simple", "moderate", "complex"
|
||||
requires_multi_step: bool
|
||||
|
||||
steward = Agent(
|
||||
'ollama:mistral-nemo', # Same base model as Tatlock
|
||||
result_type=StewardRecommendation,
|
||||
system_prompt="""..."""
|
||||
)
|
||||
```
|
||||
|
||||
- **System Prompt Engineering**
|
||||
- Role: Estate steward responsible for efficient household coordination
|
||||
- Task: Analyze requests to determine needed resources
|
||||
- Output: Structured recommendations with reasoning
|
||||
- Constraints: Be conservative (recommend only truly relevant capabilities)
|
||||
- Context: Full registry of available tools and agents
|
||||
|
||||
- **Steward Tools**
|
||||
```python
|
||||
@steward.tool
|
||||
def get_available_capabilities(ctx: RunContext) -> dict:
|
||||
"""Get catalog of all available tools and agents."""
|
||||
return {
|
||||
"tools": registry.get_all_tools(),
|
||||
"agents": registry.get_all_agents()
|
||||
}
|
||||
```
|
||||
|
||||
- **Request Analysis Flow**
|
||||
1. Receive user request
|
||||
2. Query capability registry via tool
|
||||
3. Analyze request for required capabilities
|
||||
4. Generate structured recommendation
|
||||
5. Format as note to Tatlock
|
||||
|
||||
**Testing**:
|
||||
- Test various request types (simple, complex, multi-domain)
|
||||
- Verify recommendations are relevant and not over-inclusive
|
||||
- Test structured output parsing
|
||||
- Validate reasoning quality
|
||||
|
||||
#### 3. Request Preprocessing Pipeline
|
||||
|
||||
**Purpose**: Integration layer that routes requests through Steward before Tatlock
|
||||
|
||||
**Implementation Details**:
|
||||
|
||||
- **Preprocessing Module** (`src/core/preprocessing.py`)
|
||||
```python
|
||||
async def preprocess_request(user_request: str) -> EnrichedRequest:
|
||||
"""
|
||||
1. Call Steward for analysis
|
||||
2. Get recommendations
|
||||
3. Enrich original request
|
||||
4. Return scoped context for Tatlock
|
||||
"""
|
||||
# Get Steward analysis
|
||||
steward_result = await steward.run(user_request)
|
||||
recommendations = steward_result.data
|
||||
|
||||
# Create note to Tatlock
|
||||
steward_note = format_steward_note(recommendations)
|
||||
|
||||
# Build scoped tool/agent list
|
||||
scoped_tools = get_scoped_tools(recommendations.recommended_tools)
|
||||
scoped_agents = get_scoped_agents(recommendations.recommended_agents)
|
||||
|
||||
return EnrichedRequest(
|
||||
original_request=user_request,
|
||||
steward_note=steward_note,
|
||||
available_tools=scoped_tools,
|
||||
available_agents=scoped_agents,
|
||||
metadata=recommendations
|
||||
)
|
||||
```
|
||||
|
||||
- **Note Formatting**
|
||||
```
|
||||
=== Internal Note from the Steward ===
|
||||
|
||||
Request Analysis:
|
||||
{steward reasoning}
|
||||
|
||||
Recommended Tools:
|
||||
- calculator: For mathematical computations
|
||||
- web_search: To find current information
|
||||
|
||||
Recommended Household Staff:
|
||||
- The Developer: For code generation assistance
|
||||
|
||||
Estimated Complexity: moderate
|
||||
===================================
|
||||
|
||||
[Original User Request]
|
||||
```
|
||||
|
||||
- **Orchestrator Integration**
|
||||
- Modify `src/responses/service.py` to call preprocessing
|
||||
- Prepend Steward note to request before sending to Tatlock
|
||||
- Limit Tatlock's tool access to recommended tools only
|
||||
- Stream Steward's reasoning to output
|
||||
|
||||
**Testing**:
|
||||
- Integration tests for full preprocessing flow
|
||||
- Test request enrichment format
|
||||
- Verify tool scoping works correctly
|
||||
- Test streaming of Steward reasoning
|
||||
|
||||
#### 4. Real-Time Transparency
|
||||
|
||||
**Purpose**: Stream Steward's analysis to user's reasoning output
|
||||
|
||||
**Implementation Details**:
|
||||
|
||||
- **Streaming Integration** (`src/responses/streaming.py`)
|
||||
- Add Steward analysis phase to stream
|
||||
- Format as reasoning item
|
||||
- Include recommendation summary
|
||||
|
||||
- **Example Output to User**:
|
||||
```
|
||||
[Reasoning]
|
||||
Consulting the Steward for resource planning...
|
||||
|
||||
The Steward's Analysis:
|
||||
- Request requires mathematical computation
|
||||
- Need to verify current information via web search
|
||||
- May benefit from Developer's code expertise
|
||||
|
||||
Recommended: calculator, web_search, The Developer
|
||||
|
||||
Proceeding with scoped resources...
|
||||
```
|
||||
|
||||
**Testing**:
|
||||
- Test streaming of Steward analysis
|
||||
- Verify formatting in Open WebUI
|
||||
- Test error handling if Steward fails
|
||||
|
||||
#### 5. Model Efficiency Optimization
|
||||
|
||||
**Purpose**: Ensure the base model stays loaded in VRAM
|
||||
|
||||
**Implementation Details**:
|
||||
|
||||
- **Shared Model Configuration**
|
||||
- Both Steward and Tatlock use `ollama:mistral-nemo` by default
|
||||
- Sequential calls (Steward → Tatlock) keep model hot
|
||||
- No reload delays between tiers
|
||||
|
||||
- **Performance Monitoring**
|
||||
- Log response times for Steward calls
|
||||
- Track total request latency (Steward + Tatlock)
|
||||
- Identify optimization opportunities
|
||||
|
||||
**Testing**:
|
||||
- Benchmark Steward → Tatlock call latency
|
||||
- Verify model stays loaded between calls
|
||||
- Test performance under load
|
||||
|
||||
### Implementation Strategy
|
||||
|
||||
#### Week 1-2: Foundation
|
||||
- [ ] Design and implement registry system
|
||||
- [ ] Create tool/agent metadata schemas
|
||||
- [ ] Build registry API with tests
|
||||
- [ ] Migrate existing tools to registry
|
||||
|
||||
#### Week 3-4: Steward Agent
|
||||
- [ ] Create Steward PydanticAI agent
|
||||
- [ ] Engineer system prompt for analysis
|
||||
- [ ] Implement structured recommendation output
|
||||
- [ ] Add registry query tool
|
||||
- [ ] Test with various request types
|
||||
|
||||
#### Week 5-6: Integration
|
||||
- [ ] Build request preprocessing pipeline
|
||||
- [ ] Implement note formatting
|
||||
- [ ] Integrate with Orchestrator
|
||||
- [ ] Add streaming transparency
|
||||
- [ ] Tool scoping for Tatlock
|
||||
|
||||
#### Week 7: Testing & Refinement
|
||||
- [ ] End-to-end integration tests
|
||||
- [ ] Performance optimization
|
||||
- [ ] Prompt refinement based on results
|
||||
- [ ] Documentation and examples
|
||||
|
||||
### Success Criteria
|
||||
|
||||
- [x] **Steward analyzes incoming requests** using PydanticAI agent
|
||||
- [x] **Produces structured recommendations** (tools, agents, reasoning)
|
||||
- [x] **Recommendations formatted as prepended note** to Tatlock
|
||||
- [x] **Tool registry is queryable and extensible** via clean API
|
||||
- [x] **Steward output visible in reasoning stream** for transparency
|
||||
- [x] **Only recommended tools available** to Tatlock (scoped context)
|
||||
- [x] **Base model stays loaded** between Steward and Tatlock calls
|
||||
- [x] **Recommendations are accurate** (not over/under-inclusive)
|
||||
- [x] **Integration tests pass** for full Steward → Tatlock flow
|
||||
|
||||
### Status
|
||||
**✅ COMPLETE** (v0.2.5)
|
||||
|
||||
### Performance Targets
|
||||
|
||||
- **Steward Analysis Time**: < 2 seconds for typical requests
|
||||
- **Total Added Latency**: < 3 seconds including streaming
|
||||
- **Recommendation Accuracy**: > 90% relevance (manual evaluation)
|
||||
- **Model Reload Delay**: 0 seconds (model stays hot)
|
||||
|
||||
### Risk Mitigation
|
||||
|
||||
**Risk**: Steward recommendations too broad (defeats purpose)
|
||||
- Mitigation: Conservative prompt engineering, test with diverse requests, iterate
|
||||
|
||||
**Risk**: Added latency unacceptable to users
|
||||
- Mitigation: Stream Steward reasoning for transparency, optimize prompt, parallel processing where possible
|
||||
|
||||
**Risk**: Tool registry becomes unwieldy
|
||||
- Mitigation: Good categorization, semantic search (future), regular pruning
|
||||
|
||||
**Risk**: Steward and Tatlock models compete for VRAM
|
||||
- Mitigation: Use same base model, sequential calls, monitor memory
|
||||
|
||||
### Future Enhancements (Post-Phase 2)
|
||||
|
||||
- **Semantic Search**: Vector-based capability search instead of metadata lookup
|
||||
- **Learning from Usage**: Track which recommendations work well, adjust over time
|
||||
- **Confidence Scores**: Steward provides confidence for each recommendation
|
||||
- **Request Classification**: Cache classifications for similar requests
|
||||
- **Multi-Model Support**: Allow Steward to recommend specialized models for specific tasks
|
||||
|
||||
### Estimated Effort
|
||||
|
||||
**7-8 weeks** - Core intelligence routing with comprehensive implementation
|
||||
|
||||
### Why Second?
|
||||
|
||||
The Steward is the foundation of the household architecture. Without it, we'd need to expose all tools/agents to Tatlock, creating cognitive overload and poor decision-making. The Steward enables the focused expertise pattern that makes the whole system work.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: The Butler - Tatlock Agent
|
||||
|
||||
**Goal**: Implement the second-tier coordinator with personality within the existing Orchestrator infrastructure
|
||||
|
||||
**Context**: The Orchestrator (FastAPI infrastructure) already exists. This phase implements the real Tatlock PydanticAI agent to replace the current mock agent.
|
||||
|
||||
### Deliverables
|
||||
|
||||
1. **Butler Agent (Tatlock)**
|
||||
- PydanticAI agent implementation within Orchestrator
|
||||
- Personality prompt engineering (witty British butler)
|
||||
- Tool calling framework
|
||||
- Multi-agent coordination logic
|
||||
|
||||
2. **Scoped Tool Access**
|
||||
- Filter tools based on Steward recommendations
|
||||
- Dynamic tool loading for Butler context
|
||||
- Tool execution framework
|
||||
- Result aggregation
|
||||
|
||||
3. **Real-Time Reasoning Output**
|
||||
- Stream all Butler activities to reasoning output
|
||||
- Tool call progress indicators
|
||||
- Expert agent consultation messages
|
||||
- Wait time transparency
|
||||
|
||||
### Success Criteria
|
||||
- [x] Tatlock receives enriched requests (user + Steward notes)
|
||||
- [x] Only recommended tools are available
|
||||
- [x] Tatlock coordinates multiple tool calls
|
||||
- [x] All actions streamed to reasoning output
|
||||
- [x] Responses have consistent personality
|
||||
- [x] Synthesizes multi-source results coherently
|
||||
|
||||
### Status
|
||||
**✅ COMPLETE** (v1.1.0)
|
||||
|
||||
### Estimated Effort
|
||||
**4-5 weeks** - Complex coordination logic
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Expert Household Staff - Core Agents
|
||||
|
||||
**Goal**: Implement the initial set of domain-specific expert agents
|
||||
|
||||
### Priority Expert Agents
|
||||
|
||||
1. **The Librarian** (Research & Knowledge Management) ✅ **COMPLETE** (v1.1.0)
|
||||
- Research assistance via library-desk HybridRAG
|
||||
- Wiki page management (search, create, update)
|
||||
- Semantic vector search
|
||||
- Knowledge graph queries
|
||||
- Dossier browsing
|
||||
|
||||
2. **The Biographer** (User Memory) ✅ **COMPLETE** (v1.2.0)
|
||||
- User profile management (name, location, timezone)
|
||||
- Preference storage (units, theme)
|
||||
- Semantic memory recall ("What car do I drive?")
|
||||
- Fact storage from conversations
|
||||
- Session context caching
|
||||
|
||||
3. **The Developer** (Software Development) 🔜 **Planned**
|
||||
- Code generation assistance
|
||||
- Debugging support
|
||||
- Documentation generation
|
||||
- Architecture guidance
|
||||
- *Rationale: Directly supports building the system itself*
|
||||
|
||||
4. **The Handyman** (System Maintenance) 🔜 **Planned**
|
||||
- System status queries
|
||||
- Log analysis
|
||||
- Basic troubleshooting
|
||||
- Infrastructure monitoring
|
||||
|
||||
5. **The Secretary** (Scheduling & Organization) 🔜 **Planned**
|
||||
- Calendar integration
|
||||
- Task management
|
||||
- Reminder system
|
||||
- Schedule conflict detection
|
||||
|
||||
6. **The Housekeeper** (Home Automation) 🔜 **Planned**
|
||||
- Home Assistant integration
|
||||
- Device control interface
|
||||
- Status queries
|
||||
- Automation triggers
|
||||
|
||||
### Each Agent Includes
|
||||
- Specialized prompt and personality
|
||||
- Domain-specific tools
|
||||
- MCP integration points (where applicable)
|
||||
- Integration with Butler orchestration
|
||||
|
||||
### Success Criteria
|
||||
- [x] Each agent implemented as separate module
|
||||
- [x] Agents callable via tool framework
|
||||
- [x] Agents use specialized prompts
|
||||
- [x] Results integrate cleanly with Butler
|
||||
- [ ] Can invoke specialized models (e.g., Codestral for Developer)
|
||||
|
||||
### Status
|
||||
**🔶 PARTIAL** - Librarian and Biographer complete, others planned
|
||||
|
||||
### Estimated Effort
|
||||
**6-8 weeks** - Parallel development possible
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Persistence Layer - Database & Multi-Tenancy
|
||||
|
||||
**Goal**: Add persistent storage and multi-user support when needed
|
||||
|
||||
### Deliverables
|
||||
|
||||
1. **PostgreSQL Integration**
|
||||
- Docker compose configuration for PostgreSQL
|
||||
- Database schema design with tenant isolation
|
||||
- Alembic migrations setup
|
||||
- SQLAlchemy models
|
||||
|
||||
2. **Multi-Tenant Architecture**
|
||||
- Tenant identification middleware
|
||||
- Tenant-scoped database sessions
|
||||
- User authentication system (basic)
|
||||
- Per-tenant data isolation
|
||||
|
||||
3. **Core Data Models**
|
||||
- Users and tenants
|
||||
- Conversations and messages (migrate from in-memory)
|
||||
- Agent interactions log
|
||||
- System configuration and preferences
|
||||
|
||||
4. **Migration Strategy**
|
||||
- Gradual migration from in-memory to database
|
||||
- Backward compatibility during transition
|
||||
- Data export/import utilities
|
||||
|
||||
### Success Criteria
|
||||
- [ ] PostgreSQL container running
|
||||
- [ ] Multiple users can authenticate separately
|
||||
- [ ] Each user sees only their own data
|
||||
- [ ] Conversations persist across restarts
|
||||
- [ ] Database migrations work correctly
|
||||
- [ ] Tests verify tenant isolation
|
||||
|
||||
### Estimated Effort
|
||||
**3-4 weeks** - Data layer foundation
|
||||
|
||||
### Why Later?
|
||||
The core orchestration (Steward → Butler → Experts) can work entirely with in-memory state. We only need database persistence when we want conversations to survive restarts and multiple users to have isolated experiences.
|
||||
|
||||
---
|
||||
|
||||
## Phase 6: Extended Services Integration
|
||||
|
||||
**Goal**: Connect to additional supporting services
|
||||
|
||||
### Services to Integrate
|
||||
|
||||
1. **Redis (Memory & Caching)** ✅ **COMPLETE** (v1.2.0)
|
||||
- Benchmark storage (db=1)
|
||||
- Memory cache for sessions (db=2)
|
||||
- 24h TTL for session context
|
||||
- Recent entities tracking
|
||||
|
||||
2. **Qdrant (Vector Storage)** ✅ **COMPLETE** (v1.2.0)
|
||||
- Per-user memory collections
|
||||
- 768-dim nomic-embed-text vectors
|
||||
- Semantic search for recall
|
||||
- Type-based filtering
|
||||
|
||||
3. **SearxNG (Web Search)** ✅ **COMPLETE** (v0.2.0)
|
||||
- Search tool integration
|
||||
- Result processing
|
||||
- Privacy-preserving queries
|
||||
|
||||
4. **library-desk (Research API)** ✅ **COMPLETE** (v1.1.0)
|
||||
- HybridRAG search
|
||||
- Wiki management
|
||||
- Knowledge graph queries
|
||||
|
||||
### Success Criteria
|
||||
- [x] Services communicate correctly
|
||||
- [x] Tatlock can invoke web search
|
||||
- [x] Redis used for session data
|
||||
- [x] Qdrant stores user memories
|
||||
- [x] Ollama serves the base model
|
||||
|
||||
### Status
|
||||
**✅ COMPLETE** - All core services integrated
|
||||
|
||||
### Estimated Effort
|
||||
**3-4 weeks** - Infrastructure setup
|
||||
|
||||
---
|
||||
|
||||
## Phase 7: MCP (Model Context Protocol) Integration
|
||||
|
||||
**Goal**: Enable rich tool integrations via MCP
|
||||
|
||||
### Deliverables
|
||||
|
||||
1. **MCP Server Framework**
|
||||
- MCP server implementation
|
||||
- Tool registration via MCP
|
||||
- Schema validation
|
||||
- Error handling
|
||||
|
||||
2. **MCP Client in Agents**
|
||||
- PydanticAI MCP integration
|
||||
- Tool discovery from MCP servers
|
||||
- Dynamic tool loading
|
||||
- Result processing
|
||||
|
||||
3. **Initial MCP Tools**
|
||||
- File system operations
|
||||
- Database queries
|
||||
- API integrations
|
||||
- System commands
|
||||
|
||||
### Success Criteria
|
||||
- [ ] MCP server running
|
||||
- [ ] Tools exposed via MCP protocol
|
||||
- [ ] Agents can discover and use MCP tools
|
||||
- [ ] New tools addable without code changes
|
||||
- [ ] MCP tools visible in Steward recommendations
|
||||
|
||||
### Estimated Effort
|
||||
**3-4 weeks** - Standards-based integration
|
||||
|
||||
---
|
||||
|
||||
## Phase 8: Advanced Memory & Context
|
||||
|
||||
**Goal**: Implement sophisticated memory and context management
|
||||
|
||||
### Deliverables
|
||||
|
||||
1. **Long-Term Memory** ✅ **COMPLETE** (v1.2.0 - Phase F)
|
||||
- Memory service for direct key-based access
|
||||
- Qdrant vector storage for semantic recall
|
||||
- Embedding via nomic-embed-text
|
||||
- The Biographer agent for memory management
|
||||
|
||||
2. **Session Memory** ✅ **COMPLETE** (v1.2.0)
|
||||
- Redis session cache with 24h TTL
|
||||
- Recent entities tracking
|
||||
- Conversation context preservation
|
||||
- Multi-tenancy via ContextVar
|
||||
|
||||
3. **Steward Integration** ✅ **COMPLETE** (v1.2.0)
|
||||
- Memory pre-fetch during request analysis
|
||||
- Profile/preferences included in context
|
||||
- Keyword-based context determination
|
||||
|
||||
4. **Context Management** 🔜 **Future**
|
||||
- Smart context window trimming
|
||||
- Conversation branching
|
||||
- Topic tracking
|
||||
- Memory retrieval integration
|
||||
|
||||
5. **Personalization** 🔜 **Future**
|
||||
- User preference learning
|
||||
- Interaction pattern analysis
|
||||
- Adaptive responses
|
||||
- Custom agent personalities per user
|
||||
|
||||
### Success Criteria
|
||||
- [x] User facts stored in Qdrant with semantic search
|
||||
- [x] Profile and preferences accessible via memory_service
|
||||
- [x] Session context cached in Redis
|
||||
- [x] User preferences affect responses (via Steward pre-fetch)
|
||||
- [ ] Conversations automatically embedded to Qdrant
|
||||
- [ ] Memory improves over time (learning from interactions)
|
||||
|
||||
### Status
|
||||
**🔶 PARTIAL** - Core memory system complete, advanced features planned
|
||||
|
||||
### Estimated Effort
|
||||
**4-5 weeks** - AI/ML heavy (remaining work)
|
||||
|
||||
---
|
||||
|
||||
## Phase 9: Extended Household Staff
|
||||
|
||||
**Goal**: Add specialized agents for additional domains
|
||||
|
||||
### Future Agents
|
||||
|
||||
1. **The Librarian** (Knowledge Management)
|
||||
- Personal documentation indexing
|
||||
- Research assistance
|
||||
- Knowledge base queries
|
||||
- Reference management
|
||||
|
||||
2. **The Accountant** (Financial Tracking)
|
||||
- Expense tracking
|
||||
- Budget monitoring
|
||||
- Financial reports
|
||||
- Transaction categorization
|
||||
|
||||
3. **The Chef** (Meal Planning)
|
||||
- Recipe management
|
||||
- Meal planning
|
||||
- Nutrition tracking
|
||||
- Grocery lists
|
||||
|
||||
4. **Others as Needed**
|
||||
- Domain-specific as requirements emerge
|
||||
|
||||
### Success Criteria
|
||||
- [ ] Each new agent follows household pattern
|
||||
- [ ] Integrates with Steward/Butler flow
|
||||
- [ ] Has appropriate specialized tools
|
||||
- [ ] Documented in PHILOSOPHY.md updates
|
||||
|
||||
### Estimated Effort
|
||||
**Ongoing** - Add as needed
|
||||
|
||||
---
|
||||
|
||||
## Phase 10: User Experience Refinement
|
||||
|
||||
**Goal**: Polish the interaction experience
|
||||
|
||||
### Deliverables
|
||||
|
||||
1. **Personality Tuning**
|
||||
- Refine Tatlock's wit and tone
|
||||
- Consistent household character
|
||||
- Cultural references appropriate
|
||||
- Humor that doesn't annoy
|
||||
|
||||
2. **Transparency Improvements**
|
||||
- Better progress indicators
|
||||
- Clearer reasoning explanations
|
||||
- Informative wait messages
|
||||
- Error message clarity
|
||||
|
||||
3. **Performance Optimization**
|
||||
- Response time improvements
|
||||
- Model loading optimization
|
||||
- Caching strategies
|
||||
- Streaming smoothness
|
||||
|
||||
### Success Criteria
|
||||
- [ ] Users find Tatlock engaging
|
||||
- [ ] Wait times feel reasonable
|
||||
- [ ] Errors are understandable
|
||||
- [ ] System feels responsive
|
||||
|
||||
### Estimated Effort
|
||||
**Ongoing** - Continuous improvement
|
||||
|
||||
---
|
||||
|
||||
## Phase 11: Production Hardening
|
||||
|
||||
**Goal**: Make the system production-ready for homelab deployment
|
||||
|
||||
### Deliverables
|
||||
|
||||
1. **Deployment**
|
||||
- Complete docker-compose stack
|
||||
- Environment configuration
|
||||
- Backup strategies
|
||||
- Update procedures
|
||||
|
||||
2. **Monitoring**
|
||||
- Health checks
|
||||
- Performance metrics
|
||||
- Error tracking
|
||||
- Usage analytics
|
||||
|
||||
3. **Security**
|
||||
- Authentication hardening
|
||||
- Rate limiting
|
||||
- Input validation
|
||||
- Audit logging
|
||||
|
||||
4. **Documentation**
|
||||
- Installation guide
|
||||
- Configuration reference
|
||||
- Troubleshooting guide
|
||||
- Architecture documentation
|
||||
|
||||
### Success Criteria
|
||||
- [ ] One-command deployment
|
||||
- [ ] System health is monitorable
|
||||
- [ ] Secure for homelab use
|
||||
- [ ] Well documented
|
||||
|
||||
### Estimated Effort
|
||||
**3-4 weeks** - Production polish
|
||||
|
||||
---
|
||||
|
||||
## Dependencies Between Phases
|
||||
|
||||
```
|
||||
Phase 1 (Ollama + PydanticAI) ← Foundation for all AI
|
||||
↓
|
||||
Phase 2 (Steward)
|
||||
↓
|
||||
Phase 3 (Butler/Tatlock)
|
||||
↓
|
||||
Phase 4 (Expert Agents) ← Phase 7 (MCP) can enhance
|
||||
↓
|
||||
Phase 5 (Database/Multi-Tenancy) ← Can be deferred
|
||||
↓
|
||||
Phase 6 (Extended Services) → Phase 8 (Advanced Memory)
|
||||
↓
|
||||
Phase 9 (Extended Staff) → Phase 10 (UX) → Phase 11 (Production)
|
||||
```
|
||||
|
||||
**Critical Path**: Phases 1 → 2 → 3 → 4 must be sequential
|
||||
**Can Be Deferred**: Phase 5 (Database) until you need persistence
|
||||
**Parallel Opportunities**: Phase 6 and 7 can overlap; Phase 9 and 10 ongoing
|
||||
|
||||
---
|
||||
|
||||
## Overall Timeline Estimate
|
||||
|
||||
**Minimum Viable Household** (Phases 1-4): **15-20 weeks**
|
||||
- Working Steward → Butler → Expert Agents with real LLM
|
||||
- In-memory state (no persistence needed yet)
|
||||
- Core household functional
|
||||
|
||||
**With Persistence** (Phases 1-5): **18-24 weeks**
|
||||
- Add database and multi-tenancy
|
||||
- Conversations survive restarts
|
||||
- Multiple users supported
|
||||
|
||||
**Full-Featured System** (Phases 1-9): **35-45 weeks**
|
||||
- All services integrated
|
||||
- Advanced memory and context
|
||||
- Extended household staff
|
||||
|
||||
**Production-Ready** (All phases): **40-50 weeks**
|
||||
- Polished UX
|
||||
- Hardened for homelab deployment
|
||||
- Fully documented
|
||||
|
||||
*Note: Timeline assumes consistent part-time development effort*
|
||||
|
||||
---
|
||||
|
||||
## Success Metrics
|
||||
|
||||
### Technical
|
||||
- System implements PHILOSOPHY.md patterns
|
||||
- All household roles functional
|
||||
- Multi-tenant isolation verified
|
||||
- Real-time reasoning transparency working
|
||||
- MCP integration complete
|
||||
|
||||
### User Experience
|
||||
- Tatlock feels like interacting with a butler
|
||||
- Wait times are transparent and acceptable
|
||||
- Expert agents provide value in their domains
|
||||
- System is reliable and trustworthy
|
||||
|
||||
### Architecture
|
||||
- Clean separation between household roles
|
||||
- Easy to add new agents/tools
|
||||
- Model efficiency (base model stays loaded)
|
||||
- Scales to household + friends usage
|
||||
|
||||
---
|
||||
|
||||
## Risk Management
|
||||
|
||||
### High Risk Items
|
||||
1. **PydanticAI + Ollama integration complexity**
|
||||
- Mitigation: Prototype early, iterate on connection layer
|
||||
|
||||
2. **Multi-agent coordination complexity**
|
||||
- Mitigation: Start simple, add coordination gradually
|
||||
|
||||
3. **Model performance on homelab hardware**
|
||||
- Mitigation: Model selection, quantization, optimization
|
||||
|
||||
4. **Prompt engineering for personality consistency**
|
||||
- Mitigation: Extensive testing, user feedback, iteration
|
||||
|
||||
### Medium Risk Items
|
||||
- MCP protocol adoption and tooling maturity
|
||||
- Vector embedding quality for memory
|
||||
- Home automation integration variability
|
||||
- User authentication security
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Priority**: Implement The Developer agent for code assistance
|
||||
2. **Integration**: Add Home Assistant integration for The Housekeeper
|
||||
3. **Calendar**: Integrate scheduling service for The Secretary
|
||||
4. **Ongoing**: Add more household staff as needed
|
||||
|
||||
---
|
||||
|
||||
**Document Status**: Active planning document
|
||||
**Created**: 2025-12-06
|
||||
**Last Updated**: 2025-12-13
|
||||
@@ -0,0 +1,51 @@
|
||||
.PHONY: help setup run test test-unit test-integration test-contracts lint typecheck clean
|
||||
|
||||
VENV := .venv
|
||||
PYTHON := $(VENV)/bin/python
|
||||
PIP := $(VENV)/bin/pip
|
||||
PYTEST := $(VENV)/bin/pytest
|
||||
RUFF := $(VENV)/bin/ruff
|
||||
MYPY := $(VENV)/bin/mypy
|
||||
UVICORN := $(VENV)/bin/uvicorn
|
||||
|
||||
HOST := 0.0.0.0
|
||||
PORT := 8777
|
||||
|
||||
help: ## Show this help
|
||||
@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
|
||||
|
||||
setup: ## Create venv and install all dependencies
|
||||
python3 -m venv $(VENV)
|
||||
$(PIP) install --upgrade pip
|
||||
$(PIP) install -e ".[dev]"
|
||||
|
||||
run: ## Start the development server on port 8777
|
||||
@mkdir -p build/logs
|
||||
@if lsof -Pi :$(PORT) -sTCP:LISTEN -t >/dev/null 2>&1; then \
|
||||
echo "Error: Port $(PORT) is already in use"; \
|
||||
echo "Run: lsof -i :$(PORT) to see what's using it"; \
|
||||
exit 1; \
|
||||
fi
|
||||
$(UVICORN) src.main:app --reload --host $(HOST) --port $(PORT) 2>&1 | tee build/logs/server.log
|
||||
|
||||
test: ## Run unit tests (no external services needed)
|
||||
$(PYTEST) --ignore=tests/e2e --ignore=tests/integration --ignore=tests/contracts
|
||||
|
||||
test-unit: test ## Alias for test
|
||||
|
||||
test-integration: ## Run integration tests (needs Claude/Ollama)
|
||||
$(PYTEST) tests/agents/test_tatlock_agent.py -v
|
||||
|
||||
test-contracts: ## Wire-level contract tests against live service boundaries
|
||||
$(PYTEST) tests/contracts -v --no-cov
|
||||
|
||||
lint: ## Run ruff linter and formatter check
|
||||
$(RUFF) check src tests
|
||||
$(RUFF) format --check src tests
|
||||
|
||||
typecheck: ## Run mypy type checking
|
||||
$(MYPY) src
|
||||
|
||||
clean: ## Remove build artifacts, caches, and coverage reports
|
||||
rm -rf .cache build
|
||||
find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
|
||||
@@ -1,401 +0,0 @@
|
||||
# Tatlock Enhancement Plan: Bidirectional Claude Integration
|
||||
|
||||
## Executive Summary
|
||||
|
||||
Implement a **bidirectional architecture** that:
|
||||
1. **Superpowers Tatlock** by swapping Ollama→Claude backend (200k context, better reasoning, same butler personality)
|
||||
2. **Exposes Tatlock as MCP server** for Claude instances on any device (phone, browser, desktop)
|
||||
|
||||
This gives you the flexibility to use whichever AI is best/most accessible at any moment.
|
||||
|
||||
## Key Insight: Blanket Backend Swap (Simpler Than Sidecar)
|
||||
|
||||
Instead of adding a Claude "Analyst" sidecar agent, **swap the underlying model for ALL agents**:
|
||||
|
||||
```
|
||||
CURRENT: TatlockAgent → OpenAIChatModel → OllamaProvider → Ollama (mistral-nemo)
|
||||
PROPOSED: TatlockAgent → AnthropicModel → AnthropicProvider → Claude API
|
||||
↘ (fallback when offline) → OllamaProvider → Ollama
|
||||
```
|
||||
|
||||
**Why this works:**
|
||||
- PydanticAI natively supports Anthropic via `AnthropicModel` + `AnthropicProvider`
|
||||
- The same `TATLOCK_SYSTEM_PROMPT` is passed to Claude - butler personality preserved
|
||||
- Claude is **better** at following system prompts than mistral-nemo
|
||||
- 200k context for ALL queries, not just "complex" ones
|
||||
- Simpler architecture: no routing logic, no sidecar delegation
|
||||
|
||||
---
|
||||
|
||||
## Research Findings
|
||||
|
||||
### Industry Best Practices (2025-2026)
|
||||
|
||||
**MCP Protocol Updates** ([MCP Spec Updates June 2025](https://auth0.com/blog/mcp-specs-update-all-about-auth/)):
|
||||
- Streamable HTTP replaced SSE (March 2025) - better for cloud deployment
|
||||
- OAuth 2.0 required for remote servers - MCP servers are OAuth Resource Servers
|
||||
- Tool Output Schemas now available - better structured data handling
|
||||
- MCP Registry launched (Sept 2025) - community server discovery
|
||||
|
||||
**Community Patterns** ([Claude Code Router](https://github.com/musistudio/claude-code-router)):
|
||||
- Task-based routing is becoming standard: route simple→local, complex→cloud
|
||||
- Translation proxies bridge Anthropic Messages API ↔ OpenAI format
|
||||
- Cost savings of up to 98% reported with smart routing
|
||||
|
||||
**Home Automation MCP** ([ha-mcp](https://github.com/homeassistant-ai/ha-mcp)):
|
||||
- Production-ready MCP servers exist for Home Assistant
|
||||
- Support Claude Code, Gemini CLI, Open WebUI, VSCode, Cursor
|
||||
- Pattern: expose local tools securely to remote AI clients
|
||||
|
||||
**Remote MCP Access** ([mcp-remote](https://www.npmjs.com/package/mcp-remote)):
|
||||
- Bridge local MCP servers to Claude Desktop/Browser via proxy
|
||||
- Supports authentication headers for security
|
||||
- Works with ngrok/Cloudflare Tunnel for HTTPS
|
||||
|
||||
---
|
||||
|
||||
## Recommended Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ BIDIRECTIONAL TATLOCK-CLAUDE ARCHITECTURE │
|
||||
├─────────────────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ╔═══════════════════════════════════════════════════════════════════════════════╗ │
|
||||
│ ║ SCENARIO A: Using Tatlock (Open WebUI, local apps) ║ │
|
||||
│ ║ ───────────────────────────────────────────────── ║ │
|
||||
│ ║ ║ │
|
||||
│ ║ Request → Steward → Tatlock → Tools + Expert Delegation ║ │
|
||||
│ ║ │ ║ │
|
||||
│ ║ ├─→ Librarian (Claude) → research, wiki, RAG ║ │
|
||||
│ ║ ├─→ Biographer (Claude) → memory, preferences ║ │
|
||||
│ ║ ├─→ Housekeeper (Claude) → home automation ║ │
|
||||
│ ║ └─→ All powered by Claude with Ollama fallback ║ │
|
||||
│ ║ ║ │
|
||||
│ ║ Butler personality preserved, 200k context for all queries ║ │
|
||||
│ ╚═══════════════════════════════════════════════════════════════════════════════╝ │
|
||||
│ │
|
||||
│ ╔═══════════════════════════════════════════════════════════════════════════════╗ │
|
||||
│ ║ SCENARIO B: Using Claude.ai / Claude Desktop / Phone ║ │
|
||||
│ ║ ──────────────────────────────────────────────────── ║ │
|
||||
│ ║ ║ │
|
||||
│ ║ Claude ──[MCP over HTTPS]──► Tatlock MCP Server → Household Tools ║ │
|
||||
│ ║ │ ║ │
|
||||
│ ║ ├─→ calculator, datetime ║ │
|
||||
│ ║ ├─→ web_search, wiki_search ║ │
|
||||
│ ║ ├─→ hybrid_search (RAG) ║ │
|
||||
│ ║ ├─→ memory_recall, store_insight ║ │
|
||||
│ ║ └─→ home_control (lights, climate) ║ │
|
||||
│ ║ ║ │
|
||||
│ ║ Full 200k context, your local tools accessible from anywhere ║ │
|
||||
│ ╚═══════════════════════════════════════════════════════════════════════════════╝ │
|
||||
│ │
|
||||
│ ╔═══════════════════════════════════════════════════════════════════════════════╗ │
|
||||
│ ║ SCENARIO C: Offline (internet down) ║ │
|
||||
│ ║ ────────────────────────────────── ║ │
|
||||
│ ║ ║ │
|
||||
│ ║ Tatlock operates fully locally with Ollama ║ │
|
||||
│ ║ • All tools work (except web search) ║ │
|
||||
│ ║ • Graceful degradation with same butler personality ║ │
|
||||
│ ╚═══════════════════════════════════════════════════════════════════════════════╝ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Plan
|
||||
|
||||
### Phase 1: Blanket Backend Swap (Claude for All Agents)
|
||||
|
||||
Replace Ollama with Claude as the default backend for all PydanticAI agents, with automatic offline fallback.
|
||||
|
||||
**New Files:**
|
||||
```
|
||||
src/anthropic/
|
||||
├── __init__.py
|
||||
├── provider.py # Claude provider with health check
|
||||
└── model_selector.py # Chooses Claude or Ollama based on availability
|
||||
```
|
||||
|
||||
**Key Implementation (`src/anthropic/provider.py`):**
|
||||
```python
|
||||
from pydantic_ai.models.anthropic import AnthropicModel
|
||||
from pydantic_ai.providers.anthropic import AnthropicProvider
|
||||
from pydantic_ai.models.openai import OpenAIChatModel
|
||||
from src.ollama.provider import get_ollama_provider
|
||||
from src.core.config import config
|
||||
|
||||
_anthropic_available: bool | None = None
|
||||
|
||||
async def check_anthropic_health() -> bool:
|
||||
"""Check if Anthropic API is reachable."""
|
||||
global _anthropic_available
|
||||
try:
|
||||
from anthropic import AsyncAnthropic
|
||||
client = AsyncAnthropic(api_key=config.ANTHROPIC_API_KEY)
|
||||
await client.messages.create(
|
||||
model=config.ANTHROPIC_MODEL,
|
||||
max_tokens=1,
|
||||
messages=[{"role": "user", "content": "hi"}]
|
||||
)
|
||||
_anthropic_available = True
|
||||
except Exception:
|
||||
_anthropic_available = False
|
||||
return _anthropic_available
|
||||
|
||||
def get_model(prefer_cloud: bool = True):
|
||||
"""Get the best available model. Returns Claude if available, otherwise Ollama."""
|
||||
if prefer_cloud and config.ANTHROPIC_API_KEY and _anthropic_available:
|
||||
provider = AnthropicProvider(api_key=config.ANTHROPIC_API_KEY)
|
||||
return AnthropicModel(
|
||||
model_name=config.ANTHROPIC_MODEL,
|
||||
provider=provider,
|
||||
)
|
||||
else:
|
||||
return OpenAIChatModel(
|
||||
model_name=config.OLLAMA_DEFAULT_MODEL,
|
||||
provider=get_ollama_provider()
|
||||
)
|
||||
```
|
||||
|
||||
**Modify TatlockAgent (`src/agents/tatlock.py`):**
|
||||
```python
|
||||
def _ensure_agent(self):
|
||||
if self._agent is not None:
|
||||
return
|
||||
|
||||
from src.anthropic.model_selector import get_model
|
||||
|
||||
model = get_model(prefer_cloud=True)
|
||||
|
||||
self._agent = Agent(
|
||||
model,
|
||||
system_prompt=TATLOCK_SYSTEM_PROMPT, # Same butler personality!
|
||||
)
|
||||
self._register_tools()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: MCP Server (Expose Tools to Claude)
|
||||
|
||||
Create an MCP server that exposes Tatlock's household tools to external Claude instances.
|
||||
|
||||
**New Files:**
|
||||
```
|
||||
src/mcp/
|
||||
├── __init__.py
|
||||
├── server.py # MCP server using mcp Python SDK
|
||||
├── tool_adapters.py # Convert PydanticAI tools → MCP schemas
|
||||
├── auth.py # API key authentication
|
||||
└── transport.py # Streamable HTTP transport
|
||||
```
|
||||
|
||||
**Docker Stack Addition (`stacks/agents.yml`):**
|
||||
```yaml
|
||||
tatlock-mcp:
|
||||
image: git.schweitz.internal/jpmschweitzer/tatlock:latest
|
||||
command: ["python", "-m", "src.mcp.server"]
|
||||
ports:
|
||||
- "8002:8002"
|
||||
environment:
|
||||
- MCP_AUTH_TOKEN=${MCP_AUTH_TOKEN}
|
||||
networks:
|
||||
- docker-dataplane
|
||||
```
|
||||
|
||||
**Claude Desktop Configuration:**
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"tatlock": {
|
||||
"command": "npx",
|
||||
"args": ["mcp-remote", "https://mcp.schweitz.net/sse", "--header", "Authorization: Bearer ${MCP_AUTH_TOKEN}"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Files to Modify
|
||||
|
||||
### Phase 1 - Backend Swap
|
||||
|
||||
**New Files:**
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `src/anthropic/__init__.py` | Package init |
|
||||
| `src/anthropic/provider.py` | Claude provider with health check |
|
||||
| `src/anthropic/model_selector.py` | Choose Claude or Ollama based on availability |
|
||||
|
||||
**Modified Files:**
|
||||
| File | Changes |
|
||||
|------|---------|
|
||||
| `src/core/config.py` | Add `ANTHROPIC_API_KEY`, `ANTHROPIC_MODEL`, `PREFER_CLOUD_BACKEND` |
|
||||
| `src/agents/tatlock.py` | Use `get_model()` instead of hardcoded Ollama |
|
||||
| `src/agents/librarian/agent.py` | Use `get_model()` instead of hardcoded Ollama |
|
||||
| `src/agents/biographer/agent.py` | Use `get_model()` instead of hardcoded Ollama |
|
||||
| `src/agents/steward/agent.py` | Convert to PydanticAI or add Anthropic API support |
|
||||
| `src/core/startup.py` | Add Anthropic health check on startup |
|
||||
| `requirements.txt` | Add `anthropic>=0.40.0` |
|
||||
| `.env.example` | Document new environment variables |
|
||||
|
||||
### Phase 2 - MCP Server
|
||||
|
||||
**New Files:**
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `src/mcp/__init__.py` | Package init |
|
||||
| `src/mcp/server.py` | MCP server implementation |
|
||||
| `src/mcp/tool_adapters.py` | PydanticAI → MCP schema conversion |
|
||||
| `src/mcp/auth.py` | Token-based authentication |
|
||||
|
||||
---
|
||||
|
||||
## Cost Analysis
|
||||
|
||||
- **Claude API**: $5-30/month (10-50 calls/day, ~2k input + 1k output tokens/call)
|
||||
- **MCP via Claude Pro**: Included in subscription
|
||||
- **Total**: ~$10-80/month for full bidirectional integration
|
||||
|
||||
---
|
||||
|
||||
## Verification Plan
|
||||
|
||||
### Phase 1 Testing
|
||||
```bash
|
||||
# 1. Run with Claude backend
|
||||
ANTHROPIC_API_KEY=your-key docker-compose up -d tatlock
|
||||
|
||||
# 2. Verify Claude is being used
|
||||
docker logs tatlock 2>&1 | grep -i "anthropic\|claude"
|
||||
|
||||
# 3. Test butler personality
|
||||
curl -X POST http://tatlock.schweitz.internal:8000/v1/responses \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"model": "Tatlock", "input": "Hello, who are you?"}'
|
||||
|
||||
# 4. Test offline fallback
|
||||
ANTHROPIC_API_KEY="" docker-compose up -d tatlock
|
||||
docker logs tatlock 2>&1 | grep -i "ollama\|fallback"
|
||||
```
|
||||
|
||||
### Phase 2 Testing
|
||||
```bash
|
||||
# 1. Start MCP server
|
||||
docker-compose up -d tatlock-mcp
|
||||
|
||||
# 2. Test MCP endpoint
|
||||
curl -X POST https://mcp.schweitz.net/tools/list \
|
||||
-H "Authorization: Bearer $MCP_AUTH_TOKEN"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Priority
|
||||
|
||||
1. **Phase 1: Backend Swap** (~1 week)
|
||||
- Immediate value: 200k context for ALL queries
|
||||
- Low risk: provider abstraction, graceful offline fallback
|
||||
|
||||
2. **Phase 2: MCP Server** (~2-3 weeks)
|
||||
- Enables cross-device access
|
||||
- Bidirectional: Tatlock superpowered by Claude AND accessible to Claude
|
||||
|
||||
---
|
||||
|
||||
## Future Phases (Optional)
|
||||
|
||||
- **Phase 3: LiteLLM Gateway** - Unified endpoint for all models, config-driven routing
|
||||
- **Phase 4: Multi-Provider** - Add OpenAI, Vertex AI, etc.
|
||||
- **Phase 5: Smart Routing** - Context-aware model selection, cost ceiling enforcement
|
||||
|
||||
---
|
||||
|
||||
## Offline Behavior
|
||||
|
||||
| Scenario | Behavior |
|
||||
|----------|----------|
|
||||
| No API key | Use Ollama exclusively |
|
||||
| API unreachable | Use Ollama, log warning |
|
||||
| API rate limited | Fallback to Ollama |
|
||||
|
||||
| Aspect | Claude | Ollama |
|
||||
|--------|--------|--------|
|
||||
| Context | 200k tokens | ~8k tokens |
|
||||
| Latency | 1-3s (network) | 0.5-1s (local) |
|
||||
| Personality | Preserved | Preserved |
|
||||
| Tools | All work | All work |
|
||||
| Cost | API charges | Free |
|
||||
|
||||
---
|
||||
|
||||
## Implementation Status
|
||||
|
||||
### Phase 1: Backend Swap - CODE COMPLETE (awaiting API access)
|
||||
|
||||
- [x] Add Anthropic config settings to `src/core/config.py`
|
||||
- [x] Add `pydantic-ai-slim[openai,anthropic]` to requirements.txt
|
||||
- [x] Create `src/anthropic/` module (model_selector.py)
|
||||
- [x] Add Claude health check to startup.py
|
||||
- [x] Refactor all PydanticAI agents to use `get_model()`
|
||||
- [x] Librarian
|
||||
- [x] Biographer
|
||||
- [x] Housekeeper
|
||||
- [x] Tatlock (6 locations)
|
||||
- [x] Add Claude API path to Steward agent (direct API calls)
|
||||
- [x] Update `.env.example` with new variables
|
||||
- [x] Test Ollama fallback (working)
|
||||
- [ ] Test with Claude API key (blocked: no API access currently)
|
||||
|
||||
**Note:** Implementation complete. Currently runs in Ollama-only mode. Will automatically use Claude when `ANTHROPIC_API_KEY` is configured.
|
||||
|
||||
### Phase 2: MCP Server - NOT STARTED
|
||||
|
||||
- [ ] Create `src/mcp/` module
|
||||
- [ ] Tool adapters (PydanticAI → MCP schema)
|
||||
- [ ] Authentication middleware
|
||||
- [ ] Streamable HTTP transport
|
||||
- [ ] Docker stack configuration
|
||||
|
||||
---
|
||||
|
||||
## Related Repository Handovers
|
||||
|
||||
Handover documents created in each repo: `PROJECT_CLAUDIFICATION_HANDOVER.md`
|
||||
|
||||
### library-desk - HANDOVER CREATED
|
||||
|
||||
- [x] Write handover document
|
||||
- [ ] Review HybridRAG response size limits
|
||||
- [ ] Review smart_create endpoint for Claude optimization
|
||||
- [ ] Evaluate response formats for LLM consumption
|
||||
|
||||
### core-api - HANDOVER CREATED
|
||||
|
||||
- [x] Write handover document
|
||||
- [ ] Review list_devices response format
|
||||
- [ ] Review error messages for LLM consumption
|
||||
- [ ] Evaluate rate limiting for faster Claude processing
|
||||
|
||||
### portainer-core - HANDOVER CREATED (blocking for production)
|
||||
|
||||
- [x] Write handover document
|
||||
- [ ] Update stack with new environment variables
|
||||
- [ ] Configure secrets management for API key
|
||||
- [ ] Update CONTAINERS.md documentation
|
||||
|
||||
### webber - HANDOVER CREATED
|
||||
|
||||
- [x] Write handover document
|
||||
- [ ] Review content truncation limits
|
||||
- [ ] Evaluate extraction quality for LLM consumption
|
||||
|
||||
### tatlock-ui - HANDOVER CREATED
|
||||
|
||||
- [x] Write handover document
|
||||
- [ ] Test streaming responses with Claude backend
|
||||
- [ ] Test conversation history with larger context
|
||||
- [ ] Verify tool call display and reasoning rendering
|
||||
@@ -1,6 +1,6 @@
|
||||
# Tatlock - Your Homelab Butler
|
||||
|
||||
> **📖 For the complete system vision and architectural philosophy, see [PHILOSOPHY.md](PHILOSOPHY.md)**
|
||||
> **📖 For the complete system vision and architectural philosophy, see [docs/philosophy.md](docs/philosophy.md)**
|
||||
|
||||
A privacy-first, offline-capable personal assistant system that coordinates specialized AI agents to help with research, development, home automation, and daily organization.
|
||||
|
||||
@@ -58,7 +58,7 @@ A privacy-first, offline-capable personal assistant system that coordinates spec
|
||||
- Error triggers for testing (rate_limit, context_overflow)
|
||||
|
||||
- **Tatlock**: Real PydanticAI agent with butler personality
|
||||
- **LLM Backend**: Ollama (mistral-nemo:latest by default)
|
||||
- **LLM Backend**: Ollama (gemma4:e2b by default, local-first) with optional Claude fallback
|
||||
- **Personality**: Witty British butler, research-oriented
|
||||
- **Core Tools**:
|
||||
- **Calculator**: Safe mathematical expression evaluation
|
||||
@@ -74,7 +74,7 @@ A privacy-first, offline-capable personal assistant system that coordinates spec
|
||||
|
||||
- Python 3.12+ (Python 3.12.11 recommended)
|
||||
- **External Services** (must be running separately):
|
||||
- **Ollama**: LLM inference (mistral-nemo:latest, nomic-embed-text)
|
||||
- **Ollama**: LLM inference (gemma4:e2b, nomic-embed-text)
|
||||
- **Redis**: Caching and session memory
|
||||
- **Qdrant**: Vector storage for The Biographer's memory
|
||||
- **SearXNG**: Web search (optional)
|
||||
@@ -89,12 +89,8 @@ A privacy-first, offline-capable personal assistant system that coordinates spec
|
||||
git clone https://git.schweitz.net/jpmschweitzer/tatlock.git
|
||||
cd tatlock
|
||||
|
||||
# Create virtual environment
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate # Windows: .venv\Scripts\activate
|
||||
|
||||
# Install dependencies
|
||||
pip install -r requirements.txt
|
||||
make setup
|
||||
```
|
||||
|
||||
### Run the Server
|
||||
@@ -268,7 +264,10 @@ Interactive documentation available at:
|
||||
pytest
|
||||
|
||||
# Run unit tests only (no external services needed)
|
||||
pytest --ignore=tests/e2e --ignore=tests/integration
|
||||
pytest --ignore=tests/e2e --ignore=tests/integration --ignore=tests/contracts
|
||||
|
||||
# Wire-level contract tests against live service boundaries
|
||||
make test-contracts
|
||||
|
||||
# Run with coverage
|
||||
pytest --cov=src --cov-report=term-missing
|
||||
@@ -307,12 +306,17 @@ Create a `.env` file for custom configuration:
|
||||
API_HOST=0.0.0.0
|
||||
API_PORT=8000
|
||||
|
||||
# Ollama Configuration
|
||||
# Ollama Configuration (primary backend)
|
||||
OLLAMA_HOST=http://localhost:11434
|
||||
OLLAMA_DEFAULT_MODEL=mistral-nemo:latest
|
||||
OLLAMA_DEFAULT_MODEL=gemma4:e2b
|
||||
OLLAMA_EMBEDDING_MODEL=nomic-embed-text
|
||||
OLLAMA_TIMEOUT=120
|
||||
|
||||
# Claude fallback (optional; used when Ollama is down or PREFER_CLOUD_BACKEND=true)
|
||||
# ANTHROPIC_API_KEY=sk-ant-api03-your-key-here
|
||||
ANTHROPIC_MODEL=claude-sonnet-5
|
||||
PREFER_CLOUD_BACKEND=false
|
||||
|
||||
# Redis Configuration
|
||||
REDIS_HOST=localhost
|
||||
REDIS_PORT=6379
|
||||
@@ -380,9 +384,8 @@ tatlock/
|
||||
│ │ ├── steward/ # The Steward - request analysis
|
||||
│ │ ├── tatlock_core/ # Core butler tools
|
||||
│ │ ├── tatlock.py # Tatlock PydanticAI agent
|
||||
│ │ ├── coordination.py # Multi-agent coordination
|
||||
│ │ ├── delegation.py # Expert delegation wrappers
|
||||
│ │ └── protocol.py # Agent communication protocol
|
||||
│ │ └── protocol.py # Agent error protocol
|
||||
│ ├── responses/ # Responses API (primary endpoint)
|
||||
│ ├── chat/ # Chat Completions wrapper
|
||||
│ ├── models/ # Models listing
|
||||
@@ -396,8 +399,7 @@ tatlock/
|
||||
│ │ └── multi_tenancy.py # User isolation utilities
|
||||
│ └── main.py # Application entry point
|
||||
├── tests/ # Comprehensive test suite
|
||||
├── PHILOSOPHY.md # System vision and architecture
|
||||
├── IMPLEMENTATION_ROADMAP.md # Development phases
|
||||
├── docs/ # Project documentation
|
||||
├── CHANGELOG.md # Version history
|
||||
└── README.md # This file
|
||||
```
|
||||
@@ -416,8 +418,8 @@ For LLM agent development guidelines and architectural decisions, see [AGENTS.md
|
||||
|
||||
## Documentation
|
||||
|
||||
- **System Philosophy**: [PHILOSOPHY.md](PHILOSOPHY.md) - Vision, goals, and architectural patterns
|
||||
- **User Guide**: This file - Installation, usage, and examples
|
||||
- **System Philosophy**: [docs/philosophy.md](docs/philosophy.md) - Vision, goals, and architectural patterns
|
||||
- **Development Roadmap**: [docs/roadmap.md](docs/roadmap.md) - Open work and planned phases
|
||||
- **Developer Guidelines**: [AGENTS.md](AGENTS.md) - LLM agent development patterns
|
||||
- **Version History**: [CHANGELOG.md](CHANGELOG.md) - Changes and releases
|
||||
|
||||
@@ -432,8 +434,8 @@ For LLM agent development guidelines and architectural decisions, see [AGENTS.md
|
||||
|
||||
## Version
|
||||
|
||||
Current version: **1.3.2** - Biographer tool type hints fix
|
||||
Current version: see [CHANGELOG.md](CHANGELOG.md)
|
||||
|
||||
---
|
||||
|
||||
**Note**: Tatlock is a production-ready homelab butler. All household staff use PydanticAI with Ollama for local LLM inference.
|
||||
**Note**: Tatlock is a production-ready homelab butler. All household staff use PydanticAI with local Ollama inference (gemma4), with an optional Claude cloud fallback.
|
||||
|
||||
@@ -0,0 +1,100 @@
|
||||
# Claude Integration Plan
|
||||
|
||||
## Overview
|
||||
|
||||
Tatlock uses a bidirectional Claude architecture:
|
||||
- **Scenario A**: Tatlock powered by Claude backend (with Ollama fallback) — **COMPLETE**, then **rolled back to local-first**: Ollama/gemma4 is primary, Claude is retained as fallback (`PREFER_CLOUD_BACKEND=false`)
|
||||
- **Scenario B**: Tatlock exposed as MCP server for external Claude instances — **OPEN**
|
||||
- **Scenario C**: Offline operation via Ollama — **COMPLETE**
|
||||
|
||||
---
|
||||
|
||||
## MCP Server (Expose Tools to Claude) — NOT STARTED
|
||||
|
||||
Create an MCP server that exposes Tatlock's household tools to external Claude instances.
|
||||
|
||||
### New Files
|
||||
|
||||
```
|
||||
src/mcp/
|
||||
├── __init__.py
|
||||
├── server.py # MCP server using mcp Python SDK
|
||||
├── tool_adapters.py # Convert PydanticAI tools → MCP schemas
|
||||
├── auth.py # API key authentication
|
||||
└── transport.py # Streamable HTTP transport
|
||||
```
|
||||
|
||||
### Docker Stack Addition
|
||||
|
||||
```yaml
|
||||
tatlock-mcp:
|
||||
image: git.schweitz.net/jpmschweitzer/tatlock:latest
|
||||
command: ["python", "-m", "src.mcp.server"]
|
||||
ports:
|
||||
- "8002:8002"
|
||||
environment:
|
||||
- MCP_AUTH_TOKEN=${MCP_AUTH_TOKEN}
|
||||
networks:
|
||||
- docker-dataplane
|
||||
```
|
||||
|
||||
### Claude Desktop Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"tatlock": {
|
||||
"command": "npx",
|
||||
"args": ["mcp-remote", "https://mcp.schweitz.net/sse", "--header", "Authorization: Bearer ${MCP_AUTH_TOKEN}"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Checklist
|
||||
|
||||
- [ ] Create `src/mcp/` module
|
||||
- [ ] Tool adapters (PydanticAI → MCP schema)
|
||||
- [ ] Authentication middleware
|
||||
- [ ] Streamable HTTP transport
|
||||
- [ ] Docker stack configuration
|
||||
|
||||
---
|
||||
|
||||
## Future Phases
|
||||
|
||||
- **LiteLLM Gateway** — Unified endpoint for all models, config-driven routing
|
||||
- **Multi-Provider** — Add OpenAI, Vertex AI, etc.
|
||||
- **Smart Routing** — Context-aware model selection, cost ceiling enforcement
|
||||
|
||||
---
|
||||
|
||||
## Offline Behavior
|
||||
|
||||
| Scenario | Behavior |
|
||||
|----------|----------|
|
||||
| No API key | Use Ollama exclusively |
|
||||
| API unreachable | Use Ollama, log warning |
|
||||
| API rate limited | Fallback to Ollama |
|
||||
|
||||
| Aspect | Claude | Ollama |
|
||||
|--------|--------|--------|
|
||||
| Context | 200k tokens | ~8k tokens |
|
||||
| Latency | 1-3s (network) | 0.5-1s (local) |
|
||||
| Personality | Preserved | Preserved |
|
||||
| Tools | All work | All work |
|
||||
| Cost | API charges | Free |
|
||||
|
||||
---
|
||||
|
||||
## Related Repo Handovers
|
||||
|
||||
Handover documents created in each repo: `PROJECT_CLAUDIFICATION_HANDOVER.md`
|
||||
|
||||
### Open Items
|
||||
|
||||
- **library-desk**: Review HybridRAG response size limits, smart_create endpoint, response formats
|
||||
- **core-api**: Review list_devices response format, error messages, rate limiting
|
||||
- **portainer-core**: Update stack with new env vars, configure secrets, update CONTAINERS.md
|
||||
- **webber**: Review content truncation limits, extraction quality
|
||||
- **tatlock-ui**: Test streaming with Claude backend, conversation history, tool call display
|
||||
+208
@@ -0,0 +1,208 @@
|
||||
# Tatlock Implementation Roadmap
|
||||
|
||||
> **Reference**: See [philosophy.md](philosophy.md) for the target architecture and vision
|
||||
|
||||
This document tracks open/planned work. Completed phases have been removed.
|
||||
|
||||
## Current State (v2.0.5)
|
||||
|
||||
**What we have**:
|
||||
- OpenAI-compatible API (Responses API + Chat Completions)
|
||||
- Two-tier architecture (Steward → Tatlock)
|
||||
- Household staff: Tatlock (Butler), Steward, Librarian, Biographer
|
||||
- Core tools: Calculator, Date/Time, Web search (SearXNG)
|
||||
- Memory system: Qdrant (vector), Redis (session cache), multi-tenancy via ContextVar
|
||||
- Dual backend: Ollama/gemma4 (primary) + Claude (fallback)
|
||||
- 439 tests with good coverage
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Expert Household Staff — Remaining Agents
|
||||
|
||||
**Goal**: Implement remaining domain-specific expert agents
|
||||
|
||||
### Planned Agents
|
||||
|
||||
1. **The Developer** (Software Development)
|
||||
- Code generation assistance
|
||||
- Debugging support
|
||||
- Documentation generation
|
||||
- Architecture guidance
|
||||
|
||||
2. **The Handyman** (System Maintenance)
|
||||
- System status queries
|
||||
- Log analysis
|
||||
- Basic troubleshooting
|
||||
- Infrastructure monitoring
|
||||
|
||||
3. **The Secretary** (Scheduling & Organization)
|
||||
- Calendar integration
|
||||
- Task management
|
||||
- Reminder system
|
||||
- Schedule conflict detection
|
||||
|
||||
4. **The Housekeeper** (Home Automation)
|
||||
- Home Assistant integration
|
||||
- Device control interface
|
||||
- Status queries
|
||||
- Automation triggers
|
||||
|
||||
### Each Agent Includes
|
||||
- Specialized prompt and personality
|
||||
- Domain-specific tools
|
||||
- MCP integration points (where applicable)
|
||||
- Integration with Butler orchestration
|
||||
|
||||
### Success Criteria
|
||||
- [ ] Each agent implemented as separate module
|
||||
- [ ] Agents callable via tool framework
|
||||
- [ ] Can invoke specialized models (e.g., Codestral for Developer)
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Persistence Layer — Database & Multi-Tenancy
|
||||
|
||||
**Goal**: Add persistent storage and multi-user support
|
||||
|
||||
### Deliverables
|
||||
|
||||
1. **PostgreSQL Integration**
|
||||
- Docker compose configuration
|
||||
- Database schema with tenant isolation
|
||||
- Alembic migrations
|
||||
- SQLAlchemy models
|
||||
|
||||
2. **Multi-Tenant Architecture**
|
||||
- Tenant identification middleware
|
||||
- Tenant-scoped database sessions
|
||||
- User authentication system
|
||||
- Per-tenant data isolation
|
||||
|
||||
3. **Core Data Models**
|
||||
- Users and tenants
|
||||
- Conversations and messages (migrate from in-memory)
|
||||
- Agent interactions log
|
||||
- System configuration and preferences
|
||||
|
||||
### Success Criteria
|
||||
- [ ] PostgreSQL container running
|
||||
- [ ] Multiple users authenticate separately
|
||||
- [ ] Each user sees only their own data
|
||||
- [ ] Conversations persist across restarts
|
||||
- [ ] Database migrations work correctly
|
||||
|
||||
---
|
||||
|
||||
## Phase 7: MCP (Model Context Protocol) Integration
|
||||
|
||||
**Goal**: Enable rich tool integrations via MCP
|
||||
|
||||
See also [claude-integration.md](claude-integration.md) for MCP server implementation details.
|
||||
|
||||
### Deliverables
|
||||
|
||||
1. **MCP Server Framework**
|
||||
- MCP server implementation
|
||||
- Tool registration via MCP
|
||||
- Schema validation
|
||||
- Error handling
|
||||
|
||||
2. **MCP Client in Agents**
|
||||
- PydanticAI MCP integration
|
||||
- Tool discovery from MCP servers
|
||||
- Dynamic tool loading
|
||||
|
||||
3. **Initial MCP Tools**
|
||||
- File system operations
|
||||
- Database queries
|
||||
- API integrations
|
||||
- System commands
|
||||
|
||||
### Success Criteria
|
||||
- [ ] MCP server running
|
||||
- [ ] Tools exposed via MCP protocol
|
||||
- [ ] Agents can discover and use MCP tools
|
||||
- [ ] New tools addable without code changes
|
||||
- [ ] MCP tools visible in Steward recommendations
|
||||
|
||||
---
|
||||
|
||||
## Phase 8: Advanced Memory & Context — Remaining Work
|
||||
|
||||
**Goal**: Implement sophisticated context management and personalization
|
||||
|
||||
### Open Deliverables
|
||||
|
||||
1. **Context Management**
|
||||
- Smart context window trimming
|
||||
- Conversation branching
|
||||
- Topic tracking
|
||||
|
||||
2. **Personalization**
|
||||
- User preference learning
|
||||
- Interaction pattern analysis
|
||||
- Adaptive responses
|
||||
- Custom agent personalities per user
|
||||
|
||||
### Success Criteria
|
||||
- [ ] Conversations automatically embedded to Qdrant
|
||||
- [ ] Memory improves over time (learning from interactions)
|
||||
|
||||
---
|
||||
|
||||
## Phase 9: Extended Household Staff
|
||||
|
||||
**Goal**: Add specialized agents for additional domains
|
||||
|
||||
### Future Agents
|
||||
- **The Accountant** — Expense tracking, budgets, financial reports
|
||||
- **The Chef** — Meal planning, recipes, nutrition tracking
|
||||
- Others as needs emerge
|
||||
|
||||
---
|
||||
|
||||
## Phase 10: User Experience Refinement
|
||||
|
||||
**Goal**: Polish the interaction experience
|
||||
|
||||
- Personality tuning and consistency
|
||||
- Better progress indicators
|
||||
- Response time improvements
|
||||
- Streaming smoothness
|
||||
|
||||
---
|
||||
|
||||
## Phase 11: Production Hardening
|
||||
|
||||
**Goal**: Make the system production-ready for homelab deployment
|
||||
|
||||
- Complete docker-compose stack
|
||||
- Health checks and monitoring
|
||||
- Authentication hardening and rate limiting
|
||||
- Installation and troubleshooting documentation
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
```
|
||||
Phase 4 (Remaining Agents)
|
||||
↓
|
||||
Phase 5 (Database/Multi-Tenancy) ← Can be deferred
|
||||
↓
|
||||
Phase 7 (MCP) → Phase 8 (Advanced Memory)
|
||||
↓
|
||||
Phase 9 (Extended Staff) → Phase 10 (UX) → Phase 11 (Production)
|
||||
```
|
||||
|
||||
**Can Be Deferred**: Phase 5 until you need persistence
|
||||
**Parallel Opportunities**: Phases 7 and 8 can overlap; 9 and 10 ongoing
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. Implement The Developer agent for code assistance
|
||||
2. Add Home Assistant integration for The Housekeeper
|
||||
3. Integrate scheduling service for The Secretary
|
||||
4. MCP server for external Claude access
|
||||
@@ -0,0 +1,110 @@
|
||||
# Steward Routing & Thinking — Findings
|
||||
|
||||
**Outcome: no change shipped.** The Steward stays on `gemma4:e2b` with model
|
||||
thinking left at its default (on). Every alternative was measured and every one
|
||||
loses. This document exists so the experiment is not repeated on the same
|
||||
premise.
|
||||
|
||||
Run 2026-08-08 with `scripts/benchmark_routing.py` and
|
||||
`scripts/fixtures/routing_fixtures.py` (40 labelled queries, one repeat per
|
||||
cell, temperature 0.3 as production sends).
|
||||
|
||||
---
|
||||
|
||||
## The premise was wrong
|
||||
|
||||
The experiment was designed around an observation that the Steward pays ~300
|
||||
tokens per turn for reasoning that is generated and thrown away: it calls
|
||||
`/api/generate`, gemma4 reasons by default, and **no `thinking` field comes back
|
||||
in the response**. Disabling thinking therefore looked close to free.
|
||||
|
||||
It is not. The reasoning is not discarded — it is emitted inline in `response`,
|
||||
and it is what produces a correct `DELEGATE:` line. Those tokens are the work,
|
||||
not waste. Suppressing them costs 12.5 points of routing accuracy.
|
||||
|
||||
## Results
|
||||
|
||||
| config | exact | under | over | tokens | latency | resident | predicted | co-resident with nomic |
|
||||
|---|---|---|---|---|---|---|---|---|
|
||||
| **e2b, thinking** *(production)* | **97.5%** | 2.5% | 0% | 361 | 5179 ms | 1778 MB | 7.8 GiB | yes |
|
||||
| e2b, `think: false` | 85.0% | 12.5% | 5.0% | 48 | 1435 ms | 1778 MB | 7.8 GiB | yes |
|
||||
| e4b, thinking | 100% | 0% | 0% | 192 | 4726 ms | 3089 MB | 10.6 GiB | **no** |
|
||||
| e4b, `think: false` | 97.5% | 2.5% | 0% | 52 | 2269 ms | 3089 MB | 10.6 GiB | **no** |
|
||||
|
||||
`think: true` was also measured and landed within one fixture of the default on
|
||||
both models, so production's implicit thinking is the same thing as asking for
|
||||
it explicitly. Format compliance was 100% in every cell — a `DELEGATE:` line is
|
||||
always emitted.
|
||||
|
||||
With 40 fixtures and one repeat, each result is worth 2.5 points, so the
|
||||
97.5-vs-100 gaps are single fixtures and inside the noise. The latency and token
|
||||
medians (40 calls each) and the e2b `think: false` degradation (6 failures with a
|
||||
consistent mechanism) are the parts worth trusting.
|
||||
|
||||
## Why each alternative loses
|
||||
|
||||
**`think: false` on e2b** — 85% exact, and the failures are not random. All three
|
||||
multi-capability fixtures under-route, each missing a second capability. Without
|
||||
reasoning the model names one capability and stops decomposing. It is not
|
||||
degraded across the board; it specifically stops handling compound requests,
|
||||
which is where a user would most notice the Butler quietly doing half the job.
|
||||
|
||||
**e4b, either setting** — disqualified by memory, not by quality. Ollama predicts
|
||||
**10.6 GiB** for it at 16k context. Maximum available on this card is ~7.9 GiB
|
||||
(10.4 free − 2.0 GPU overhead − 0.46 minimum), so e4b *always* exceeds the budget
|
||||
and evicts every co-resident before loading. Observed directly: loading it threw
|
||||
out both `gemma4:e2b` and `nomic-embed-text`. Losing nomic means Tatlock memory
|
||||
and library-desk thrash on every embedding call. Note this is not caused by the
|
||||
2 GiB reservation — without it, available would be ~9.7 GiB, still under 10.6.
|
||||
|
||||
**Lower `OLLAMA_CONTEXT_LENGTH`** — the obvious way to free headroom, and it does
|
||||
not work. Dropping 16384 → 2048, an 8× reduction, moved the prediction only from
|
||||
7.8 to 6.7 GiB. The prediction is dominated by weights and batch size, not KV
|
||||
cache. It would also truncate the Librarian's retrieved passages and webber's
|
||||
code context for a 14% saving that funds nothing.
|
||||
|
||||
**Per-request `num_ctx`** — worse. A single request with a different `num_ctx`
|
||||
reloads the shared runner, which **drops the `keep_alive: -1` pin** (expiry fell
|
||||
from year-2318 to a 2-hour default) and evicts nomic. Three services share this
|
||||
Ollama, so mixed context sizes are a thrash generator, and it fails silently.
|
||||
|
||||
**`OLLAMA_NUM_PARALLEL > 1`** — never viable here. e2b already predicts 7.8 GiB
|
||||
against ~7.9 available, so there is no room for a second slot at any context
|
||||
length. It is also set to 1 deliberately, to avoid batch overflow panics.
|
||||
|
||||
## What the two axes actually control
|
||||
|
||||
They do not interact, which is the useful part:
|
||||
|
||||
- **Model choice** governs VRAM and co-residency. e2b 1778 MB, e4b 3089 MB.
|
||||
- **Think setting** governs tokens, latency and routing quality — and costs
|
||||
**nothing** in VRAM. Verified: e2b is resident at 1778 MB with `think` unset,
|
||||
true and false alike, because the KV cache is allocated for the full context at
|
||||
load time and `think` is a per-request generation parameter.
|
||||
|
||||
So the only real question is whether 313 tokens and 3.7 seconds are worth 12.5
|
||||
points of compound-query routing. On a turn that is already three sequential
|
||||
Ollama calls, they are.
|
||||
|
||||
## Prerequisite: the extraction fix
|
||||
|
||||
These numbers are only meaningful because `_extract_capabilities` was fixed first
|
||||
(commit `a905363`). It previously substring-matched capability *domains* across
|
||||
the Steward's entire response, so ordinary English in the `REASON:` line selected
|
||||
agents — "description" contains the housekeeper domain "script", "acknowledge"
|
||||
contains "knowledge" and "know".
|
||||
|
||||
That made **prose length a routing input**. Benchmarking against it would have
|
||||
shown `think: false` improving routing purely because shorter output produces
|
||||
fewer accidental substring hits — a thinking policy derived from a parsing
|
||||
artefact. The `adversarial` fixture group is regression coverage for exactly this.
|
||||
|
||||
## If this is revisited
|
||||
|
||||
The constraint is the single 11 GB card, not the model. A second inference host
|
||||
(*forge*) removes it entirely, and e4b's 100% routing becomes reachable without
|
||||
evicting anything. Re-run then; on this card the answer is settled.
|
||||
|
||||
`scripts/benchmark_routing.py` takes `--models`, `--think` and `--repeats`, and
|
||||
restores GPU residency on exit — including on SIGTERM, which the first version
|
||||
did not.
|
||||
+63
-3
@@ -4,17 +4,72 @@ build-backend = "setuptools.build_meta"
|
||||
|
||||
[project]
|
||||
name = "tatlock"
|
||||
version = "2.0.3"
|
||||
version = "2.4.3"
|
||||
description = "OpenAI-compatible API with Ollama backend"
|
||||
requires-python = ">=3.12"
|
||||
dependencies = []
|
||||
dependencies = [
|
||||
"fastapi>=0.123,<0.124",
|
||||
"uvicorn[standard]>=0.38,<0.39",
|
||||
"pydantic>=2.11,<2.13",
|
||||
"pydantic-settings>=2.12,<2.13",
|
||||
"pydantic-ai-slim[openai,anthropic]>=1.27,<1.28",
|
||||
# pydantic-ai 1.27 imports the private opentelemetry._events module,
|
||||
# removed in opentelemetry-api 1.44 — cap until pydantic-ai is bumped
|
||||
"opentelemetry-api>=1.30,<1.44",
|
||||
"anthropic>=0.77,<1.0",
|
||||
"httpx>=0.28,<0.29",
|
||||
"sse-starlette>=3.0,<3.1",
|
||||
"python-dotenv>=1.2,<1.3",
|
||||
"starlette>=0.45,<0.46",
|
||||
"redis[hiredis]>=5.2,<6.0",
|
||||
"qdrant-client>=1.12,<2.0",
|
||||
"structlog>=24.1,<25.0",
|
||||
]
|
||||
|
||||
[project.optional-dependencies]
|
||||
dev = [
|
||||
"pytest>=8.3,<8.4",
|
||||
"pytest-asyncio>=0.25,<0.26",
|
||||
"pytest-cov>=6.0,<6.1",
|
||||
"pytest-mock>=3.14,<3.15",
|
||||
"ruff>=0.8,<0.9",
|
||||
"mypy>=1.14,<1.15",
|
||||
"faker>=34.0,<35.0",
|
||||
"coverage[toml]>=7.7,<7.8",
|
||||
]
|
||||
|
||||
[tool.pytest.ini_options]
|
||||
testpaths = ["tests"]
|
||||
python_files = ["test_*.py"]
|
||||
python_classes = ["Test*"]
|
||||
python_functions = ["test_*"]
|
||||
asyncio_mode = "auto"
|
||||
asyncio_default_fixture_loop_scope = "function"
|
||||
cache_dir = ".cache/pytest"
|
||||
markers = [
|
||||
"unit: Unit tests",
|
||||
"integration: Integration tests",
|
||||
"slow: Slow running tests",
|
||||
"contract: Wire-level contract tests against live service boundaries",
|
||||
]
|
||||
addopts = [
|
||||
"--verbose",
|
||||
"--strict-markers",
|
||||
"--tb=short",
|
||||
"--cov=src",
|
||||
"--cov-report=term-missing",
|
||||
"--cov-report=html:build/coverage/html",
|
||||
"--cov-report=xml:build/coverage/coverage.xml",
|
||||
"--cov-branch",
|
||||
]
|
||||
filterwarnings = [
|
||||
"ignore::DeprecationWarning",
|
||||
]
|
||||
|
||||
[tool.coverage.run]
|
||||
source = ["src"]
|
||||
branch = true
|
||||
data_file = "build/coverage/.coverage"
|
||||
omit = [
|
||||
"*/tests/*",
|
||||
"*/__pycache__/*",
|
||||
@@ -37,11 +92,15 @@ exclude_lines = [
|
||||
]
|
||||
|
||||
[tool.coverage.html]
|
||||
directory = "htmlcov"
|
||||
directory = "build/coverage/html"
|
||||
|
||||
[tool.coverage.xml]
|
||||
output = "build/coverage/coverage.xml"
|
||||
|
||||
[tool.ruff]
|
||||
line-length = 100
|
||||
target-version = "py312"
|
||||
cache-dir = ".cache/ruff"
|
||||
|
||||
[tool.ruff.lint]
|
||||
select = [
|
||||
@@ -64,6 +123,7 @@ ignore = [
|
||||
|
||||
[tool.mypy]
|
||||
python_version = "3.12"
|
||||
cache_dir = ".cache/mypy"
|
||||
warn_return_any = true
|
||||
warn_unused_configs = true
|
||||
disallow_untyped_defs = true
|
||||
|
||||
-28
@@ -1,28 +0,0 @@
|
||||
[pytest]
|
||||
testpaths = tests
|
||||
python_files = test_*.py
|
||||
python_classes = Test*
|
||||
python_functions = test_*
|
||||
asyncio_mode = auto
|
||||
asyncio_default_fixture_loop_scope = function
|
||||
|
||||
# Markers
|
||||
markers =
|
||||
unit: Unit tests
|
||||
integration: Integration tests
|
||||
slow: Slow running tests
|
||||
|
||||
# Coverage options (overridden by pyproject.toml)
|
||||
addopts =
|
||||
--verbose
|
||||
--strict-markers
|
||||
--tb=short
|
||||
--cov=src
|
||||
--cov-report=term-missing
|
||||
--cov-report=html
|
||||
--cov-report=xml
|
||||
--cov-branch
|
||||
|
||||
# Ignore warnings from dependencies
|
||||
filterwarnings =
|
||||
ignore::DeprecationWarning
|
||||
@@ -1,25 +0,0 @@
|
||||
# Development and Testing Dependencies
|
||||
# Install with: pip install -r requirements.txt -r requirements-dev.txt
|
||||
|
||||
# Testing Framework
|
||||
# Latest pytest with async support
|
||||
pytest>=8.3,<8.4
|
||||
pytest-asyncio>=0.25,<0.26
|
||||
pytest-cov>=6.0,<6.1
|
||||
|
||||
# Test client for FastAPI
|
||||
httpx>=0.28,<0.29 # Already in requirements.txt but needed for test client
|
||||
|
||||
# Code Quality
|
||||
# Linting and formatting
|
||||
ruff>=0.8,<0.9
|
||||
|
||||
# Type checking
|
||||
mypy>=1.14,<1.15
|
||||
|
||||
# Testing utilities
|
||||
pytest-mock>=3.14,<3.15
|
||||
faker>=34.0,<35.0
|
||||
|
||||
# Coverage reporting
|
||||
coverage[toml]>=7.7,<7.8
|
||||
@@ -1,60 +0,0 @@
|
||||
# Core FastAPI framework and server
|
||||
# FastAPI: Modern, fast web framework for building APIs
|
||||
# Latest: 0.123.9 (Dec 4, 2025) - No known CVEs
|
||||
fastapi>=0.123,<0.124
|
||||
|
||||
# ASGI server for running FastAPI
|
||||
# Latest: 0.38.0 (Oct 18, 2025) - No known CVEs
|
||||
# Note: Old versions had CVE-2020-7694/7695, but 0.38.0 is secure
|
||||
uvicorn[standard]>=0.38,<0.39
|
||||
|
||||
# Additional dependencies
|
||||
# Pydantic for data validation (comes with pydantic-ai but pinning explicitly)
|
||||
# Updated to >=2.11 due to ag-ui-protocol dependency requirement
|
||||
# Latest: 2.12.4 (Nov 5, 2025) - No known CVEs
|
||||
pydantic>=2.11,<2.13
|
||||
|
||||
# Pydantic settings for configuration management
|
||||
# Required explicitly since pydantic-ai-slim doesn't include it
|
||||
# Latest: 2.12.0 (Dec 2025) - No known CVEs
|
||||
pydantic-settings>=2.12,<2.13
|
||||
|
||||
# AI/LLM integration
|
||||
# PydanticAI: Agent framework for using Pydantic with LLMs
|
||||
# Using slim version with openai (Ollama) and anthropic (Claude) extras
|
||||
# See DEPENDENCY_SLIM.md for rollback instructions if this breaks
|
||||
pydantic-ai-slim[openai,anthropic]>=1.27,<1.28
|
||||
|
||||
# HTTP client for Ollama communication
|
||||
# Latest: 0.28.1 - No known CVEs
|
||||
httpx>=0.28,<0.29
|
||||
|
||||
# Server-Sent Events for streaming responses
|
||||
# Required for OpenAI-compatible streaming endpoints
|
||||
# Latest: 3.0.2 (Oct 30, 2025) - No known CVEs
|
||||
sse-starlette>=3.0,<3.1
|
||||
|
||||
# Configuration management
|
||||
# Latest: 1.2.1 (Oct 26, 2025) - No known CVEs
|
||||
python-dotenv>=1.2,<1.3
|
||||
|
||||
# ASGI toolkit (dependency of FastAPI, pinning for security)
|
||||
starlette>=0.45,<0.46
|
||||
|
||||
# Redis for performance benchmarking and caching
|
||||
# Latest: 5.2.1 (Dec 5, 2025) - No known CVEs
|
||||
# hiredis: C parser for better performance
|
||||
redis[hiredis]>=5.2,<6.0
|
||||
|
||||
# Qdrant vector database client for memory storage
|
||||
# Latest: 1.12.1 (Dec 2025) - No known CVEs
|
||||
qdrant-client>=1.12,<2.0
|
||||
|
||||
# Structured logging for observability
|
||||
# Latest: 24.4.0 (Aug 22, 2024) - No known CVEs
|
||||
structlog>=24.1,<25.0
|
||||
|
||||
# Note on version locking strategy:
|
||||
# Using >=X.Y,<X.(Y+1) format to lock to minor versions
|
||||
# This protects against supply chain attacks while allowing patch updates
|
||||
# Update regularly and review changelogs before upgrading minor versions
|
||||
@@ -0,0 +1,235 @@
|
||||
"""
|
||||
Benchmark Steward routing quality against model and thinking settings.
|
||||
|
||||
Talks to Ollama directly. No Tatlock server, no agents, no tools, nothing is
|
||||
executed — the mutating fixtures ("turn on the lights", "update the wiki") only
|
||||
ever produce a routing decision. That makes this cheap and repeatable, and it
|
||||
isolates the question: does the Steward still pick the right capabilities when
|
||||
the model reasons less?
|
||||
|
||||
The request body is byte-identical to StewardAgent._call_ollama, plus the
|
||||
`think` flag under test, so a cell labelled `unset` is exactly what production
|
||||
sends today.
|
||||
|
||||
Three thinking settings, because "on vs off" hides the interesting case:
|
||||
|
||||
unset what production sends now. gemma4 reasons by default, and the
|
||||
response carries no `thinking` field, so those tokens are generated
|
||||
and discarded.
|
||||
true reasoning requested explicitly and returned in `thinking`.
|
||||
false reasoning suppressed.
|
||||
|
||||
Scoring is deliberately asymmetric. A missing capability under-routes and the
|
||||
Butler answers without a tool it needed; a spurious one over-routes, and that is
|
||||
a real agent call — a stray librarian is a multi-second web search on a query
|
||||
that asked for arithmetic. Over-routing is the predicted failure when thinking
|
||||
is off, so `forbid` violations are reported separately rather than folded into
|
||||
one accuracy number.
|
||||
|
||||
Usage:
|
||||
.venv/bin/python scripts/benchmark_routing.py
|
||||
.venv/bin/python scripts/benchmark_routing.py --models gemma4:e2b
|
||||
.venv/bin/python scripts/benchmark_routing.py --think false --repeats 3
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import statistics
|
||||
import sys
|
||||
import time
|
||||
from datetime import UTC, datetime
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
import httpx
|
||||
|
||||
PROJECT_ROOT = Path(__file__).resolve().parents[1]
|
||||
sys.path.insert(0, str(PROJECT_ROOT))
|
||||
|
||||
from scripts.fixtures.routing_fixtures import FIXTURES # noqa: E402
|
||||
from scripts.ollama_residency import ( # noqa: E402
|
||||
install_sigterm_handler,
|
||||
residency_guard,
|
||||
)
|
||||
from src.agents.steward.agent import build_steward_prompt # noqa: E402
|
||||
from src.agents.steward.service import _DELEGATE_LINE_RE, _extract_capabilities # noqa: E402
|
||||
from src.core.startup import register_household_members # noqa: E402
|
||||
|
||||
OLLAMA_URL = "http://localhost:11434"
|
||||
DEFAULT_MODELS = ["gemma4:e2b", "gemma4:e4b"]
|
||||
DEFAULT_THINK = ["unset", "true", "false"]
|
||||
RESULTS_DIR = PROJECT_ROOT / "logs"
|
||||
|
||||
|
||||
def build_body(model: str, prompt: str, think: str) -> dict[str, Any]:
|
||||
"""Mirror StewardAgent._call_ollama exactly, then add the flag under test."""
|
||||
body: dict[str, Any] = {
|
||||
"model": model,
|
||||
"prompt": prompt,
|
||||
"stream": False,
|
||||
"options": {
|
||||
"temperature": 0.3, # Lower = more consistent
|
||||
"top_p": 0.9,
|
||||
},
|
||||
}
|
||||
if think != "unset":
|
||||
body["think"] = think == "true"
|
||||
return body
|
||||
|
||||
|
||||
def call(client: httpx.Client, body: dict[str, Any]) -> dict[str, Any] | None:
|
||||
try:
|
||||
response = client.post(f"{OLLAMA_URL}/api/generate", json=body)
|
||||
response.raise_for_status()
|
||||
return response.json()
|
||||
except Exception as exc: # noqa: BLE001 - a failed cell must not abort the run
|
||||
print(f" ! {exc}", file=sys.stderr)
|
||||
return None
|
||||
|
||||
|
||||
def score(fixture: dict, found: list[str]) -> dict[str, Any]:
|
||||
expected = set(fixture["expect"])
|
||||
forbidden = set(fixture["forbid"])
|
||||
got = set(found)
|
||||
missing = sorted(expected - got)
|
||||
spurious = sorted(got & forbidden)
|
||||
return {
|
||||
"found": found,
|
||||
"missing": missing,
|
||||
"spurious": spurious,
|
||||
# Exact only when everything expected arrived and nothing forbidden did.
|
||||
"exact": not missing and not spurious,
|
||||
"under_routed": bool(missing),
|
||||
"over_routed": bool(spurious),
|
||||
}
|
||||
|
||||
|
||||
def run_cell(client: httpx.Client, model: str, think: str, repeats: int) -> list[dict[str, Any]]:
|
||||
rows: list[dict[str, Any]] = []
|
||||
for fixture in FIXTURES:
|
||||
prompt = build_steward_prompt(fixture["query"], [])
|
||||
body = build_body(model, prompt, think)
|
||||
for rep in range(repeats):
|
||||
started = time.perf_counter()
|
||||
data = call(client, body)
|
||||
elapsed_ms = (time.perf_counter() - started) * 1000
|
||||
if data is None:
|
||||
rows.append({
|
||||
"id": fixture["id"], "group": fixture["group"], "rep": rep,
|
||||
"error": True, "exact": False, "under_routed": False, "over_routed": False,
|
||||
})
|
||||
continue
|
||||
|
||||
text = data.get("response", "") or ""
|
||||
found = _extract_capabilities(text)
|
||||
rows.append({
|
||||
"id": fixture["id"],
|
||||
"group": fixture["group"],
|
||||
"rep": rep,
|
||||
"error": False,
|
||||
"latency_ms": round(elapsed_ms, 1),
|
||||
"eval_tokens": data.get("eval_count"),
|
||||
"prompt_tokens": data.get("prompt_eval_count"),
|
||||
# Did the model obey the documented output shape at all?
|
||||
"has_delegate_line": bool(_DELEGATE_LINE_RE.search(text)),
|
||||
# Whether reasoning came back, as opposed to being generated and dropped.
|
||||
"thinking_returned": bool(data.get("thinking")),
|
||||
"response_chars": len(text),
|
||||
**score(fixture, found),
|
||||
})
|
||||
return rows
|
||||
|
||||
|
||||
def summarise(rows: list[dict[str, Any]]) -> dict[str, Any]:
|
||||
ok = [r for r in rows if not r["error"]]
|
||||
if not ok:
|
||||
return {"n": 0, "errors": len(rows)}
|
||||
latencies = [r["latency_ms"] for r in ok]
|
||||
tokens = [r["eval_tokens"] for r in ok if r["eval_tokens"] is not None]
|
||||
return {
|
||||
"n": len(ok),
|
||||
"errors": len(rows) - len(ok),
|
||||
"exact_pct": round(100 * sum(r["exact"] for r in ok) / len(ok), 1),
|
||||
"under_routed_pct": round(100 * sum(r["under_routed"] for r in ok) / len(ok), 1),
|
||||
"over_routed_pct": round(100 * sum(r["over_routed"] for r in ok) / len(ok), 1),
|
||||
"format_ok_pct": round(100 * sum(r["has_delegate_line"] for r in ok) / len(ok), 1),
|
||||
"thinking_returned_pct": round(100 * sum(r["thinking_returned"] for r in ok) / len(ok), 1),
|
||||
"latency_ms_median": round(statistics.median(latencies), 1),
|
||||
"latency_ms_mean": round(statistics.fmean(latencies), 1),
|
||||
"eval_tokens_median": round(statistics.median(tokens), 1) if tokens else None,
|
||||
"eval_tokens_total": sum(tokens) if tokens else None,
|
||||
}
|
||||
|
||||
|
||||
def main() -> int:
|
||||
install_sigterm_handler()
|
||||
|
||||
parser = argparse.ArgumentParser(description=__doc__)
|
||||
parser.add_argument("--models", default=",".join(DEFAULT_MODELS))
|
||||
parser.add_argument("--think", default=",".join(DEFAULT_THINK),
|
||||
help="comma-separated subset of unset,true,false")
|
||||
parser.add_argument("--repeats", type=int, default=1)
|
||||
parser.add_argument("--timeout", type=float, default=180.0)
|
||||
args = parser.parse_args()
|
||||
|
||||
models = [m.strip() for m in args.models.split(",") if m.strip()]
|
||||
think_modes = [t.strip() for t in args.think.split(",") if t.strip()]
|
||||
|
||||
# build_steward_prompt reads the registry, and the registry is populated at
|
||||
# application startup. Without this the prompt lists no capabilities and every
|
||||
# cell scores zero for reasons that have nothing to do with the model.
|
||||
register_household_members()
|
||||
|
||||
print(f"{len(FIXTURES)} fixtures x {len(models)} models x {len(think_modes)} think "
|
||||
f"x {args.repeats} repeats = {len(FIXTURES) * len(models) * len(think_modes) * args.repeats} calls\n")
|
||||
|
||||
cells: dict[str, Any] = {}
|
||||
# The guard restores production's pinned models however this exits — a
|
||||
# finished run, a failed cell, Ctrl-C or SIGTERM.
|
||||
with residency_guard(models_used=models), httpx.Client(timeout=args.timeout) as client:
|
||||
for model in models:
|
||||
# Absorb the cold load (~36s) outside the measurements.
|
||||
print(f"warming {model} ...", flush=True)
|
||||
call(client, build_body(model, "hi", "false"))
|
||||
for think in think_modes:
|
||||
key = f"{model}|think={think}"
|
||||
print(f" {key} ...", end=" ", flush=True)
|
||||
started = time.perf_counter()
|
||||
rows = run_cell(client, model, think, args.repeats)
|
||||
summary = summarise(rows)
|
||||
cells[key] = {"summary": summary, "rows": rows}
|
||||
print(f"exact={summary.get('exact_pct')}% "
|
||||
f"over={summary.get('over_routed_pct')}% "
|
||||
f"median={summary.get('latency_ms_median')}ms "
|
||||
f"({time.perf_counter() - started:.0f}s)")
|
||||
|
||||
RESULTS_DIR.mkdir(parents=True, exist_ok=True)
|
||||
stamp = datetime.now(UTC).strftime("%Y%m%dT%H%M%SZ")
|
||||
out = RESULTS_DIR / f"routing-bench-{stamp}.json"
|
||||
out.write_text(json.dumps({
|
||||
"generated_at": datetime.now(UTC).isoformat(),
|
||||
"fixtures": len(FIXTURES),
|
||||
"repeats": args.repeats,
|
||||
"cells": cells,
|
||||
}, indent=2))
|
||||
|
||||
print(f"\n{'cell':28} {'exact':>7} {'under':>7} {'over':>7} {'fmt':>6} {'tok':>7} {'ms':>8}")
|
||||
print("-" * 76)
|
||||
for key, cell in cells.items():
|
||||
s = cell["summary"]
|
||||
print(f"{key:28} {s.get('exact_pct'):>6}% {s.get('under_routed_pct'):>6}% "
|
||||
f"{s.get('over_routed_pct'):>6}% {s.get('format_ok_pct'):>5}% "
|
||||
f"{str(s.get('eval_tokens_median')):>7} {s.get('latency_ms_median'):>8}")
|
||||
print(f"\nwritten to {out}")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
try:
|
||||
sys.exit(main())
|
||||
except KeyboardInterrupt:
|
||||
# The residency guard has already run by the time this is caught;
|
||||
# a traceback here would just bury its output.
|
||||
print("\ninterrupted", file=sys.stderr)
|
||||
sys.exit(130)
|
||||
@@ -268,7 +268,7 @@ async def run_benchmarks(iterations: int = 10, verbose: bool = False):
|
||||
print(f" Max: {overall_max:.3f}s (target: ≤5.0s)")
|
||||
print(f" Avg: {overall_avg:.3f}s (target: ≤1.67s)")
|
||||
print(f"\n Recommendations:")
|
||||
print(f" - Switch to a faster model (current: mistral-nemo)")
|
||||
print(f" - Switch to a faster model (current: gemma4:e2b)")
|
||||
print(f" - Reduce system prompt complexity")
|
||||
print(f" - Limit tool calls (currently limited to 3)")
|
||||
print(f" - Consider caching household registry responses")
|
||||
|
||||
@@ -0,0 +1,559 @@
|
||||
"""
|
||||
Benchmark tool calling across different Ollama models via Tatlock API.
|
||||
|
||||
Sends test prompts through the full Tatlock pipeline (Steward -> Orchestration
|
||||
-> Synthesis) and records tool selection accuracy, latency, and response quality.
|
||||
|
||||
Between models, swaps OLLAMA_DEFAULT_MODEL in .env and waits for uvicorn
|
||||
auto-reload. Requires the server to be running via ./wakeup.sh.
|
||||
|
||||
Usage:
|
||||
.venv/bin/python scripts/benchmark_tool_calling.py
|
||||
.venv/bin/python scripts/benchmark_tool_calling.py --models "gemma4:e4b,gemma4:e2b"
|
||||
.venv/bin/python scripts/benchmark_tool_calling.py --iterations 3
|
||||
"""
|
||||
import argparse
|
||||
import asyncio
|
||||
import json
|
||||
import re
|
||||
import statistics
|
||||
import sys
|
||||
import time
|
||||
from dataclasses import dataclass, field
|
||||
from pathlib import Path
|
||||
|
||||
import httpx
|
||||
|
||||
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
|
||||
from scripts.ollama_residency import install_sigterm_handler, residency_guard
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Configuration
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
API_BASE = "http://localhost:8777"
|
||||
CHAT_URL = f"{API_BASE}/v1/chat/completions"
|
||||
HEALTH_URL = f"{API_BASE}/health"
|
||||
OLLAMA_URL = "http://localhost:11434"
|
||||
ENV_PATH = Path(__file__).parent.parent / ".env"
|
||||
|
||||
DEFAULT_MODELS = ["mistral-nemo-large:latest", "gemma4:e4b", "gemma4:e2b"]
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Test scenarios
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
@dataclass
|
||||
class Scenario:
|
||||
name: str
|
||||
prompt: str
|
||||
expected_tool: str | None # None = no tool expected
|
||||
# Patterns to check in the response text for indirect tool-use evidence
|
||||
success_patterns: list[str] = field(default_factory=list)
|
||||
category: str = "basic"
|
||||
|
||||
|
||||
SCENARIOS = [
|
||||
# --- Should call calculate_math ---
|
||||
Scenario(
|
||||
name="Simple arithmetic",
|
||||
prompt="What is 144 divided by 12?",
|
||||
expected_tool="calculate_math",
|
||||
success_patterns=["12"],
|
||||
category="calculator",
|
||||
),
|
||||
Scenario(
|
||||
name="Square root",
|
||||
prompt="What's the square root of 256?",
|
||||
expected_tool="calculate_math",
|
||||
success_patterns=["16"],
|
||||
category="calculator",
|
||||
),
|
||||
Scenario(
|
||||
name="Complex math",
|
||||
prompt="Calculate pi times the square of 5",
|
||||
expected_tool="calculate_math",
|
||||
success_patterns=["78.5"], # pi * 25 ≈ 78.54
|
||||
category="calculator",
|
||||
),
|
||||
Scenario(
|
||||
name="Word problem",
|
||||
prompt="If I have 3 bags with 17 apples each and I eat 4, how many apples do I have?",
|
||||
expected_tool="calculate_math",
|
||||
success_patterns=["47"],
|
||||
category="calculator",
|
||||
),
|
||||
|
||||
# --- Should call get_current_time ---
|
||||
Scenario(
|
||||
name="Current date",
|
||||
prompt="What's today's date?",
|
||||
expected_tool="get_current_time",
|
||||
success_patterns=["2026"], # Should contain current year
|
||||
category="datetime",
|
||||
),
|
||||
Scenario(
|
||||
name="Current time",
|
||||
prompt="What time is it right now?",
|
||||
expected_tool="get_current_time",
|
||||
success_patterns=[":"], # Time format contains colons
|
||||
category="datetime",
|
||||
),
|
||||
|
||||
# --- Should call calculate_date_offset ---
|
||||
Scenario(
|
||||
name="Relative date past",
|
||||
prompt="What was the date 2 weeks ago?",
|
||||
expected_tool="calculate_date_offset",
|
||||
success_patterns=["2026"],
|
||||
category="datetime",
|
||||
),
|
||||
|
||||
# --- Should call calculate_time_difference ---
|
||||
Scenario(
|
||||
name="Date difference",
|
||||
prompt="How many days between January 1st 2025 and March 15th 2025?",
|
||||
expected_tool="calculate_time_difference",
|
||||
success_patterns=["73", "74"], # 73 or 74 days
|
||||
category="datetime",
|
||||
),
|
||||
|
||||
# --- Should NOT call any tool ---
|
||||
Scenario(
|
||||
name="Greeting",
|
||||
prompt="Hello! How are you?",
|
||||
expected_tool=None,
|
||||
success_patterns=["sir"], # Butler personality
|
||||
category="no_tool",
|
||||
),
|
||||
Scenario(
|
||||
name="Knowledge question",
|
||||
prompt="What is the capital of France?",
|
||||
expected_tool=None,
|
||||
success_patterns=["Paris"],
|
||||
category="no_tool",
|
||||
),
|
||||
Scenario(
|
||||
name="Opinion request",
|
||||
prompt="What do you think about rainy days?",
|
||||
expected_tool=None,
|
||||
category="no_tool",
|
||||
),
|
||||
]
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Result tracking
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
@dataclass
|
||||
class RunResult:
|
||||
scenario: str
|
||||
model: str
|
||||
iteration: int
|
||||
latency: float
|
||||
response_text: str
|
||||
has_correct_answer: bool
|
||||
error: str | None = None
|
||||
|
||||
|
||||
@dataclass
|
||||
class ModelStats:
|
||||
model: str
|
||||
results: list[RunResult] = field(default_factory=list)
|
||||
|
||||
@property
|
||||
def total(self) -> int:
|
||||
return len(self.results)
|
||||
|
||||
@property
|
||||
def errors(self) -> int:
|
||||
return sum(1 for r in self.results if r.error)
|
||||
|
||||
@property
|
||||
def accuracy(self) -> float:
|
||||
valid = [r for r in self.results if not r.error]
|
||||
if not valid:
|
||||
return 0
|
||||
return sum(1 for r in valid if r.has_correct_answer) / len(valid) * 100
|
||||
|
||||
@property
|
||||
def avg_latency(self) -> float:
|
||||
lats = [r.latency for r in self.results if not r.error]
|
||||
return statistics.mean(lats) if lats else 0
|
||||
|
||||
@property
|
||||
def p95_latency(self) -> float:
|
||||
lats = sorted(r.latency for r in self.results if not r.error)
|
||||
if not lats:
|
||||
return 0
|
||||
return lats[min(int(len(lats) * 0.95), len(lats) - 1)]
|
||||
|
||||
@property
|
||||
def max_latency(self) -> float:
|
||||
lats = [r.latency for r in self.results if not r.error]
|
||||
return max(lats) if lats else 0
|
||||
|
||||
def category_accuracy(self, category: str) -> float:
|
||||
cat_scenarios = {s.name for s in SCENARIOS if s.category == category}
|
||||
valid = [r for r in self.results if not r.error and r.scenario in cat_scenarios]
|
||||
if not valid:
|
||||
return 0
|
||||
return sum(1 for r in valid if r.has_correct_answer) / len(valid) * 100
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# .env manipulation
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def swap_model_in_env(model_name: str):
|
||||
"""Swap OLLAMA_DEFAULT_MODEL in .env file."""
|
||||
content = ENV_PATH.read_text()
|
||||
content = re.sub(
|
||||
r'^OLLAMA_DEFAULT_MODEL=.*$',
|
||||
f'OLLAMA_DEFAULT_MODEL={model_name}',
|
||||
content,
|
||||
flags=re.MULTILINE,
|
||||
)
|
||||
ENV_PATH.write_text(content)
|
||||
print(f" .env updated: OLLAMA_DEFAULT_MODEL={model_name}")
|
||||
|
||||
|
||||
async def wait_for_server_reload(client: httpx.AsyncClient, timeout: float = 30):
|
||||
"""Wait for uvicorn to auto-reload after .env change."""
|
||||
# Give uvicorn a moment to detect the file change
|
||||
await asyncio.sleep(3)
|
||||
|
||||
# Poll health endpoint
|
||||
deadline = time.monotonic() + timeout
|
||||
while time.monotonic() < deadline:
|
||||
try:
|
||||
r = await client.get(HEALTH_URL, timeout=5)
|
||||
if r.status_code == 200:
|
||||
return
|
||||
except Exception:
|
||||
pass
|
||||
await asyncio.sleep(1)
|
||||
|
||||
raise TimeoutError("Server did not come back after reload")
|
||||
|
||||
|
||||
async def warm_up_ollama_model(client: httpx.AsyncClient, model_name: str):
|
||||
"""Send a throwaway request to load the model into VRAM."""
|
||||
print(f" Warming up {model_name} in Ollama...", end=" ", flush=True)
|
||||
try:
|
||||
r = await client.post(
|
||||
f"{OLLAMA_URL}/api/generate",
|
||||
json={"model": model_name, "prompt": "hi", "stream": False},
|
||||
timeout=120,
|
||||
)
|
||||
r.raise_for_status()
|
||||
duration = r.json().get("total_duration", 0) / 1e9
|
||||
print(f"OK ({duration:.1f}s)")
|
||||
except Exception as e:
|
||||
print(f"WARN: {e}")
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Core benchmark logic
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
async def run_scenario(
|
||||
client: httpx.AsyncClient,
|
||||
scenario: Scenario,
|
||||
model: str,
|
||||
iteration: int,
|
||||
) -> RunResult:
|
||||
"""Run a single scenario through the Tatlock API."""
|
||||
payload = {
|
||||
"model": "Tatlock",
|
||||
"messages": [{"role": "user", "content": scenario.prompt}],
|
||||
}
|
||||
|
||||
start = time.monotonic()
|
||||
try:
|
||||
r = await client.post(CHAT_URL, json=payload, timeout=120)
|
||||
latency = time.monotonic() - start
|
||||
|
||||
if r.status_code != 200:
|
||||
return RunResult(
|
||||
scenario=scenario.name,
|
||||
model=model,
|
||||
iteration=iteration,
|
||||
latency=latency,
|
||||
response_text="",
|
||||
has_correct_answer=False,
|
||||
error=f"HTTP {r.status_code}: {r.text[:100]}",
|
||||
)
|
||||
|
||||
data = r.json()
|
||||
response_text = data["choices"][0]["message"]["content"]
|
||||
|
||||
# Check if the response contains expected patterns
|
||||
has_correct = True
|
||||
if scenario.success_patterns:
|
||||
has_correct = any(
|
||||
p.lower() in response_text.lower()
|
||||
for p in scenario.success_patterns
|
||||
)
|
||||
|
||||
return RunResult(
|
||||
scenario=scenario.name,
|
||||
model=model,
|
||||
iteration=iteration,
|
||||
latency=latency,
|
||||
response_text=response_text,
|
||||
has_correct_answer=has_correct,
|
||||
)
|
||||
|
||||
except Exception as e:
|
||||
latency = time.monotonic() - start
|
||||
return RunResult(
|
||||
scenario=scenario.name,
|
||||
model=model,
|
||||
iteration=iteration,
|
||||
latency=latency,
|
||||
response_text="",
|
||||
has_correct_answer=False,
|
||||
error=str(e)[:200],
|
||||
)
|
||||
|
||||
|
||||
async def benchmark_model(
|
||||
client: httpx.AsyncClient,
|
||||
model_name: str,
|
||||
iterations: int,
|
||||
) -> ModelStats:
|
||||
"""Run all scenarios for a single model."""
|
||||
stats = ModelStats(model=model_name)
|
||||
|
||||
print(f"\n{'=' * 70}")
|
||||
print(f" Model: {model_name}")
|
||||
print(f"{'=' * 70}")
|
||||
|
||||
# Swap model in .env
|
||||
swap_model_in_env(model_name)
|
||||
|
||||
# Warm up model in Ollama BEFORE server reload picks it up
|
||||
await warm_up_ollama_model(client, model_name)
|
||||
|
||||
# Wait for server to reload with new model
|
||||
print(" Waiting for server reload...", end=" ", flush=True)
|
||||
await wait_for_server_reload(client)
|
||||
print("OK")
|
||||
|
||||
# Run a throwaway request through the full pipeline to warm up
|
||||
print(" Warming up pipeline...", end=" ", flush=True)
|
||||
try:
|
||||
await client.post(
|
||||
CHAT_URL,
|
||||
json={"model": "Tatlock", "messages": [{"role": "user", "content": "hi"}]},
|
||||
timeout=120,
|
||||
)
|
||||
print("OK")
|
||||
except Exception as e:
|
||||
print(f"WARN: {e}")
|
||||
|
||||
for iteration in range(iterations):
|
||||
if iterations > 1:
|
||||
print(f"\n --- Iteration {iteration + 1}/{iterations} ---")
|
||||
|
||||
for scenario in SCENARIOS:
|
||||
result = await run_scenario(client, scenario, model_name, iteration)
|
||||
stats.results.append(result)
|
||||
|
||||
# Display
|
||||
if result.error:
|
||||
print(
|
||||
f" [ERR ] {scenario.name:30s} {result.latency:5.1f}s "
|
||||
f"{result.error[:60]}"
|
||||
)
|
||||
elif result.has_correct_answer:
|
||||
preview = result.response_text[:60].replace("\n", " ")
|
||||
print(f" [OK ] {scenario.name:30s} {result.latency:5.1f}s {preview}")
|
||||
else:
|
||||
preview = result.response_text[:60].replace("\n", " ")
|
||||
print(f" [MISS] {scenario.name:30s} {result.latency:5.1f}s {preview}")
|
||||
|
||||
return stats
|
||||
|
||||
|
||||
def print_comparison(all_stats: list[ModelStats]):
|
||||
"""Print side-by-side comparison table."""
|
||||
print("\n" + "=" * 80)
|
||||
print(" COMPARISON SUMMARY")
|
||||
print("=" * 80)
|
||||
|
||||
col_width = max(len(s.model) for s in all_stats) + 2
|
||||
label_width = 32
|
||||
|
||||
header = f"{'Metric':<{label_width}}"
|
||||
for s in all_stats:
|
||||
header += f" {s.model:>{col_width}}"
|
||||
print(f"\n{header}")
|
||||
print("-" * (label_width + (col_width + 2) * len(all_stats)))
|
||||
|
||||
# Answer accuracy
|
||||
row = f"{'Correct answer rate':<{label_width}}"
|
||||
for s in all_stats:
|
||||
row += f" {s.accuracy:>{col_width - 1}.1f}%"
|
||||
print(row)
|
||||
|
||||
# Latency
|
||||
row = f"{'Avg latency':<{label_width}}"
|
||||
for s in all_stats:
|
||||
row += f" {s.avg_latency:>{col_width - 1}.1f}s"
|
||||
print(row)
|
||||
|
||||
row = f"{'P95 latency':<{label_width}}"
|
||||
for s in all_stats:
|
||||
row += f" {s.p95_latency:>{col_width - 1}.1f}s"
|
||||
print(row)
|
||||
|
||||
row = f"{'Max latency':<{label_width}}"
|
||||
for s in all_stats:
|
||||
row += f" {s.max_latency:>{col_width - 1}.1f}s"
|
||||
print(row)
|
||||
|
||||
# Errors
|
||||
row = f"{'Errors':<{label_width}}"
|
||||
for s in all_stats:
|
||||
row += f" {s.errors:>{col_width}}"
|
||||
print(row)
|
||||
|
||||
# Per-category
|
||||
categories = sorted(set(sc.category for sc in SCENARIOS))
|
||||
print(f"\n{'Per-category accuracy':<{label_width}}")
|
||||
print("-" * (label_width + (col_width + 2) * len(all_stats)))
|
||||
for cat in categories:
|
||||
row = f" {cat:<{label_width - 2}}"
|
||||
for s in all_stats:
|
||||
row += f" {s.category_accuracy(cat):>{col_width - 1}.1f}%"
|
||||
print(row)
|
||||
|
||||
# Mismatches
|
||||
print(f"\n{'Missed answers':<50}")
|
||||
print("-" * 80)
|
||||
any_miss = False
|
||||
for scenario in SCENARIOS:
|
||||
misses = []
|
||||
for s in all_stats:
|
||||
sc_results = [r for r in s.results if r.scenario == scenario.name]
|
||||
fails = [r for r in sc_results if not r.has_correct_answer and not r.error]
|
||||
if fails:
|
||||
preview = fails[0].response_text[:50].replace("\n", " ")
|
||||
misses.append(f"{s.model}: \"{preview}\"")
|
||||
if misses:
|
||||
any_miss = True
|
||||
print(f" {scenario.name}")
|
||||
for m in misses:
|
||||
print(f" {m}")
|
||||
|
||||
if not any_miss:
|
||||
print(" (none)")
|
||||
|
||||
print("\n" + "=" * 80)
|
||||
|
||||
|
||||
def save_results(all_stats: list[ModelStats], output_path: Path):
|
||||
"""Save detailed results to JSON."""
|
||||
data = {}
|
||||
for stats in all_stats:
|
||||
data[stats.model] = {
|
||||
"summary": {
|
||||
"accuracy": stats.accuracy,
|
||||
"avg_latency": round(stats.avg_latency, 2),
|
||||
"p95_latency": round(stats.p95_latency, 2),
|
||||
"max_latency": round(stats.max_latency, 2),
|
||||
"errors": stats.errors,
|
||||
"total_runs": stats.total,
|
||||
},
|
||||
"runs": [
|
||||
{
|
||||
"scenario": r.scenario,
|
||||
"iteration": r.iteration,
|
||||
"latency": round(r.latency, 3),
|
||||
"has_correct_answer": r.has_correct_answer,
|
||||
"response_text": r.response_text,
|
||||
"error": r.error,
|
||||
}
|
||||
for r in stats.results
|
||||
],
|
||||
}
|
||||
|
||||
output_path.parent.mkdir(parents=True, exist_ok=True)
|
||||
output_path.write_text(json.dumps(data, indent=2))
|
||||
print(f"\nDetailed results saved to: {output_path}")
|
||||
|
||||
|
||||
async def main():
|
||||
parser = argparse.ArgumentParser(description="Benchmark tool calling across Ollama models via Tatlock API")
|
||||
parser.add_argument(
|
||||
"--iterations", type=int, default=1,
|
||||
help="Iterations per model (default: 1)",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--models", type=str, default=",".join(DEFAULT_MODELS),
|
||||
help=f"Comma-separated models (default: {','.join(DEFAULT_MODELS)})",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--output", type=str, default="logs/benchmark_results.json",
|
||||
help="JSON output path (default: logs/benchmark_results.json)",
|
||||
)
|
||||
args = parser.parse_args()
|
||||
|
||||
models = [m.strip() for m in args.models.split(",")]
|
||||
|
||||
# Verify server is running
|
||||
async with httpx.AsyncClient() as client:
|
||||
try:
|
||||
r = await client.get(HEALTH_URL, timeout=5)
|
||||
r.raise_for_status()
|
||||
print("Server is running.")
|
||||
except Exception:
|
||||
print("ERROR: Server not running. Start it with ./wakeup.sh first.")
|
||||
return
|
||||
|
||||
print("=" * 70)
|
||||
print(" Tool Calling Benchmark (via Tatlock API)")
|
||||
print("=" * 70)
|
||||
print(f" Models: {', '.join(models)}")
|
||||
print(f" Scenarios: {len(SCENARIOS)}")
|
||||
print(f" Iterations: {args.iterations}")
|
||||
print(f" Total runs: {len(SCENARIOS) * args.iterations * len(models)}")
|
||||
|
||||
# Remember original model to restore after benchmark
|
||||
original_env = ENV_PATH.read_text()
|
||||
|
||||
all_stats = []
|
||||
# Both restores must survive a crash or an interrupt. The .env one especially:
|
||||
# this script rewrites OLLAMA_DEFAULT_MODEL and lets uvicorn reload onto it,
|
||||
# so bailing out mid-run used to leave the *running server* pointed at the
|
||||
# benchmark model — and DEFAULT_MODELS starts at mistral-nemo-large, the 9.2G
|
||||
# model implicated in the 2026-08-07 VRAM outage.
|
||||
install_sigterm_handler()
|
||||
try:
|
||||
with residency_guard(models_used=models):
|
||||
async with httpx.AsyncClient() as client:
|
||||
for model in models:
|
||||
stats = await benchmark_model(client, model, args.iterations)
|
||||
all_stats.append(stats)
|
||||
finally:
|
||||
ENV_PATH.write_text(original_env)
|
||||
print("\n .env restored to original")
|
||||
|
||||
print_comparison(all_stats)
|
||||
save_results(all_stats, Path(args.output))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
try:
|
||||
asyncio.run(main())
|
||||
except KeyboardInterrupt:
|
||||
# .env and GPU residency are both restored by now; do not bury that
|
||||
# output under a traceback.
|
||||
print("\ninterrupted", file=sys.stderr)
|
||||
raise SystemExit(130) from None
|
||||
@@ -0,0 +1,159 @@
|
||||
"""
|
||||
Labelled queries for the Steward routing benchmark.
|
||||
|
||||
Each fixture carries both `expect` and `forbid`:
|
||||
|
||||
expect capabilities that must appear. Missing one is under-routing — the
|
||||
Butler answers without a tool it needed.
|
||||
forbid capabilities that must not appear. Over-routing is not cosmetic: a
|
||||
spurious librarian is a real multi-second web call, and a spurious
|
||||
housekeeper can actuate hardware.
|
||||
|
||||
`forbid` matters more than `expect` here, because over-recommendation is the
|
||||
predicted failure when model thinking is disabled and the Steward has less room
|
||||
to discriminate.
|
||||
|
||||
The `adversarial` group deserves explanation. Until 2026-08-08 the extractor
|
||||
substring-matched capability *domains* across the Steward's whole response, so
|
||||
ordinary English in its REASON line selected agents: "description" contains the
|
||||
housekeeper domain "script", "acknowledge" contains "knowledge" and "know",
|
||||
"economy" contains the biographer domain "my". Those queries invite exactly that
|
||||
vocabulary. They now serve as an end-to-end regression: routing must depend on
|
||||
what the Steward *decided*, not on the words it happened to use while explaining.
|
||||
|
||||
Expectations follow the routing rules stated in the Steward prompt itself
|
||||
(src/agents/steward/agent.py), not on what a capability could plausibly cover.
|
||||
"""
|
||||
|
||||
CORE = "tatlock_core"
|
||||
LIB = "librarian"
|
||||
BIO = "biographer"
|
||||
HOUSE = "housekeeper"
|
||||
ALL = [CORE, LIB, BIO, HOUSE]
|
||||
|
||||
|
||||
def _others(*keep: str) -> list[str]:
|
||||
return [c for c in ALL if c not in keep]
|
||||
|
||||
|
||||
FIXTURES: list[dict] = [
|
||||
# --- arithmetic and computation -> tatlock_core --------------------------
|
||||
{"id": "math_add", "group": "math", "query": "What is 61 plus 12?",
|
||||
"expect": [CORE], "forbid": _others(CORE)},
|
||||
{"id": "math_percent", "group": "math", "query": "What is 15% of 240?",
|
||||
"expect": [CORE], "forbid": _others(CORE)},
|
||||
{"id": "math_compound", "group": "math", "query": "If I save 200 a month for 3 years, how much is that?",
|
||||
"expect": [CORE], "forbid": _others(CORE)},
|
||||
{"id": "math_sqrt", "group": "math", "query": "What is the square root of 1764?",
|
||||
"expect": [CORE], "forbid": _others(CORE)},
|
||||
|
||||
# --- date and time -> tatlock_core ---------------------------------------
|
||||
{"id": "time_now", "group": "datetime", "query": "What time is it?",
|
||||
"expect": [CORE], "forbid": _others(CORE)},
|
||||
{"id": "time_date", "group": "datetime", "query": "What is today's date?",
|
||||
"expect": [CORE], "forbid": _others(CORE)},
|
||||
{"id": "time_delta", "group": "datetime", "query": "How many days until Christmas?",
|
||||
"expect": [CORE], "forbid": _others(CORE)},
|
||||
|
||||
# --- personal memory -> biographer ---------------------------------------
|
||||
{"id": "bio_location", "group": "biographer", "query": "Where do I live?",
|
||||
"expect": [BIO], "forbid": [LIB, HOUSE]},
|
||||
{"id": "bio_name", "group": "biographer", "query": "What's my name?",
|
||||
"expect": [BIO], "forbid": [LIB, HOUSE]},
|
||||
{"id": "bio_car", "group": "biographer", "query": "What car do I drive?",
|
||||
"expect": [BIO], "forbid": [LIB, HOUSE]},
|
||||
{"id": "bio_store", "group": "biographer", "query": "Remember that I prefer my coffee black.",
|
||||
"expect": [BIO], "forbid": [LIB, HOUSE]},
|
||||
{"id": "bio_list", "group": "biographer", "query": "What do you know about me?",
|
||||
"expect": [BIO], "forbid": [LIB, HOUSE]},
|
||||
{"id": "bio_forget", "group": "biographer", "query": "Forget my old address.",
|
||||
"expect": [BIO], "forbid": [LIB, HOUSE]},
|
||||
|
||||
# --- research and current information -> librarian ------------------------
|
||||
{"id": "lib_weather", "group": "librarian", "query": "What's the weather in Rotterdam tomorrow?",
|
||||
"expect": [LIB], "forbid": [HOUSE]},
|
||||
{"id": "lib_news", "group": "librarian", "query": "What's in the news today?",
|
||||
"expect": [LIB], "forbid": [HOUSE, BIO]},
|
||||
{"id": "lib_url", "group": "librarian", "query": "Read https://example.com/article and summarise it.",
|
||||
"expect": [LIB], "forbid": [HOUSE, BIO]},
|
||||
{"id": "lib_research", "group": "librarian", "query": "Research how tidal power stations work.",
|
||||
"expect": [LIB], "forbid": [HOUSE, BIO]},
|
||||
{"id": "lib_wiki_create", "group": "librarian", "query": "Create a wiki page about our network topology.",
|
||||
"expect": [LIB], "forbid": [HOUSE, BIO]},
|
||||
|
||||
# --- home automation -> housekeeper --------------------------------------
|
||||
{"id": "house_lights_on", "group": "housekeeper", "query": "Turn on the kitchen lights.",
|
||||
"expect": [HOUSE], "forbid": [LIB, BIO, CORE]},
|
||||
{"id": "house_lights_off", "group": "housekeeper", "query": "Switch off all the lights downstairs.",
|
||||
"expect": [HOUSE], "forbid": [LIB, BIO, CORE]},
|
||||
{"id": "house_thermostat", "group": "housekeeper", "query": "Set the thermostat to 20 degrees.",
|
||||
"expect": [HOUSE], "forbid": [LIB, BIO]},
|
||||
{"id": "house_blinds", "group": "housekeeper", "query": "Close the blinds in the living room.",
|
||||
"expect": [HOUSE], "forbid": [LIB, BIO, CORE]},
|
||||
|
||||
# --- conversational -> nothing at all -------------------------------------
|
||||
# The expensive failure mode: a greeting that triggers a web search.
|
||||
{"id": "chat_greeting", "group": "conversational", "query": "Hello!",
|
||||
"expect": [], "forbid": ALL},
|
||||
{"id": "chat_thanks", "group": "conversational", "query": "Thanks, that's helpful.",
|
||||
"expect": [], "forbid": ALL},
|
||||
{"id": "chat_joke", "group": "conversational", "query": "Tell me a joke.",
|
||||
"expect": [], "forbid": ALL},
|
||||
{"id": "chat_howareyou", "group": "conversational", "query": "How are you doing today?",
|
||||
"expect": [], "forbid": ALL},
|
||||
{"id": "chat_prior_turn", "group": "conversational", "query": "What did I just say?",
|
||||
"expect": [], "forbid": ALL},
|
||||
|
||||
# --- genuinely multi-capability -------------------------------------------
|
||||
{"id": "multi_weather_home", "group": "multi",
|
||||
"query": "What's the weather here, and remember that I like it warm?",
|
||||
"expect": [LIB, BIO], "forbid": []},
|
||||
{"id": "multi_recall_search", "group": "multi",
|
||||
"query": "Look up the best route from my home address to Utrecht.",
|
||||
"expect": [BIO, LIB], "forbid": []},
|
||||
{"id": "multi_math_memory", "group": "multi",
|
||||
"query": "Remember that my budget is 500 euro, then work out 12% of it.",
|
||||
"expect": [BIO, CORE], "forbid": [LIB, HOUSE]},
|
||||
|
||||
# --- adversarial: vocabulary that used to select agents by substring ------
|
||||
# "temperature" is a housekeeper domain, but this is a unit conversion.
|
||||
{"id": "adv_temperature", "group": "adversarial", "query": "Convert 98.6 Fahrenheit to Celsius.",
|
||||
"expect": [CORE], "forbid": [HOUSE, LIB, BIO]},
|
||||
# "description" contains "script"; "discover" contains "cover".
|
||||
{"id": "adv_description", "group": "adversarial",
|
||||
"query": "Give me a short description of what 17 times 23 comes to.",
|
||||
"expect": [CORE], "forbid": [HOUSE, LIB]},
|
||||
# "acknowledge" contains "knowledge" and "know".
|
||||
{"id": "adv_acknowledge", "group": "adversarial",
|
||||
"query": "Just acknowledge this and add 5 and 6 for me.",
|
||||
"expect": [CORE], "forbid": [LIB, BIO]},
|
||||
# "my" appears inside "economy".
|
||||
{"id": "adv_economy", "group": "adversarial",
|
||||
"query": "How many zeros are in one trillion?",
|
||||
"expect": [CORE], "forbid": [BIO, HOUSE]},
|
||||
# "fan" inside "fantastic"; also a climate word without a home-control intent.
|
||||
{"id": "adv_fantastic", "group": "adversarial",
|
||||
"query": "That's fantastic. What is 8 squared?",
|
||||
"expect": [CORE], "forbid": [HOUSE, LIB]},
|
||||
# "home" without any actuation intent.
|
||||
{"id": "adv_home_word", "group": "adversarial", "query": "What time do I usually get home?",
|
||||
"expect": [BIO], "forbid": [HOUSE]},
|
||||
# "search" as ordinary English, not a web-search request.
|
||||
{"id": "adv_search_word", "group": "adversarial",
|
||||
"query": "No need to search anything, just tell me what 9 times 9 is.",
|
||||
"expect": [CORE], "forbid": [LIB]},
|
||||
# "create"/"write" are librarian domains but this is conversational.
|
||||
{"id": "adv_write_word", "group": "adversarial", "query": "Can you write that more simply?",
|
||||
"expect": [], "forbid": [LIB, HOUSE]},
|
||||
|
||||
# --- mutating intents: routing only, nothing is ever executed -------------
|
||||
{"id": "mutate_wiki_update", "group": "mutating", "query": "Update the dossier page with today's findings.",
|
||||
"expect": [LIB], "forbid": [HOUSE, CORE]},
|
||||
{"id": "mutate_scene", "group": "mutating", "query": "Run the movie night scene.",
|
||||
"expect": [HOUSE], "forbid": [LIB, BIO, CORE]},
|
||||
]
|
||||
|
||||
|
||||
GROUPS = sorted({f["group"] for f in FIXTURES})
|
||||
|
||||
assert len({f["id"] for f in FIXTURES}) == len(FIXTURES), "duplicate fixture id"
|
||||
@@ -0,0 +1,121 @@
|
||||
"""
|
||||
Guard production's GPU residency across a benchmark run.
|
||||
|
||||
Benchmarks swap models on the card production is serving from. Ollama evicts to
|
||||
make room, so a run leaves its own models resident and the production one gone:
|
||||
the next voice turn pays a ~36s cold load, and the pin that prevented it is
|
||||
silently lost. That happened on 2026-08-08 — a routing benchmark evicted
|
||||
gemma4:e2b and left gemma4:e4b behind, and only the monitoring noticing
|
||||
`unexpected_models` caught it.
|
||||
|
||||
Snapshot before, restore after, and wire the restore to SIGTERM as well as the
|
||||
normal path. Python runs `finally` for SIGINT, which arrives as
|
||||
KeyboardInterrupt, but the default SIGTERM action terminates outright — so
|
||||
`timeout`, a systemd stop or a plain `kill` would skip the guard entirely.
|
||||
|
||||
from scripts.ollama_residency import residency_guard, install_sigterm_handler
|
||||
|
||||
install_sigterm_handler()
|
||||
with residency_guard(models_used=["gemma4:e4b"]):
|
||||
...
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import signal
|
||||
from collections.abc import Iterator
|
||||
from contextlib import contextmanager
|
||||
from datetime import UTC, datetime
|
||||
from typing import Any
|
||||
|
||||
import httpx
|
||||
|
||||
OLLAMA_URL = "http://localhost:11434"
|
||||
|
||||
# keep_alive:-1 yields a year-2318 expiry, so "pinned" is simply "expires more
|
||||
# than a day out". Matches check-ai-pipeline.sh in system-admin-toj.
|
||||
PINNED_THRESHOLD_SECONDS = 86400
|
||||
|
||||
|
||||
def install_sigterm_handler() -> None:
|
||||
"""Make SIGTERM raise, so `finally` blocks and context managers still run."""
|
||||
def _raise(signum, _frame):
|
||||
raise KeyboardInterrupt(f"signal {signum}")
|
||||
|
||||
signal.signal(signal.SIGTERM, _raise)
|
||||
|
||||
|
||||
def snapshot_residency(client: httpx.Client | None = None) -> dict[str, bool]:
|
||||
"""Resident models mapped to whether each is pinned."""
|
||||
owns = client is None
|
||||
client = client or httpx.Client(timeout=30)
|
||||
try:
|
||||
data = client.get(f"{OLLAMA_URL}/api/ps", timeout=10).json()
|
||||
except Exception: # noqa: BLE001 - a missing snapshot must not abort the run
|
||||
return {}
|
||||
finally:
|
||||
if owns:
|
||||
client.close()
|
||||
|
||||
resident: dict[str, bool] = {}
|
||||
now = datetime.now(UTC)
|
||||
for model in data.get("models", []):
|
||||
pinned = False
|
||||
try:
|
||||
expires = datetime.fromisoformat(model.get("expires_at", "").replace("Z", "+00:00"))
|
||||
pinned = (expires - now).total_seconds() > PINNED_THRESHOLD_SECONDS
|
||||
except ValueError:
|
||||
pass
|
||||
resident[model["name"]] = pinned
|
||||
return resident
|
||||
|
||||
|
||||
def set_keep_alive(model: str, keep_alive: Any, client: httpx.Client | None = None) -> bool:
|
||||
"""Load, unload or pin a model. Embedding models reject /api/generate."""
|
||||
owns = client is None
|
||||
client = client or httpx.Client(timeout=180)
|
||||
payload = {"model": model, "keep_alive": keep_alive}
|
||||
try:
|
||||
for endpoint in ("generate", "embed"):
|
||||
try:
|
||||
response = client.post(f"{OLLAMA_URL}/api/{endpoint}", json=payload, timeout=180)
|
||||
except Exception: # noqa: BLE001
|
||||
return False
|
||||
if response.status_code == 200:
|
||||
return True
|
||||
if response.status_code == 400 and "does not support generate" in response.text:
|
||||
continue # embedding-only model; try /api/embed
|
||||
return False
|
||||
return False
|
||||
finally:
|
||||
if owns:
|
||||
client.close()
|
||||
|
||||
|
||||
def restore_residency(before: dict[str, bool], used: list[str]) -> None:
|
||||
"""Evict what the benchmark loaded, then re-pin what was pinned before."""
|
||||
base = {name.split(":")[0] for name in before}
|
||||
with httpx.Client(timeout=180) as client:
|
||||
for model in used:
|
||||
if model not in before and model.split(":")[0] not in base:
|
||||
print(f" residency: unloading benchmark model {model}")
|
||||
set_keep_alive(model, 0, client)
|
||||
for name, pinned in before.items():
|
||||
if not pinned:
|
||||
continue
|
||||
ok = set_keep_alive(name, -1, client)
|
||||
print(f" residency: re-pinned {name}" if ok
|
||||
else f" residency: FAILED to re-pin {name} -- run warmup-ollama.sh")
|
||||
|
||||
|
||||
@contextmanager
|
||||
def residency_guard(models_used: list[str]) -> Iterator[dict[str, bool]]:
|
||||
"""Snapshot residency on entry, restore it on exit however that happens."""
|
||||
before = snapshot_residency()
|
||||
pinned = [n for n, p in before.items() if p]
|
||||
print(f" residency: resident before {sorted(before)}"
|
||||
f"{f' (pinned: {pinned})' if pinned else ''}")
|
||||
try:
|
||||
yield before
|
||||
finally:
|
||||
print(" residency: restoring ...")
|
||||
restore_residency(before, models_used)
|
||||
@@ -3,7 +3,7 @@
|
||||
# Verifies room groups are controlled by checking actual state changes
|
||||
|
||||
API_URL="http://localhost:8777/v1/chat/completions"
|
||||
CORE_API="http://192.168.86.149:8083"
|
||||
CORE_API="http://localhost:8083"
|
||||
RESULTS_FILE="/tmp/housekeeper_test_results.txt"
|
||||
|
||||
GREEN='\033[0;32m'
|
||||
|
||||
@@ -1,407 +0,0 @@
|
||||
"""
|
||||
Multi-agent coordination engine.
|
||||
|
||||
Orchestrates delegation from Tatlock to expert agents (Librarian, etc.)
|
||||
based on Steward recommendations. Handles:
|
||||
- Routing tasks to appropriate agents
|
||||
- Parallel and sequential execution
|
||||
- Result aggregation
|
||||
- Error handling and graceful degradation
|
||||
"""
|
||||
import asyncio
|
||||
import time
|
||||
from typing import Any, AsyncGenerator, Optional
|
||||
|
||||
from src.agents.librarian import run_librarian, run_librarian_stream
|
||||
from src.agents.protocol import (
|
||||
AgentError,
|
||||
AgentRequest,
|
||||
AgentResponse,
|
||||
AgentTimeoutError,
|
||||
AgentUnavailableError,
|
||||
CoordinationResult,
|
||||
DelegationIntent,
|
||||
DelegationReason,
|
||||
ToolCallRecord,
|
||||
)
|
||||
from src.core.household_registry import get_household_registry
|
||||
from src.core.logging_config import get_logger
|
||||
|
||||
logger = get_logger(__name__)
|
||||
|
||||
|
||||
# Agent execution functions registry
|
||||
AGENT_EXECUTORS: dict[str, Any] = {
|
||||
"librarian": run_librarian,
|
||||
}
|
||||
|
||||
AGENT_STREAM_EXECUTORS: dict[str, Any] = {
|
||||
"librarian": run_librarian_stream,
|
||||
}
|
||||
|
||||
|
||||
class CoordinationEngine:
|
||||
"""
|
||||
Coordinates multi-agent task execution.
|
||||
|
||||
Routes tasks from Tatlock to appropriate expert agents,
|
||||
handles execution, and aggregates results.
|
||||
"""
|
||||
|
||||
def __init__(self):
|
||||
"""Initialize the coordination engine."""
|
||||
self.registry = get_household_registry()
|
||||
logger.info("coordination_engine_initialized")
|
||||
|
||||
def get_available_agents(self) -> list[str]:
|
||||
"""
|
||||
Get list of available expert agents.
|
||||
|
||||
Returns:
|
||||
List of agent names that can accept delegations
|
||||
"""
|
||||
available = []
|
||||
for name in self.registry.list_members():
|
||||
member = self.registry.get_member(name)
|
||||
if member and member.agent is not None:
|
||||
available.append(name)
|
||||
return available
|
||||
|
||||
def can_delegate_to(self, agent_name: str) -> bool:
|
||||
"""
|
||||
Check if delegation to an agent is possible.
|
||||
|
||||
Args:
|
||||
agent_name: Name of the target agent
|
||||
|
||||
Returns:
|
||||
True if agent is available and can accept tasks
|
||||
"""
|
||||
if agent_name not in AGENT_EXECUTORS:
|
||||
return False
|
||||
|
||||
member = self.registry.get_member(agent_name)
|
||||
return member is not None and member.agent is not None
|
||||
|
||||
async def execute_delegation(
|
||||
self,
|
||||
intent: DelegationIntent,
|
||||
context: str = "",
|
||||
message_history: Optional[list[Any]] = None,
|
||||
) -> AgentResponse:
|
||||
"""
|
||||
Execute a single delegation to an expert agent.
|
||||
|
||||
Args:
|
||||
intent: The delegation intent with task details
|
||||
context: Additional context for the agent
|
||||
message_history: Optional conversation history
|
||||
|
||||
Returns:
|
||||
AgentResponse with results
|
||||
|
||||
Raises:
|
||||
AgentUnavailableError: If agent is not available
|
||||
AgentTimeoutError: If execution times out
|
||||
AgentError: For other execution errors
|
||||
"""
|
||||
start_time = time.time()
|
||||
agent_name = intent.target_agent
|
||||
|
||||
logger.info(
|
||||
"delegation_started",
|
||||
agent=agent_name,
|
||||
task=intent.task[:100],
|
||||
reason=intent.reason.value,
|
||||
)
|
||||
|
||||
# Check if agent is available
|
||||
if not self.can_delegate_to(agent_name):
|
||||
raise AgentUnavailableError(
|
||||
f"Agent '{agent_name}' is not available for delegation",
|
||||
agent_name=agent_name,
|
||||
)
|
||||
|
||||
# Get the executor
|
||||
executor = AGENT_EXECUTORS.get(agent_name)
|
||||
if not executor:
|
||||
raise AgentUnavailableError(
|
||||
f"No executor found for agent '{agent_name}'",
|
||||
agent_name=agent_name,
|
||||
)
|
||||
|
||||
try:
|
||||
# Build the request
|
||||
request = AgentRequest(
|
||||
task=intent.task,
|
||||
context=context,
|
||||
delegation_reason=intent.reason,
|
||||
)
|
||||
|
||||
# Execute with timeout
|
||||
timeout = request.timeout_seconds or 60
|
||||
|
||||
result = await asyncio.wait_for(
|
||||
executor(
|
||||
task=request.task,
|
||||
context=request.context,
|
||||
message_history=message_history,
|
||||
),
|
||||
timeout=timeout,
|
||||
)
|
||||
|
||||
duration_ms = int((time.time() - start_time) * 1000)
|
||||
|
||||
logger.info(
|
||||
"delegation_completed",
|
||||
agent=agent_name,
|
||||
duration_ms=duration_ms,
|
||||
output_length=len(result),
|
||||
)
|
||||
|
||||
return AgentResponse(
|
||||
success=True,
|
||||
result=result,
|
||||
reasoning=f"Delegated to {agent_name}: {intent.expected_outcome}",
|
||||
duration_ms=duration_ms,
|
||||
)
|
||||
|
||||
except asyncio.TimeoutError:
|
||||
duration_ms = int((time.time() - start_time) * 1000)
|
||||
logger.error(
|
||||
"delegation_timeout",
|
||||
agent=agent_name,
|
||||
duration_ms=duration_ms,
|
||||
)
|
||||
raise AgentTimeoutError(
|
||||
f"Agent '{agent_name}' timed out after {duration_ms}ms",
|
||||
agent_name=agent_name,
|
||||
)
|
||||
|
||||
except Exception as e:
|
||||
duration_ms = int((time.time() - start_time) * 1000)
|
||||
logger.error(
|
||||
"delegation_error",
|
||||
agent=agent_name,
|
||||
error=str(e),
|
||||
duration_ms=duration_ms,
|
||||
exc_info=True,
|
||||
)
|
||||
return AgentResponse(
|
||||
success=False,
|
||||
result="",
|
||||
error_message=str(e),
|
||||
duration_ms=duration_ms,
|
||||
)
|
||||
|
||||
async def execute_delegation_stream(
|
||||
self,
|
||||
intent: DelegationIntent,
|
||||
context: str = "",
|
||||
message_history: Optional[list[Any]] = None,
|
||||
) -> AsyncGenerator[str, None]:
|
||||
"""
|
||||
Execute a delegation with streaming output.
|
||||
|
||||
Args:
|
||||
intent: The delegation intent with task details
|
||||
context: Additional context for the agent
|
||||
message_history: Optional conversation history
|
||||
|
||||
Yields:
|
||||
Text deltas from the agent
|
||||
|
||||
Raises:
|
||||
AgentUnavailableError: If agent is not available
|
||||
"""
|
||||
agent_name = intent.target_agent
|
||||
|
||||
logger.info(
|
||||
"delegation_stream_started",
|
||||
agent=agent_name,
|
||||
task=intent.task[:100],
|
||||
)
|
||||
|
||||
# Check if agent is available
|
||||
if agent_name not in AGENT_STREAM_EXECUTORS:
|
||||
raise AgentUnavailableError(
|
||||
f"Agent '{agent_name}' does not support streaming",
|
||||
agent_name=agent_name,
|
||||
)
|
||||
|
||||
executor = AGENT_STREAM_EXECUTORS[agent_name]
|
||||
|
||||
try:
|
||||
async for delta in executor(
|
||||
task=intent.task,
|
||||
context=context,
|
||||
message_history=message_history,
|
||||
):
|
||||
yield delta
|
||||
|
||||
logger.info("delegation_stream_completed", agent=agent_name)
|
||||
|
||||
except Exception as e:
|
||||
logger.error(
|
||||
"delegation_stream_error",
|
||||
agent=agent_name,
|
||||
error=str(e),
|
||||
exc_info=True,
|
||||
)
|
||||
yield f"\n\n[Error from {agent_name}: {str(e)}]"
|
||||
|
||||
async def coordinate(
|
||||
self,
|
||||
intents: list[DelegationIntent],
|
||||
context: str = "",
|
||||
message_history: Optional[list[Any]] = None,
|
||||
) -> CoordinationResult:
|
||||
"""
|
||||
Coordinate execution of multiple delegations.
|
||||
|
||||
Handles parallel execution for independent tasks and
|
||||
sequential execution for dependent tasks.
|
||||
|
||||
Args:
|
||||
intents: List of delegation intents to execute
|
||||
context: Shared context for all agents
|
||||
message_history: Optional conversation history
|
||||
|
||||
Returns:
|
||||
CoordinationResult with aggregated results
|
||||
"""
|
||||
start_time = time.time()
|
||||
agent_responses: dict[str, AgentResponse] = {}
|
||||
agents_consulted: list[str] = []
|
||||
|
||||
logger.info(
|
||||
"coordination_started",
|
||||
intent_count=len(intents),
|
||||
agents=[i.target_agent for i in intents],
|
||||
)
|
||||
|
||||
# Sort by priority
|
||||
sorted_intents = sorted(intents, key=lambda x: x.priority)
|
||||
|
||||
# Group by dependencies (simple version: sequential for now)
|
||||
# TODO: Implement parallel execution for independent tasks
|
||||
for intent in sorted_intents:
|
||||
try:
|
||||
response = await self.execute_delegation(
|
||||
intent=intent,
|
||||
context=context,
|
||||
message_history=message_history,
|
||||
)
|
||||
agent_responses[intent.target_agent] = response
|
||||
if response.success:
|
||||
agents_consulted.append(intent.target_agent)
|
||||
|
||||
except AgentError as e:
|
||||
agent_responses[intent.target_agent] = AgentResponse(
|
||||
success=False,
|
||||
result="",
|
||||
error_message=str(e),
|
||||
)
|
||||
|
||||
# Aggregate results
|
||||
successful_results = [
|
||||
r.result for r in agent_responses.values() if r.success and r.result
|
||||
]
|
||||
|
||||
final_response = "\n\n---\n\n".join(successful_results) if successful_results else ""
|
||||
|
||||
total_duration = int((time.time() - start_time) * 1000)
|
||||
|
||||
logger.info(
|
||||
"coordination_completed",
|
||||
total_duration_ms=total_duration,
|
||||
agents_consulted=agents_consulted,
|
||||
success_count=len(successful_results),
|
||||
)
|
||||
|
||||
return CoordinationResult(
|
||||
final_response=final_response,
|
||||
agent_responses=agent_responses,
|
||||
delegation_intents=intents,
|
||||
total_duration_ms=total_duration,
|
||||
agents_consulted=agents_consulted,
|
||||
)
|
||||
|
||||
|
||||
# Global coordination engine instance
|
||||
_coordination_engine: Optional[CoordinationEngine] = None
|
||||
|
||||
|
||||
def get_coordination_engine() -> CoordinationEngine:
|
||||
"""Get the global coordination engine instance."""
|
||||
global _coordination_engine
|
||||
if _coordination_engine is None:
|
||||
_coordination_engine = CoordinationEngine()
|
||||
return _coordination_engine
|
||||
|
||||
|
||||
async def delegate_to_librarian(
|
||||
task: str,
|
||||
context: str = "",
|
||||
reason: DelegationReason = DelegationReason.DOMAIN_EXPERTISE,
|
||||
message_history: Optional[list[Any]] = None,
|
||||
) -> AgentResponse:
|
||||
"""
|
||||
Convenience function to delegate a task to The Librarian.
|
||||
|
||||
Args:
|
||||
task: Research task description
|
||||
context: Additional context
|
||||
reason: Why delegating to Librarian
|
||||
message_history: Optional conversation history
|
||||
|
||||
Returns:
|
||||
AgentResponse with research results
|
||||
"""
|
||||
engine = get_coordination_engine()
|
||||
|
||||
intent = DelegationIntent(
|
||||
target_agent="librarian",
|
||||
task=task,
|
||||
reason=reason,
|
||||
expected_outcome="Research findings and relevant information",
|
||||
)
|
||||
|
||||
return await engine.execute_delegation(
|
||||
intent=intent,
|
||||
context=context,
|
||||
message_history=message_history,
|
||||
)
|
||||
|
||||
|
||||
async def delegate_to_librarian_stream(
|
||||
task: str,
|
||||
context: str = "",
|
||||
message_history: Optional[list[Any]] = None,
|
||||
) -> AsyncGenerator[str, None]:
|
||||
"""
|
||||
Convenience function to delegate to Librarian with streaming.
|
||||
|
||||
Args:
|
||||
task: Research task description
|
||||
context: Additional context
|
||||
message_history: Optional conversation history
|
||||
|
||||
Yields:
|
||||
Text deltas from The Librarian
|
||||
"""
|
||||
engine = get_coordination_engine()
|
||||
|
||||
intent = DelegationIntent(
|
||||
target_agent="librarian",
|
||||
task=task,
|
||||
reason=DelegationReason.DOMAIN_EXPERTISE,
|
||||
expected_outcome="Research findings",
|
||||
)
|
||||
|
||||
async for delta in engine.execute_delegation_stream(
|
||||
intent=intent,
|
||||
context=context,
|
||||
message_history=message_history,
|
||||
):
|
||||
yield delta
|
||||
+96
-111
@@ -8,12 +8,13 @@ returns a structured result for synthesis.
|
||||
This implements the agent-as-tool pattern recommended by PydanticAI:
|
||||
agents call other agents via tool wrappers, keeping each agent focused.
|
||||
"""
|
||||
import asyncio
|
||||
from dataclasses import dataclass, field
|
||||
from enum import Enum
|
||||
from typing import AsyncGenerator, Callable, Optional, Any
|
||||
|
||||
from src.core.config import config
|
||||
from src.core.logging_config import get_logger
|
||||
from src.core.tracing import trace_span, SpanType
|
||||
from src.core.tracing import SpanType, trace_span
|
||||
|
||||
logger = get_logger(__name__)
|
||||
|
||||
@@ -126,6 +127,50 @@ def _detect_action_type(expert: str, task: str) -> ActionType:
|
||||
return ActionType.RETRIEVE
|
||||
|
||||
|
||||
def build_delegation_context(
|
||||
conversation_history: list[dict] | None,
|
||||
max_turns: int = 6,
|
||||
max_chars_per_turn: int = 500,
|
||||
) -> str:
|
||||
"""
|
||||
Format the most recent conversation turns as delegation context.
|
||||
|
||||
Experts accept a context string but the live paths never passed the
|
||||
in-scope conversation history; this trims it to the last few turns
|
||||
so follow-up questions ("and what about X?") keep their referent.
|
||||
|
||||
Args:
|
||||
conversation_history: Prior messages as {"role", "content"} dicts
|
||||
max_turns: How many trailing turns to include
|
||||
max_chars_per_turn: Truncation limit per turn
|
||||
|
||||
Returns:
|
||||
str: Newline-joined "role: content" lines ("" when no history)
|
||||
"""
|
||||
if not conversation_history:
|
||||
return ""
|
||||
|
||||
lines = []
|
||||
for msg in conversation_history[-max_turns:]:
|
||||
if not isinstance(msg, dict):
|
||||
continue
|
||||
role = msg.get("role", "user")
|
||||
content = msg.get("content", "")
|
||||
if isinstance(content, list):
|
||||
# Tolerate structured content parts
|
||||
content = " ".join(
|
||||
part.get("text", "") if isinstance(part, dict) else str(part)
|
||||
for part in content
|
||||
)
|
||||
content = str(content).strip()
|
||||
if content:
|
||||
lines.append(f"{role}: {content[:max_chars_per_turn]}")
|
||||
|
||||
if not lines:
|
||||
return ""
|
||||
return "Recent conversation:\n" + "\n".join(lines)
|
||||
|
||||
|
||||
def get_think_message(expert: str, task: str, phase: str) -> str:
|
||||
"""
|
||||
Get the appropriate think message for an expert delegation.
|
||||
@@ -167,7 +212,7 @@ class DelegationTask:
|
||||
action: str = ""
|
||||
priority: int = 0
|
||||
depends_on: list[str] = field(default_factory=list)
|
||||
result: Optional[str] = None
|
||||
result: str | None = None
|
||||
task_id: str = ""
|
||||
|
||||
def __post_init__(self):
|
||||
@@ -186,14 +231,16 @@ class DelegationResult:
|
||||
expert_name: Which expert handled the task
|
||||
task: Original task description
|
||||
success: Whether the delegation succeeded
|
||||
output: Expert's response/findings
|
||||
error: Error message if failed
|
||||
output: Expert's response/findings. On failure this holds a
|
||||
curated, user-safe butler sentence (never exception detail)
|
||||
error: Short user-safe error label if failed. Exception detail
|
||||
stays in the logs only
|
||||
"""
|
||||
expert_name: str
|
||||
task: str
|
||||
success: bool
|
||||
output: str
|
||||
error: Optional[str] = None
|
||||
error: str | None = None
|
||||
|
||||
|
||||
async def delegate_to_librarian(
|
||||
@@ -250,8 +297,14 @@ async def delegate_to_librarian(
|
||||
},
|
||||
) as span:
|
||||
try:
|
||||
# Use run() not run_stream() - avoids Ollama bug
|
||||
output = await run_librarian(task=task, context=context)
|
||||
# Use run() not run_stream() - avoids Ollama bug.
|
||||
# One timeout budget for the whole delegation - covers both
|
||||
# live paths (steward direct delegation and streaming), which
|
||||
# previously had no cap at all (SDK default ~600s per LLM call).
|
||||
output = await asyncio.wait_for(
|
||||
run_librarian(task=task, context=context),
|
||||
timeout=config.LIBRARIAN_TIMEOUT,
|
||||
)
|
||||
|
||||
logger.info(
|
||||
"delegation_to_librarian_completed",
|
||||
@@ -273,6 +326,30 @@ async def delegate_to_librarian(
|
||||
output=output,
|
||||
)
|
||||
|
||||
except TimeoutError:
|
||||
logger.error(
|
||||
"delegation_to_librarian_timeout",
|
||||
task=task[:50],
|
||||
timeout_seconds=config.LIBRARIAN_TIMEOUT,
|
||||
)
|
||||
|
||||
if span:
|
||||
span.metadata["success"] = False
|
||||
span.details["error"] = (
|
||||
f"timed out after {config.LIBRARIAN_TIMEOUT}s"
|
||||
)
|
||||
|
||||
return DelegationResult(
|
||||
expert_name="librarian",
|
||||
task=task,
|
||||
success=False,
|
||||
output=(
|
||||
"I'm afraid the research took longer than expected "
|
||||
"and had to be abandoned, sir."
|
||||
),
|
||||
error="The Librarian did not respond within the time budget.",
|
||||
)
|
||||
|
||||
except Exception as e:
|
||||
logger.error(
|
||||
"delegation_to_librarian_error",
|
||||
@@ -285,12 +362,15 @@ async def delegate_to_librarian(
|
||||
span.metadata["success"] = False
|
||||
span.details["error"] = str(e)
|
||||
|
||||
# Exception detail stays in the logs; the user-facing output
|
||||
# is a curated butler sentence so internals never leak into
|
||||
# synthesis.
|
||||
return DelegationResult(
|
||||
expert_name="librarian",
|
||||
task=task,
|
||||
success=False,
|
||||
output="",
|
||||
error=str(e),
|
||||
output=get_think_message("librarian", task, "error"),
|
||||
error="The Librarian was unable to complete the task.",
|
||||
)
|
||||
|
||||
|
||||
@@ -383,12 +463,13 @@ async def delegate_to_biographer(
|
||||
span.metadata["success"] = False
|
||||
span.details["error"] = str(e)
|
||||
|
||||
# Exception detail stays in the logs only.
|
||||
return DelegationResult(
|
||||
expert_name="biographer",
|
||||
task=task,
|
||||
success=False,
|
||||
output="",
|
||||
error=str(e),
|
||||
output=get_think_message("biographer", task, "error"),
|
||||
error="The Biographer was unable to complete the task.",
|
||||
)
|
||||
|
||||
|
||||
@@ -480,112 +561,16 @@ async def delegate_to_housekeeper(
|
||||
span.metadata["success"] = False
|
||||
span.details["error"] = str(e)
|
||||
|
||||
# Exception detail stays in the logs only.
|
||||
return DelegationResult(
|
||||
expert_name="housekeeper",
|
||||
task=task,
|
||||
success=False,
|
||||
output="",
|
||||
error=str(e),
|
||||
output=get_think_message("housekeeper", task, "error"),
|
||||
error="The Housekeeper was unable to complete the task.",
|
||||
)
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Streaming Delegation Wrappers (with Think Messages)
|
||||
# =============================================================================
|
||||
|
||||
async def stream_delegate_to_librarian(
|
||||
task: str,
|
||||
context: str = "",
|
||||
) -> AsyncGenerator[str, None]:
|
||||
"""
|
||||
Stream delegation to Librarian with automatic think messages.
|
||||
|
||||
Yields butler-perspective think messages before and after the delegation,
|
||||
allowing the UI to show progress to the user.
|
||||
|
||||
Args:
|
||||
task: Task description
|
||||
context: Additional context
|
||||
|
||||
Yields:
|
||||
str: Think messages and final result marker
|
||||
"""
|
||||
# Yield start message (deterministic)
|
||||
yield get_think_message("librarian", task, "start") + "\n"
|
||||
|
||||
# Execute delegation
|
||||
result = await delegate_to_librarian(task, context)
|
||||
|
||||
# Yield completion message (deterministic)
|
||||
if result.success:
|
||||
yield get_think_message("librarian", task, "success") + "\n"
|
||||
else:
|
||||
yield get_think_message("librarian", task, "error") + "\n"
|
||||
|
||||
# Yield result marker for extraction
|
||||
yield f"__DELEGATION_RESULT__:librarian:{result.output}"
|
||||
|
||||
|
||||
async def stream_delegate_to_biographer(
|
||||
task: str,
|
||||
context: str = "",
|
||||
) -> AsyncGenerator[str, None]:
|
||||
"""
|
||||
Stream delegation to Biographer with automatic think messages.
|
||||
|
||||
Args:
|
||||
task: Task description
|
||||
context: Additional context
|
||||
|
||||
Yields:
|
||||
str: Think messages and final result marker
|
||||
"""
|
||||
yield get_think_message("biographer", task, "start") + "\n"
|
||||
|
||||
result = await delegate_to_biographer(task, context)
|
||||
|
||||
if result.success:
|
||||
yield get_think_message("biographer", task, "success") + "\n"
|
||||
else:
|
||||
yield get_think_message("biographer", task, "error") + "\n"
|
||||
|
||||
yield f"__DELEGATION_RESULT__:biographer:{result.output}"
|
||||
|
||||
|
||||
async def stream_delegate_to_housekeeper(
|
||||
task: str,
|
||||
context: str = "",
|
||||
) -> AsyncGenerator[str, None]:
|
||||
"""
|
||||
Stream delegation to Housekeeper with automatic think messages.
|
||||
|
||||
Args:
|
||||
task: Task description
|
||||
context: Additional context
|
||||
|
||||
Yields:
|
||||
str: Think messages and final result marker
|
||||
"""
|
||||
yield get_think_message("housekeeper", task, "start") + "\n"
|
||||
|
||||
result = await delegate_to_housekeeper(task, context)
|
||||
|
||||
if result.success:
|
||||
yield get_think_message("housekeeper", task, "success") + "\n"
|
||||
else:
|
||||
yield get_think_message("housekeeper", task, "error") + "\n"
|
||||
|
||||
yield f"__DELEGATION_RESULT__:housekeeper:{result.output}"
|
||||
|
||||
|
||||
# Mapping of streaming delegation wrappers
|
||||
STREAMING_DELEGATION_WRAPPERS = {
|
||||
"librarian": stream_delegate_to_librarian,
|
||||
"biographer": stream_delegate_to_biographer,
|
||||
"housekeeper": stream_delegate_to_housekeeper,
|
||||
}
|
||||
|
||||
|
||||
# Future expert delegation wrappers will be added here:
|
||||
# - delegate_to_developer(task, context) -> DelegationResult
|
||||
# - delegate_to_secretary(task, context) -> DelegationResult
|
||||
|
||||
@@ -204,13 +204,13 @@ async def run_housekeeper(
|
||||
)
|
||||
|
||||
try:
|
||||
# Use temperature 0.1 for slight exploration
|
||||
from pydantic_ai.settings import ModelSettings
|
||||
# Temperature 0.1 for slight exploration (skipped on Claude backend)
|
||||
from src.anthropic.model_selector import get_sampling_settings
|
||||
|
||||
result = await agent.run(
|
||||
prompt,
|
||||
message_history=message_history,
|
||||
model_settings=ModelSettings(temperature=0.1),
|
||||
model_settings=get_sampling_settings(0.1),
|
||||
)
|
||||
|
||||
logger.info(
|
||||
@@ -266,13 +266,13 @@ async def run_housekeeper_stream(
|
||||
)
|
||||
|
||||
try:
|
||||
# Use temperature 0.1 for slight exploration
|
||||
from pydantic_ai.settings import ModelSettings
|
||||
# Temperature 0.1 for slight exploration (skipped on Claude backend)
|
||||
from src.anthropic.model_selector import get_sampling_settings
|
||||
|
||||
async with agent.run_stream(
|
||||
prompt,
|
||||
message_history=message_history,
|
||||
model_settings=ModelSettings(temperature=0.1),
|
||||
model_settings=get_sampling_settings(0.1),
|
||||
) as response:
|
||||
async for delta in response.stream_text(delta=True):
|
||||
yield delta
|
||||
|
||||
@@ -10,7 +10,6 @@ Connects to the library-desk API to provide:
|
||||
from src.agents.librarian.agent import (
|
||||
get_librarian_agent,
|
||||
run_librarian,
|
||||
run_librarian_stream,
|
||||
)
|
||||
from src.agents.librarian.capability import (
|
||||
LIBRARIAN_CAPABILITY,
|
||||
@@ -26,5 +25,4 @@ __all__ = [
|
||||
"register_librarian",
|
||||
"unregister_librarian",
|
||||
"run_librarian",
|
||||
"run_librarian_stream",
|
||||
]
|
||||
|
||||
@@ -7,10 +7,11 @@ the library-desk API, offering:
|
||||
- Wiki and document management
|
||||
- Semantic search and knowledge graph exploration
|
||||
"""
|
||||
from typing import Any, Optional
|
||||
from typing import Any
|
||||
|
||||
from pydantic_ai import Agent
|
||||
|
||||
from src.agents.librarian.client import library_client_session
|
||||
from src.agents.librarian.tools import (
|
||||
create_wiki_page,
|
||||
explore_knowledge_graph,
|
||||
@@ -27,7 +28,7 @@ from src.agents.librarian.tools import (
|
||||
smart_create_wiki_page,
|
||||
update_wiki_page,
|
||||
)
|
||||
from src.core.config import config
|
||||
from src.agents.protocol import AgentError
|
||||
from src.core.logging_config import get_logger
|
||||
|
||||
logger = get_logger(__name__)
|
||||
@@ -137,8 +138,32 @@ If a tool fails or you cannot access a data source:
|
||||
- It is better to return no information than to return fabricated information
|
||||
"""
|
||||
|
||||
|
||||
# Tool-phase prompt actually used by the agent. The scholarly persona prompt
|
||||
# above suppresses tool calling on small local models (gemma4 answers in
|
||||
# character - "please provide your request" - without ever calling a tool),
|
||||
# the same pathology TATLOCK_ORCHESTRATION_PROMPT fixed for the butler.
|
||||
# Tatlock's synthesis phase supplies the user-facing voice, so the research
|
||||
# phase only needs tool discipline. Kept: the anti-fabrication rule.
|
||||
LIBRARIAN_TASK_PROMPT = """You are The Librarian, the research executor of the \
|
||||
Tatlock household. Your only job is to gather accurate findings by calling the \
|
||||
provided tools.
|
||||
|
||||
- ALWAYS use tools - never answer a research task from memory alone.
|
||||
- Research or wiki questions: call hybrid_search first; then search_wiki and \
|
||||
get_wiki_page to read specific pages BEFORE summarizing them.
|
||||
- Current or external information (weather, news, live facts): call search_web; \
|
||||
call read_url when given a specific URL.
|
||||
- Wiki writing: smart_create_wiki_page when asked for a page about a topic; \
|
||||
create_wiki_page only for user-provided verbatim content; update_wiki_page for \
|
||||
edits (search_wiki, then get_wiki_page, then update).
|
||||
- Reply with a concise factual summary of what the tools returned, citing page \
|
||||
titles and URLs. A later step writes the polished answer, so no personality.
|
||||
- NEVER fabricate. If a tool fails or returns nothing, state exactly what you \
|
||||
could not retrieve and stop."""
|
||||
|
||||
# Lazy initialization to avoid connection issues during imports
|
||||
_librarian_agent: Optional[Agent[None, str]] = None
|
||||
_librarian_agent: Agent[None, str] | None = None
|
||||
|
||||
|
||||
def _create_librarian_agent() -> Agent[None, str]:
|
||||
@@ -150,7 +175,7 @@ def _create_librarian_agent() -> Agent[None, str]:
|
||||
|
||||
agent: Agent[None, str] = Agent(
|
||||
model=model,
|
||||
system_prompt=LIBRARIAN_SYSTEM_PROMPT,
|
||||
system_prompt=LIBRARIAN_TASK_PROMPT,
|
||||
retries=2,
|
||||
)
|
||||
|
||||
@@ -204,7 +229,7 @@ def get_librarian_agent() -> Agent[None, str]:
|
||||
async def run_librarian(
|
||||
task: str,
|
||||
context: str = "",
|
||||
message_history: Optional[list[Any]] = None,
|
||||
message_history: list[Any] | None = None,
|
||||
) -> str:
|
||||
"""
|
||||
Execute a research task with The Librarian.
|
||||
@@ -220,6 +245,10 @@ async def run_librarian(
|
||||
Returns:
|
||||
Research results and findings
|
||||
|
||||
Raises:
|
||||
AgentError: If the research task fails. Exception detail is
|
||||
logged here; callers map the failure to a user-safe message.
|
||||
|
||||
Example:
|
||||
result = await run_librarian(
|
||||
task="Find information about Docker networking",
|
||||
@@ -241,6 +270,8 @@ async def run_librarian(
|
||||
)
|
||||
|
||||
try:
|
||||
# One shared library-desk connection for all tool calls in this run
|
||||
async with library_client_session():
|
||||
result = await agent.run(
|
||||
prompt,
|
||||
message_history=message_history,
|
||||
@@ -255,64 +286,14 @@ async def run_librarian(
|
||||
return result.output
|
||||
|
||||
except Exception as e:
|
||||
# Full detail stays in the logs; callers receive a structured
|
||||
# failure instead of error text masquerading as research output.
|
||||
logger.error(
|
||||
"librarian_task_error",
|
||||
task=task[:50],
|
||||
error=str(e),
|
||||
exc_info=True,
|
||||
)
|
||||
return f"The Librarian encountered an error: {str(e)}"
|
||||
|
||||
|
||||
async def run_librarian_stream(
|
||||
task: str,
|
||||
context: str = "",
|
||||
message_history: Optional[list[Any]] = None,
|
||||
):
|
||||
"""
|
||||
Execute a research task with streaming output.
|
||||
|
||||
Yields text deltas as The Librarian generates the response.
|
||||
|
||||
Args:
|
||||
task: The research task or question
|
||||
context: Additional context from conversation
|
||||
message_history: Optional conversation history
|
||||
|
||||
Yields:
|
||||
str: Text deltas from the response
|
||||
|
||||
Example:
|
||||
async for delta in run_librarian_stream("Find Docker docs"):
|
||||
print(delta, end="", flush=True)
|
||||
"""
|
||||
agent = get_librarian_agent()
|
||||
|
||||
# Build prompt with context if provided
|
||||
prompt = task
|
||||
if context:
|
||||
prompt = f"Context: {context}\n\nTask: {task}"
|
||||
|
||||
logger.info(
|
||||
"librarian_stream_started",
|
||||
task=task[:100],
|
||||
)
|
||||
|
||||
try:
|
||||
async with agent.run_stream(
|
||||
prompt,
|
||||
message_history=message_history,
|
||||
) as response:
|
||||
async for delta in response.stream_text(delta=True):
|
||||
yield delta
|
||||
|
||||
logger.info("librarian_stream_completed", task=task[:50])
|
||||
|
||||
except Exception as e:
|
||||
logger.error(
|
||||
"librarian_stream_error",
|
||||
task=task[:50],
|
||||
error=str(e),
|
||||
exc_info=True,
|
||||
)
|
||||
yield f"\n\nThe Librarian encountered an error: {str(e)}"
|
||||
raise AgentError(
|
||||
"Research task failed", agent_name="librarian"
|
||||
) from e
|
||||
|
||||
+277
-76
@@ -7,17 +7,32 @@ Provides async methods for all relevant library-desk endpoints:
|
||||
- Vector search
|
||||
- Knowledge graph queries
|
||||
"""
|
||||
from typing import Any, Optional
|
||||
import asyncio
|
||||
from collections.abc import AsyncIterator, Awaitable, Callable
|
||||
from contextlib import asynccontextmanager
|
||||
from contextvars import ContextVar
|
||||
from typing import Any
|
||||
|
||||
import httpx
|
||||
from pydantic import BaseModel, Field
|
||||
|
||||
from src.core.config import config
|
||||
from src.core.context import get_user
|
||||
from src.core.context import apply_tenant_guard, get_user
|
||||
from src.core.logging_config import get_logger
|
||||
|
||||
logger = get_logger(__name__)
|
||||
|
||||
# Retry policy for idempotent/read-only requests (GETs, POST /query/*,
|
||||
# POST /rag/search). Writes are never retried.
|
||||
_RETRY_ATTEMPTS = 2
|
||||
_RETRY_BACKOFF_SECONDS = 0.5
|
||||
_RETRYABLE_STATUS_CODES = {502, 503, 504}
|
||||
|
||||
# One shared HTTP connection per librarian run (see library_client_session)
|
||||
_shared_http_client: ContextVar[httpx.AsyncClient | None] = ContextVar(
|
||||
"library_desk_http_client", default=None
|
||||
)
|
||||
|
||||
|
||||
# ============================================================================
|
||||
# Response Models
|
||||
@@ -28,11 +43,11 @@ class WikiPage(BaseModel):
|
||||
id: int
|
||||
path: str
|
||||
title: str
|
||||
description: Optional[str] = None
|
||||
content: Optional[str] = None
|
||||
description: str | None = None
|
||||
content: str | None = None
|
||||
tags: list[str] = Field(default_factory=list)
|
||||
created_at: Optional[str] = None
|
||||
updated_at: Optional[str] = None
|
||||
created_at: str | None = None
|
||||
updated_at: str | None = None
|
||||
|
||||
|
||||
class WikiSearchResult(BaseModel):
|
||||
@@ -40,8 +55,8 @@ class WikiSearchResult(BaseModel):
|
||||
id: int
|
||||
path: str
|
||||
title: str
|
||||
description: Optional[str] = None
|
||||
locale: Optional[str] = None
|
||||
description: str | None = None
|
||||
locale: str | None = None
|
||||
|
||||
|
||||
class VectorSearchResult(BaseModel):
|
||||
@@ -56,12 +71,14 @@ class VectorSearchResult(BaseModel):
|
||||
|
||||
class HybridSearchResult(BaseModel):
|
||||
"""Result from HybridRAG search."""
|
||||
source: str # "vector", "graph", "web"
|
||||
source: str # source_type: "wiki", "web", "volatile", "document"
|
||||
sources: list[str] = Field(default_factory=list) # legs that found it: "vector", "graph", "web", ...
|
||||
title: str
|
||||
content: str
|
||||
url: Optional[str] = None
|
||||
score: float
|
||||
page_id: Optional[int] = None
|
||||
url: str | None = None
|
||||
score: float # rrf_score from the live service
|
||||
page_id: int | None = None
|
||||
related_dossiers: list[dict[str, Any]] = Field(default_factory=list)
|
||||
metadata: dict[str, Any] = Field(default_factory=dict)
|
||||
|
||||
|
||||
@@ -72,8 +89,15 @@ class HybridRAGResponse(BaseModel):
|
||||
synonyms: list[str] = Field(default_factory=list)
|
||||
related_dossiers: list[str] = Field(default_factory=list)
|
||||
formatted_context: str = ""
|
||||
search_id: Optional[str] = None
|
||||
search_id: str | None = None
|
||||
source_counts: dict[str, int] = Field(default_factory=dict)
|
||||
timing: dict[str, float] = Field(default_factory=dict)
|
||||
# Additive degradation contract - only newer library-desk versions
|
||||
# send these; absence means "no status reported", not "healthy".
|
||||
# Maps each leg (vector/graph/web/volatile/documents) to
|
||||
# "ok" | "failed" | "disabled".
|
||||
source_status: dict[str, str] = Field(default_factory=dict)
|
||||
degraded: bool = False
|
||||
|
||||
|
||||
class GraphNode(BaseModel):
|
||||
@@ -105,7 +129,7 @@ class WebSearchResult(BaseModel):
|
||||
content: str = "" # Full extracted text via Trafilatura
|
||||
snippet: str = "" # Original search engine snippet
|
||||
source: str = "" # Domain name
|
||||
published_date: Optional[str] = None
|
||||
published_date: str | None = None
|
||||
|
||||
|
||||
class WebSearchResponse(BaseModel):
|
||||
@@ -121,13 +145,13 @@ class WebSearchResponse(BaseModel):
|
||||
class ContentExtractionResult(BaseModel):
|
||||
"""Result from content extraction."""
|
||||
url: str
|
||||
title: Optional[str] = None
|
||||
title: str | None = None
|
||||
content: str = ""
|
||||
author: Optional[str] = None
|
||||
date: Optional[str] = None
|
||||
language: Optional[str] = None
|
||||
author: str | None = None
|
||||
date: str | None = None
|
||||
language: str | None = None
|
||||
success: bool = True
|
||||
error: Optional[str] = None
|
||||
error: str | None = None
|
||||
|
||||
|
||||
class BatchExtractionResponse(BaseModel):
|
||||
@@ -151,7 +175,7 @@ class SmartCreateResponse(BaseModel):
|
||||
page: WikiPage
|
||||
research_summary: ResearchSummary = Field(default_factory=ResearchSummary)
|
||||
sources_used: int = 0
|
||||
search_id: Optional[str] = None
|
||||
search_id: str | None = None
|
||||
entity_linking: EntityLinking = Field(default_factory=EntityLinking)
|
||||
|
||||
|
||||
@@ -170,9 +194,9 @@ class LibraryDeskClient:
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
base_url: Optional[str] = None,
|
||||
api_key: Optional[str] = None,
|
||||
timeout: int = 60,
|
||||
base_url: str | None = None,
|
||||
api_key: str | None = None,
|
||||
timeout: int | None = None,
|
||||
):
|
||||
"""
|
||||
Initialize the client.
|
||||
@@ -181,30 +205,55 @@ class LibraryDeskClient:
|
||||
base_url: Library-desk API URL (defaults to config)
|
||||
api_key: API key for authentication (defaults to config)
|
||||
timeout: Request timeout in seconds
|
||||
(defaults to config.LIBRARY_DESK_TIMEOUT)
|
||||
"""
|
||||
self.base_url = base_url or str(config.LIBRARY_DESK_HOST)
|
||||
self.api_key = api_key or config.LIBRARY_DESK_API_KEY
|
||||
self.timeout = timeout
|
||||
self._client: Optional[httpx.AsyncClient] = None
|
||||
self.timeout = timeout if timeout is not None else config.LIBRARY_DESK_TIMEOUT
|
||||
self._client: httpx.AsyncClient | None = None
|
||||
self._owns_client = False
|
||||
|
||||
async def __aenter__(self) -> "LibraryDeskClient":
|
||||
"""Create HTTP client on context entry."""
|
||||
def _build_http_client(self) -> httpx.AsyncClient:
|
||||
"""Build a configured httpx client."""
|
||||
headers = {}
|
||||
if self.api_key:
|
||||
headers["Authorization"] = f"Bearer {self.api_key}"
|
||||
|
||||
self._client = httpx.AsyncClient(
|
||||
return httpx.AsyncClient(
|
||||
base_url=self.base_url,
|
||||
headers=headers,
|
||||
timeout=self.timeout,
|
||||
)
|
||||
|
||||
def _uses_default_target(self) -> bool:
|
||||
"""Whether this client targets the configured library-desk instance."""
|
||||
return (
|
||||
self.base_url == str(config.LIBRARY_DESK_HOST)
|
||||
and self.api_key == config.LIBRARY_DESK_API_KEY
|
||||
)
|
||||
|
||||
async def __aenter__(self) -> "LibraryDeskClient":
|
||||
"""
|
||||
Acquire an HTTP client on context entry.
|
||||
|
||||
Reuses the run-level shared connection (see library_client_session)
|
||||
when one is active, instead of constructing a new client per call.
|
||||
"""
|
||||
shared = _shared_http_client.get()
|
||||
if shared is not None and not shared.is_closed and self._uses_default_target():
|
||||
self._client = shared
|
||||
self._owns_client = False
|
||||
else:
|
||||
self._client = self._build_http_client()
|
||||
self._owns_client = True
|
||||
return self
|
||||
|
||||
async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
|
||||
"""Close HTTP client on context exit."""
|
||||
if self._client:
|
||||
"""Close HTTP client on context exit (only if we own it)."""
|
||||
if self._client and self._owns_client:
|
||||
await self._client.aclose()
|
||||
self._client = None
|
||||
self._owns_client = False
|
||||
|
||||
def _ensure_client(self) -> httpx.AsyncClient:
|
||||
"""Ensure client is initialized."""
|
||||
@@ -214,6 +263,69 @@ class LibraryDeskClient:
|
||||
)
|
||||
return self._client
|
||||
|
||||
def _resolve_user(self, user: str | None) -> str:
|
||||
"""
|
||||
Resolve the effective tenant for a request and require it non-empty.
|
||||
|
||||
Library-desk is removing its server-side default user, so every
|
||||
request must carry an explicit tenant (a missing user will 422).
|
||||
An empty tenant is a programming or configuration error - fail
|
||||
loudly here, before any bytes hit the wire.
|
||||
|
||||
Explicit user arguments are stripped and routed through the same
|
||||
tenant guard as context resolution (get_user() already applies
|
||||
it), so a dev environment can never send the production tenant -
|
||||
or a sanitization-collision variant of it - to library-desk.
|
||||
"""
|
||||
effective = (user if user is not None else get_user()).strip()
|
||||
if not effective:
|
||||
raise ValueError(
|
||||
"library-desk request requires a non-empty user (tenant); "
|
||||
"got an empty value from the caller or request context"
|
||||
)
|
||||
return apply_tenant_guard(effective)
|
||||
|
||||
async def _request_with_retry(
|
||||
self,
|
||||
send: Callable[[], Awaitable[httpx.Response]],
|
||||
description: str,
|
||||
) -> httpx.Response:
|
||||
"""
|
||||
Send an idempotent/read-only request with a bounded retry.
|
||||
|
||||
Retries once (2 attempts total) with a short backoff on transport
|
||||
errors and retryable 5xx statuses. Only used for GETs and the
|
||||
read-only POST /query/* and /rag/search endpoints - never for
|
||||
wiki writes.
|
||||
"""
|
||||
for attempt in range(1, _RETRY_ATTEMPTS + 1):
|
||||
try:
|
||||
response = await send()
|
||||
except httpx.TransportError as e:
|
||||
if attempt >= _RETRY_ATTEMPTS:
|
||||
raise
|
||||
logger.warning(
|
||||
"library_desk_retry",
|
||||
request=description,
|
||||
error=str(e),
|
||||
attempt=attempt,
|
||||
)
|
||||
else:
|
||||
if (
|
||||
response.status_code not in _RETRYABLE_STATUS_CODES
|
||||
or attempt >= _RETRY_ATTEMPTS
|
||||
):
|
||||
return response
|
||||
logger.warning(
|
||||
"library_desk_retry",
|
||||
request=description,
|
||||
status_code=response.status_code,
|
||||
attempt=attempt,
|
||||
)
|
||||
await asyncio.sleep(_RETRY_BACKOFF_SECONDS * attempt)
|
||||
|
||||
raise RuntimeError("unreachable") # pragma: no cover
|
||||
|
||||
# ========================================================================
|
||||
# HybridRAG
|
||||
# ========================================================================
|
||||
@@ -247,17 +359,19 @@ class LibraryDeskClient:
|
||||
Returns:
|
||||
HybridRAGResponse with ranked results and context
|
||||
"""
|
||||
user = user or get_user()
|
||||
user = self._resolve_user(user)
|
||||
client = self._ensure_client()
|
||||
|
||||
# The live service requires all limits >= 1 (422 otherwise);
|
||||
# legs are disabled via the enable_* flags, not a zero limit.
|
||||
payload = {
|
||||
"query": query,
|
||||
"config": {
|
||||
"vector_limit": vector_limit,
|
||||
"graph_limit": graph_limit,
|
||||
"web_limit": web_limit,
|
||||
"document_limit": document_limit,
|
||||
"volatile_limit": volatile_limit,
|
||||
"vector_limit": max(vector_limit, 1),
|
||||
"graph_limit": max(graph_limit, 1),
|
||||
"web_limit": max(web_limit, 1),
|
||||
"document_limit": max(document_limit, 1),
|
||||
"volatile_limit": max(volatile_limit, 1),
|
||||
"enable_documents": document_limit > 0,
|
||||
"enable_volatile": volatile_limit > 0,
|
||||
"enable_web": web_limit > 0,
|
||||
@@ -268,43 +382,69 @@ class LibraryDeskClient:
|
||||
|
||||
logger.info("library_desk_hybrid_search", query=query, user=user)
|
||||
|
||||
response = await client.post(
|
||||
response = await self._request_with_retry(
|
||||
lambda: client.post(
|
||||
"/query/hybrid",
|
||||
json=payload,
|
||||
params={"user": user},
|
||||
),
|
||||
"POST /query/hybrid",
|
||||
)
|
||||
response.raise_for_status()
|
||||
|
||||
data = response.json()
|
||||
|
||||
# Parse results
|
||||
# Parse results (live field names: source_type, sources, rrf_score,
|
||||
# related_dossiers; older names kept as fallbacks)
|
||||
results = []
|
||||
for r in data.get("results", []):
|
||||
results.append(HybridSearchResult(
|
||||
source=r.get("source", "unknown"),
|
||||
source=r.get("source_type") or r.get("source", "unknown"),
|
||||
sources=r.get("sources", []),
|
||||
title=r.get("title", ""),
|
||||
content=r.get("content", ""),
|
||||
url=r.get("url"),
|
||||
score=r.get("score", 0.0),
|
||||
score=r.get("rrf_score", r.get("score", 0.0)),
|
||||
page_id=r.get("page_id"),
|
||||
related_dossiers=r.get("related_dossiers", []),
|
||||
metadata=r.get("metadata", {}),
|
||||
))
|
||||
|
||||
# Handle keywords being either a list or a dict with core_keywords
|
||||
# Handle keywords being either a list or a dict with core_keywords;
|
||||
# the live service nests synonyms inside the keywords dict as a
|
||||
# {term: [synonyms]} map.
|
||||
raw_keywords = data.get("keywords", [])
|
||||
raw_synonyms: Any = data.get("synonyms", [])
|
||||
if isinstance(raw_keywords, dict):
|
||||
keywords = raw_keywords.get("core_keywords", [])
|
||||
raw_synonyms = raw_keywords.get("synonyms", {})
|
||||
else:
|
||||
keywords = raw_keywords
|
||||
if isinstance(raw_synonyms, dict):
|
||||
synonyms = [s for values in raw_synonyms.values() for s in values]
|
||||
else:
|
||||
synonyms = raw_synonyms
|
||||
|
||||
# Aggregate per-result related dossiers into unique top-level titles
|
||||
related_dossiers: list[str] = []
|
||||
for result in results:
|
||||
for dossier in result.related_dossiers:
|
||||
title = dossier.get("title", "")
|
||||
if title and title not in related_dossiers:
|
||||
related_dossiers.append(title)
|
||||
|
||||
return HybridRAGResponse(
|
||||
results=results,
|
||||
keywords=keywords,
|
||||
synonyms=data.get("synonyms", []),
|
||||
related_dossiers=data.get("related_dossiers", []),
|
||||
formatted_context=data.get("formatted_context", ""),
|
||||
synonyms=synonyms,
|
||||
related_dossiers=related_dossiers,
|
||||
formatted_context=data.get("context", data.get("formatted_context", "")),
|
||||
search_id=data.get("search_id"),
|
||||
source_counts=data.get("source_counts", {}),
|
||||
timing=data.get("timing", {}),
|
||||
# Additive fields - tolerate absence on older library-desk
|
||||
source_status=data.get("source_status") or {},
|
||||
degraded=bool(data.get("degraded", False)),
|
||||
)
|
||||
|
||||
# ========================================================================
|
||||
@@ -328,14 +468,17 @@ class LibraryDeskClient:
|
||||
Returns:
|
||||
List of matching wiki pages
|
||||
"""
|
||||
user = user or get_user()
|
||||
user = self._resolve_user(user)
|
||||
client = self._ensure_client()
|
||||
|
||||
logger.debug("library_desk_wiki_search", query=query, user=user)
|
||||
|
||||
response = await client.get(
|
||||
response = await self._request_with_retry(
|
||||
lambda: client.get(
|
||||
"/wiki/search",
|
||||
params={"q": query, "user": user, "limit": limit},
|
||||
),
|
||||
"GET /wiki/search",
|
||||
)
|
||||
response.raise_for_status()
|
||||
|
||||
@@ -357,12 +500,15 @@ class LibraryDeskClient:
|
||||
Returns:
|
||||
WikiPage with full content
|
||||
"""
|
||||
user = user or get_user()
|
||||
user = self._resolve_user(user)
|
||||
client = self._ensure_client()
|
||||
|
||||
response = await client.get(
|
||||
response = await self._request_with_retry(
|
||||
lambda: client.get(
|
||||
f"/wiki/pages/{page_id}",
|
||||
params={"user": user},
|
||||
),
|
||||
f"GET /wiki/pages/{page_id}",
|
||||
)
|
||||
response.raise_for_status()
|
||||
|
||||
@@ -371,7 +517,7 @@ class LibraryDeskClient:
|
||||
async def list_wiki_pages(
|
||||
self,
|
||||
user: str | None = None,
|
||||
tag: Optional[str] = None,
|
||||
tag: str | None = None,
|
||||
limit: int = 50,
|
||||
) -> list[WikiPage]:
|
||||
"""
|
||||
@@ -385,14 +531,17 @@ class LibraryDeskClient:
|
||||
Returns:
|
||||
List of wiki pages
|
||||
"""
|
||||
user = user or get_user()
|
||||
user = self._resolve_user(user)
|
||||
client = self._ensure_client()
|
||||
|
||||
params: dict[str, Any] = {"user": user, "limit": limit}
|
||||
if tag:
|
||||
params["tag"] = tag
|
||||
|
||||
response = await client.get("/wiki/pages", params=params)
|
||||
response = await self._request_with_retry(
|
||||
lambda: client.get("/wiki/pages", params=params),
|
||||
"GET /wiki/pages",
|
||||
)
|
||||
response.raise_for_status()
|
||||
|
||||
data = response.json()
|
||||
@@ -405,7 +554,7 @@ class LibraryDeskClient:
|
||||
content: str,
|
||||
user: str | None = None,
|
||||
description: str = "",
|
||||
tags: Optional[list[str]] = None,
|
||||
tags: list[str] | None = None,
|
||||
) -> WikiPage:
|
||||
"""
|
||||
Create a new wiki page.
|
||||
@@ -421,7 +570,7 @@ class LibraryDeskClient:
|
||||
Returns:
|
||||
Created WikiPage
|
||||
"""
|
||||
user = user or get_user()
|
||||
user = self._resolve_user(user)
|
||||
client = self._ensure_client()
|
||||
|
||||
payload = {
|
||||
@@ -444,10 +593,10 @@ class LibraryDeskClient:
|
||||
self,
|
||||
page_id: int,
|
||||
user: str | None = None,
|
||||
content: Optional[str] = None,
|
||||
title: Optional[str] = None,
|
||||
tags: Optional[list[str]] = None,
|
||||
description: Optional[str] = None,
|
||||
content: str | None = None,
|
||||
title: str | None = None,
|
||||
tags: list[str] | None = None,
|
||||
description: str | None = None,
|
||||
) -> WikiPage:
|
||||
"""
|
||||
Update an existing wiki page.
|
||||
@@ -466,7 +615,7 @@ class LibraryDeskClient:
|
||||
Returns:
|
||||
Updated WikiPage
|
||||
"""
|
||||
user = user or get_user()
|
||||
user = self._resolve_user(user)
|
||||
client = self._ensure_client()
|
||||
|
||||
# Build update payload with only provided fields
|
||||
@@ -500,7 +649,7 @@ class LibraryDeskClient:
|
||||
topic: str,
|
||||
tags: list[str],
|
||||
user: str | None = None,
|
||||
path: Optional[str] = None,
|
||||
path: str | None = None,
|
||||
include_web_research: bool = True,
|
||||
include_wiki_search: bool = True,
|
||||
) -> SmartCreateResponse:
|
||||
@@ -524,7 +673,7 @@ class LibraryDeskClient:
|
||||
Returns:
|
||||
SmartCreateResponse with page and research metadata
|
||||
"""
|
||||
user = user or get_user()
|
||||
user = self._resolve_user(user)
|
||||
client = self._ensure_client()
|
||||
|
||||
payload: dict[str, Any] = {
|
||||
@@ -575,12 +724,15 @@ class LibraryDeskClient:
|
||||
Returns:
|
||||
List of dossiers with page counts
|
||||
"""
|
||||
user = user or get_user()
|
||||
user = self._resolve_user(user)
|
||||
client = self._ensure_client()
|
||||
|
||||
response = await client.get(
|
||||
response = await self._request_with_retry(
|
||||
lambda: client.get(
|
||||
"/wiki/dossiers",
|
||||
params={"user": user},
|
||||
),
|
||||
"GET /wiki/dossiers",
|
||||
)
|
||||
response.raise_for_status()
|
||||
|
||||
@@ -610,7 +762,7 @@ class LibraryDeskClient:
|
||||
Returns:
|
||||
List of matching document chunks with scores
|
||||
"""
|
||||
user = user or get_user()
|
||||
user = self._resolve_user(user)
|
||||
client = self._ensure_client()
|
||||
|
||||
payload = {
|
||||
@@ -636,7 +788,7 @@ class LibraryDeskClient:
|
||||
self,
|
||||
cypher_query: str,
|
||||
user: str | None = None,
|
||||
parameters: Optional[dict[str, Any]] = None,
|
||||
parameters: dict[str, Any] | None = None,
|
||||
) -> list[dict[str, Any]]:
|
||||
"""
|
||||
Execute a Cypher query on the knowledge graph.
|
||||
@@ -651,7 +803,7 @@ class LibraryDeskClient:
|
||||
Returns:
|
||||
List of result records
|
||||
"""
|
||||
user = user or get_user()
|
||||
user = self._resolve_user(user)
|
||||
client = self._ensure_client()
|
||||
|
||||
payload = {
|
||||
@@ -670,7 +822,7 @@ class LibraryDeskClient:
|
||||
async def list_graph_nodes(
|
||||
self,
|
||||
user: str | None = None,
|
||||
node_type: Optional[str] = None,
|
||||
node_type: str | None = None,
|
||||
limit: int = 100,
|
||||
) -> list[GraphNode]:
|
||||
"""
|
||||
@@ -684,14 +836,17 @@ class LibraryDeskClient:
|
||||
Returns:
|
||||
List of graph nodes
|
||||
"""
|
||||
user = user or get_user()
|
||||
user = self._resolve_user(user)
|
||||
client = self._ensure_client()
|
||||
|
||||
params: dict[str, Any] = {"user": user, "limit": limit}
|
||||
if node_type:
|
||||
params["node_type"] = node_type
|
||||
|
||||
response = await client.get("/graph/nodes", params=params)
|
||||
response = await self._request_with_retry(
|
||||
lambda: client.get("/graph/nodes", params=params),
|
||||
"GET /graph/nodes",
|
||||
)
|
||||
response.raise_for_status()
|
||||
|
||||
data = response.json()
|
||||
@@ -712,12 +867,15 @@ class LibraryDeskClient:
|
||||
Returns:
|
||||
Node with relationships and connected nodes
|
||||
"""
|
||||
user = user or get_user()
|
||||
user = self._resolve_user(user)
|
||||
client = self._ensure_client()
|
||||
|
||||
response = await client.get(
|
||||
response = await self._request_with_retry(
|
||||
lambda: client.get(
|
||||
f"/graph/nodes/{node_id}",
|
||||
params={"user": user},
|
||||
),
|
||||
f"GET /graph/nodes/{node_id}",
|
||||
)
|
||||
response.raise_for_status()
|
||||
|
||||
@@ -736,7 +894,10 @@ class LibraryDeskClient:
|
||||
"""
|
||||
try:
|
||||
client = self._ensure_client()
|
||||
response = await client.get("/health")
|
||||
response = await self._request_with_retry(
|
||||
lambda: client.get("/health"),
|
||||
"GET /health",
|
||||
)
|
||||
return response.status_code == 200
|
||||
except Exception as e:
|
||||
logger.warning("library_desk_health_check_failed", error=str(e))
|
||||
@@ -768,19 +929,22 @@ class LibraryDeskClient:
|
||||
Returns:
|
||||
WebSearchResponse with results and pre-formatted sources
|
||||
"""
|
||||
user = user or get_user()
|
||||
user = self._resolve_user(user)
|
||||
client = self._ensure_client()
|
||||
|
||||
payload = {
|
||||
"query": query,
|
||||
"search_type": search_type,
|
||||
"limit": limit,
|
||||
"user": user or "tatlock-librarian",
|
||||
"user": user,
|
||||
}
|
||||
|
||||
logger.info("library_desk_web_search", query=query, limit=limit)
|
||||
|
||||
response = await client.post("/rag/search", json=payload, timeout=30.0)
|
||||
response = await self._request_with_retry(
|
||||
lambda: client.post("/rag/search", json=payload),
|
||||
"POST /rag/search",
|
||||
)
|
||||
response.raise_for_status()
|
||||
|
||||
data = response.json()
|
||||
@@ -813,6 +977,7 @@ class LibraryDeskClient:
|
||||
async def extract_content(
|
||||
self,
|
||||
url: str,
|
||||
user: str | None = None,
|
||||
include_metadata: bool = True,
|
||||
max_length: int = 5000,
|
||||
) -> ContentExtractionResult:
|
||||
@@ -826,12 +991,14 @@ class LibraryDeskClient:
|
||||
|
||||
Args:
|
||||
url: URL to extract content from
|
||||
user: User identifier (defaults to request context)
|
||||
include_metadata: Whether to extract author, date, etc.
|
||||
max_length: Maximum content length
|
||||
|
||||
Returns:
|
||||
ContentExtractionResult (check .success and .error fields)
|
||||
"""
|
||||
user = self._resolve_user(user)
|
||||
client = self._ensure_client()
|
||||
|
||||
payload = {
|
||||
@@ -842,7 +1009,11 @@ class LibraryDeskClient:
|
||||
|
||||
logger.debug("library_desk_extract_content", url=url)
|
||||
|
||||
response = await client.post("/content/extract", json=payload, timeout=30.0)
|
||||
response = await client.post(
|
||||
"/content/extract",
|
||||
json=payload,
|
||||
params={"user": user},
|
||||
)
|
||||
response.raise_for_status()
|
||||
|
||||
data = response.json()
|
||||
@@ -862,6 +1033,7 @@ class LibraryDeskClient:
|
||||
async def extract_content_batch(
|
||||
self,
|
||||
urls: list[str],
|
||||
user: str | None = None,
|
||||
include_metadata: bool = True,
|
||||
max_length: int = 2000,
|
||||
) -> BatchExtractionResponse:
|
||||
@@ -875,12 +1047,14 @@ class LibraryDeskClient:
|
||||
|
||||
Args:
|
||||
urls: List of URLs to extract (max 20)
|
||||
user: User identifier (defaults to request context)
|
||||
include_metadata: Whether to extract author, date, etc.
|
||||
max_length: Maximum content length per URL
|
||||
|
||||
Returns:
|
||||
BatchExtractionResponse with results and stats
|
||||
"""
|
||||
user = self._resolve_user(user)
|
||||
client = self._ensure_client()
|
||||
|
||||
payload = {
|
||||
@@ -894,7 +1068,7 @@ class LibraryDeskClient:
|
||||
response = await client.post(
|
||||
"/content/extract/batch",
|
||||
json=payload,
|
||||
timeout=60.0, # Longer timeout for batch
|
||||
params={"user": user},
|
||||
)
|
||||
response.raise_for_status()
|
||||
|
||||
@@ -933,3 +1107,30 @@ async def get_library_client() -> LibraryDeskClient:
|
||||
results = await client.hybrid_search("query")
|
||||
"""
|
||||
return LibraryDeskClient()
|
||||
|
||||
|
||||
@asynccontextmanager
|
||||
async def library_client_session() -> AsyncIterator[None]:
|
||||
"""
|
||||
Hold ONE shared HTTP connection for the duration of a librarian run.
|
||||
|
||||
While the session is active, every LibraryDeskClient targeting the
|
||||
configured library-desk instance reuses the shared httpx client
|
||||
instead of constructing (and tearing down) a connection per tool
|
||||
call. Nested sessions are no-ops.
|
||||
|
||||
Usage:
|
||||
async with library_client_session():
|
||||
... # librarian tools reuse one connection
|
||||
"""
|
||||
if _shared_http_client.get() is not None:
|
||||
yield
|
||||
return
|
||||
|
||||
http_client = LibraryDeskClient()._build_http_client()
|
||||
token = _shared_http_client.set(http_client)
|
||||
try:
|
||||
yield
|
||||
finally:
|
||||
_shared_http_client.reset(token)
|
||||
await http_client.aclose()
|
||||
|
||||
+179
-44
@@ -4,12 +4,109 @@ Librarian tools for PydanticAI agent.
|
||||
These tools wrap the library-desk API and are registered with
|
||||
The Librarian agent for research and knowledge management tasks.
|
||||
"""
|
||||
from src.agents.librarian.client import LibraryDeskClient
|
||||
import httpx
|
||||
from pydantic_ai import ModelRetry
|
||||
|
||||
from src.agents.librarian.client import HybridRAGResponse, LibraryDeskClient
|
||||
from src.core.logging_config import get_logger
|
||||
|
||||
logger = get_logger(__name__)
|
||||
|
||||
|
||||
def _retry_if_transient(e: Exception, what: str) -> None:
|
||||
"""
|
||||
Convert transient HTTP errors into ModelRetry so the agent's
|
||||
retry budget (Agent(retries=2)) engages instead of the tool
|
||||
swallowing the failure.
|
||||
|
||||
Only read tools call this - writes are never retried to avoid
|
||||
duplicate wiki pages.
|
||||
"""
|
||||
retryable = isinstance(e, httpx.TransportError)
|
||||
if isinstance(e, httpx.HTTPStatusError):
|
||||
status = e.response.status_code
|
||||
retryable = status >= 500 or status == 429
|
||||
if retryable:
|
||||
raise ModelRetry(
|
||||
f"{what} is temporarily unavailable; please retry."
|
||||
) from e
|
||||
|
||||
# Icons keyed by the values library-desk emits in each result's `sources`
|
||||
# list (search legs) and `source_type` (result origin).
|
||||
SOURCE_ICONS = {
|
||||
"vector": "📄",
|
||||
"graph": "🔗",
|
||||
"web": "🌐",
|
||||
"document": "📑",
|
||||
"documents": "📑",
|
||||
"volatile": "⚡",
|
||||
"wiki": "📄",
|
||||
}
|
||||
|
||||
|
||||
def _coverage_note(
|
||||
response: HybridRAGResponse,
|
||||
include_web: bool,
|
||||
include_documents: bool,
|
||||
include_volatile: bool,
|
||||
) -> str:
|
||||
"""
|
||||
Build a one-line coverage note when the search was degraded or an
|
||||
enabled source leg contributed nothing, so outages stay visible to
|
||||
the model and the user instead of silently narrowing results.
|
||||
|
||||
When the additive source_status/degraded contract is present it is
|
||||
authoritative and used EXCLUSIVELY - no count heuristics. Without
|
||||
it, absence from source_counts is only inferred for the optional
|
||||
legs this request explicitly enabled (web/documents/volatile);
|
||||
the always-on wiki legs (vector/graph) are never inferred, because
|
||||
source_counts only tallies the sources of the final top-N fused
|
||||
results, so their absence is normal ranking behavior, not an outage.
|
||||
"""
|
||||
if response.source_status:
|
||||
failed = sorted(
|
||||
leg
|
||||
for leg, status in response.source_status.items()
|
||||
if status == "failed"
|
||||
)
|
||||
if failed:
|
||||
return (
|
||||
"⚠️ *Coverage note: results are partial - "
|
||||
f"these sources failed: {', '.join(failed)}.*"
|
||||
)
|
||||
if response.degraded:
|
||||
return (
|
||||
"⚠️ *Coverage note: results are partial - "
|
||||
"one or more sources failed during this search.*"
|
||||
)
|
||||
return ""
|
||||
|
||||
if not response.source_counts:
|
||||
# Older library-desk without per-source reporting - nothing to infer
|
||||
return ""
|
||||
|
||||
# Only legs the request explicitly enabled; never vector/graph (their
|
||||
# absence from the top-N counts is healthy, see docstring)
|
||||
expected = set()
|
||||
if include_web:
|
||||
expected.add("web")
|
||||
if include_documents:
|
||||
expected.add("documents")
|
||||
if include_volatile:
|
||||
expected.add("volatile")
|
||||
|
||||
# Normalize count keys to leg names (document/documents)
|
||||
aliases = {"document": "documents"}
|
||||
reported = {aliases.get(key, key) for key in response.source_counts}
|
||||
missing = sorted(expected - reported)
|
||||
if missing:
|
||||
return (
|
||||
"⚠️ *Coverage note: no results came from: "
|
||||
f"{', '.join(missing)} (source unavailable or nothing found).*"
|
||||
)
|
||||
return ""
|
||||
|
||||
|
||||
# ============================================================================
|
||||
# HybridRAG Search
|
||||
# ============================================================================
|
||||
@@ -76,13 +173,10 @@ async def hybrid_search(
|
||||
|
||||
# Add results
|
||||
for i, result in enumerate(response.results, 1):
|
||||
source_icon = {
|
||||
"vector": "📄",
|
||||
"graph": "🔗",
|
||||
"web": "🌐",
|
||||
"document": "📑",
|
||||
"volatile": "⚡",
|
||||
}.get(result.source, "•")
|
||||
source_keys = result.sources or [result.source]
|
||||
source_icon = "".join(
|
||||
dict.fromkeys(SOURCE_ICONS.get(key, "•") for key in source_keys)
|
||||
)
|
||||
|
||||
output_parts.append(
|
||||
f"{i}. {source_icon} **{result.title}** (score: {result.score:.2f})"
|
||||
@@ -92,17 +186,30 @@ async def hybrid_search(
|
||||
output_parts.append(f" {result.content[:300]}...")
|
||||
output_parts.append("")
|
||||
|
||||
# Surface degraded coverage so outages are visible downstream
|
||||
coverage_note = _coverage_note(
|
||||
response,
|
||||
include_web=include_web,
|
||||
include_documents=include_documents,
|
||||
include_volatile=include_volatile,
|
||||
)
|
||||
if coverage_note:
|
||||
output_parts.append(coverage_note)
|
||||
|
||||
logger.info(
|
||||
"librarian_hybrid_search",
|
||||
query=query,
|
||||
result_count=len(response.results),
|
||||
degraded=response.degraded,
|
||||
source_counts=response.source_counts,
|
||||
)
|
||||
|
||||
return "\n".join(output_parts)
|
||||
|
||||
except Exception as e:
|
||||
logger.error("librarian_hybrid_search_error", error=str(e), query=query)
|
||||
return f"Error searching: {str(e)}"
|
||||
_retry_if_transient(e, "The knowledge archive")
|
||||
return "I was unable to search the knowledge archives; the search service did not respond properly."
|
||||
|
||||
|
||||
# ============================================================================
|
||||
@@ -139,8 +246,11 @@ async def search_wiki(
|
||||
|
||||
output_parts = [f"## Wiki Search: {query}\n"]
|
||||
|
||||
for i, page in enumerate(results, 1):
|
||||
output_parts.append(f"{i}. **{page.title}**")
|
||||
# No ordinal numbering: small models pass the list position to
|
||||
# get_wiki_page instead of the page ID unless the ID is the only
|
||||
# number in sight.
|
||||
for page in results:
|
||||
output_parts.append(f"- **{page.title}** (page_id: {page.id})")
|
||||
output_parts.append(f" Path: {page.path}")
|
||||
if page.description:
|
||||
output_parts.append(f" {page.description}")
|
||||
@@ -150,7 +260,8 @@ async def search_wiki(
|
||||
|
||||
except Exception as e:
|
||||
logger.error("librarian_wiki_search_error", error=str(e))
|
||||
return f"Error searching wiki: {str(e)}"
|
||||
_retry_if_transient(e, "The wiki search")
|
||||
return "I was unable to search the wiki at this time."
|
||||
|
||||
|
||||
async def get_wiki_page(
|
||||
@@ -193,7 +304,8 @@ async def get_wiki_page(
|
||||
|
||||
except Exception as e:
|
||||
logger.error("librarian_get_page_error", error=str(e), page_id=page_id)
|
||||
return f"Error getting page {page_id}: {str(e)}"
|
||||
_retry_if_transient(e, "The wiki")
|
||||
return f"I was unable to retrieve wiki page {page_id}."
|
||||
|
||||
|
||||
async def list_dossiers() -> str:
|
||||
@@ -227,7 +339,8 @@ async def list_dossiers() -> str:
|
||||
|
||||
except Exception as e:
|
||||
logger.error("librarian_list_dossiers_error", error=str(e))
|
||||
return f"Error listing dossiers: {str(e)}"
|
||||
_retry_if_transient(e, "The dossier index")
|
||||
return "I was unable to retrieve the list of dossiers."
|
||||
|
||||
|
||||
async def get_dossier_pages(
|
||||
@@ -268,7 +381,8 @@ async def get_dossier_pages(
|
||||
|
||||
except Exception as e:
|
||||
logger.error("librarian_get_dossier_error", error=str(e))
|
||||
return f"Error getting dossier: {str(e)}"
|
||||
_retry_if_transient(e, "The dossier index")
|
||||
return f"I was unable to retrieve the dossier '{dossier_name}'."
|
||||
|
||||
|
||||
# ============================================================================
|
||||
@@ -317,7 +431,8 @@ async def semantic_search(
|
||||
|
||||
except Exception as e:
|
||||
logger.error("librarian_semantic_search_error", error=str(e))
|
||||
return f"Error in semantic search: {str(e)}"
|
||||
_retry_if_transient(e, "The semantic search")
|
||||
return "I was unable to complete the semantic search."
|
||||
|
||||
|
||||
# ============================================================================
|
||||
@@ -370,7 +485,8 @@ async def explore_knowledge_graph(
|
||||
|
||||
except Exception as e:
|
||||
logger.error("librarian_explore_graph_error", error=str(e))
|
||||
return f"Error exploring knowledge graph: {str(e)}"
|
||||
_retry_if_transient(e, "The knowledge graph")
|
||||
return "I was unable to explore the knowledge graph."
|
||||
|
||||
|
||||
async def find_related_entities(
|
||||
@@ -441,7 +557,8 @@ async def find_related_entities(
|
||||
|
||||
except Exception as e:
|
||||
logger.error("librarian_find_related_error", error=str(e))
|
||||
return f"Error finding related entities: {str(e)}"
|
||||
_retry_if_transient(e, "The knowledge graph")
|
||||
return f"I was unable to look up entities related to '{entity_name}'."
|
||||
|
||||
|
||||
# ============================================================================
|
||||
@@ -524,7 +641,8 @@ async def search_web(
|
||||
|
||||
except Exception as e:
|
||||
logger.error("librarian_web_search_error", error=str(e), query=query)
|
||||
return f"Error searching web: {str(e)}"
|
||||
_retry_if_transient(e, "The web search")
|
||||
return "I was unable to search the web at this time."
|
||||
|
||||
|
||||
async def read_url(
|
||||
@@ -600,7 +718,8 @@ async def read_url(
|
||||
|
||||
except Exception as e:
|
||||
logger.error("librarian_read_url_error", error=str(e), url=url)
|
||||
return f"Error reading URL: {str(e)}"
|
||||
_retry_if_transient(e, "Content extraction")
|
||||
return f"I was unable to read the page at {url}."
|
||||
|
||||
|
||||
async def read_urls_batch(
|
||||
@@ -635,7 +754,7 @@ async def read_urls_batch(
|
||||
)
|
||||
|
||||
output_parts = [
|
||||
f"## Batch Content Extraction",
|
||||
"## Batch Content Extraction",
|
||||
f"*Extracted {response.successful}/{response.total_urls} URLs in {response.extraction_time_ms}ms*\n",
|
||||
]
|
||||
|
||||
@@ -674,19 +793,23 @@ async def read_urls_batch(
|
||||
|
||||
except Exception as e:
|
||||
logger.error("librarian_read_urls_batch_error", error=str(e))
|
||||
return f"Error reading URLs: {str(e)}"
|
||||
_retry_if_transient(e, "Content extraction")
|
||||
return "I was unable to read the requested pages."
|
||||
|
||||
|
||||
# ============================================================================
|
||||
# Wiki Write Operations
|
||||
# ============================================================================
|
||||
|
||||
CLEAR_TAGS_SENTINEL = "__CLEAR__"
|
||||
|
||||
|
||||
async def update_wiki_page(
|
||||
page_id: int,
|
||||
content: str | None = None,
|
||||
title: str | None = None,
|
||||
tags: list[str] | None = None,
|
||||
description: str | None = None,
|
||||
content: str = "",
|
||||
title: str = "",
|
||||
tags: list[str] = [], # noqa: B006 - sentinel, never mutated
|
||||
description: str = "",
|
||||
) -> str:
|
||||
"""
|
||||
Update an existing wiki page.
|
||||
@@ -700,12 +823,17 @@ async def update_wiki_page(
|
||||
- Updating tags to organize pages into dossiers
|
||||
- Fixing descriptions or titles
|
||||
|
||||
Note: empty values are sentinels for "leave unchanged" (Ollama's
|
||||
OpenAI-compatible API mishandles anyOf[X, null] parameter schemas).
|
||||
|
||||
Args:
|
||||
page_id: ID of the page to update (get from search_wiki results)
|
||||
content: New markdown content (optional - only if changing content)
|
||||
title: New title (optional - only if renaming)
|
||||
tags: New tag list (optional - replaces existing tags)
|
||||
description: New description (optional)
|
||||
content: New markdown content (empty = leave unchanged)
|
||||
title: New title (empty = leave unchanged)
|
||||
tags: New tag list, replaces existing tags (empty = leave unchanged).
|
||||
To remove ALL tags from a page, pass exactly ["__CLEAR__"]
|
||||
(an empty list means "leave unchanged", not "clear")
|
||||
description: New description (empty = leave unchanged)
|
||||
|
||||
Returns:
|
||||
Confirmation with updated page details
|
||||
@@ -713,27 +841,34 @@ async def update_wiki_page(
|
||||
Examples:
|
||||
update_wiki_page(42, content="# Updated Content\\n\\nNew information here")
|
||||
update_wiki_page(42, tags=["projects", "devops"]) # Add to dossiers
|
||||
update_wiki_page(42, tags=["__CLEAR__"]) # Remove all tags
|
||||
update_wiki_page(42, description="Updated description")
|
||||
"""
|
||||
# Empty list = leave unchanged; the explicit clear sentinel sends an
|
||||
# empty tag list to the service, which replaces (clears) all tags.
|
||||
clear_tags = tags == [CLEAR_TAGS_SENTINEL]
|
||||
|
||||
try:
|
||||
async with LibraryDeskClient() as client:
|
||||
page = await client.update_wiki_page(
|
||||
page_id=page_id,
|
||||
content=content,
|
||||
title=title,
|
||||
tags=tags,
|
||||
description=description,
|
||||
content=content if content else None,
|
||||
title=title if title else None,
|
||||
tags=[] if clear_tags else (tags if tags else None),
|
||||
description=description if description else None,
|
||||
)
|
||||
|
||||
# Build update summary
|
||||
updated_fields = []
|
||||
if content is not None:
|
||||
if content:
|
||||
updated_fields.append("content")
|
||||
if title is not None:
|
||||
if title:
|
||||
updated_fields.append("title")
|
||||
if tags is not None:
|
||||
if clear_tags:
|
||||
updated_fields.append("tags (cleared)")
|
||||
elif tags:
|
||||
updated_fields.append("tags")
|
||||
if description is not None:
|
||||
if description:
|
||||
updated_fields.append("description")
|
||||
|
||||
output_parts = [
|
||||
@@ -757,7 +892,7 @@ async def update_wiki_page(
|
||||
|
||||
except Exception as e:
|
||||
logger.error("librarian_update_page_error", error=str(e), page_id=page_id)
|
||||
return f"Error updating page {page_id}: {str(e)}"
|
||||
return f"I was unable to update wiki page {page_id}."
|
||||
|
||||
|
||||
async def create_wiki_page(
|
||||
@@ -832,13 +967,13 @@ async def create_wiki_page(
|
||||
|
||||
except Exception as e:
|
||||
logger.error("librarian_create_page_error", error=str(e), title=title)
|
||||
return f"Error creating page: {str(e)}"
|
||||
return f"I was unable to create the page '{title}'."
|
||||
|
||||
|
||||
async def smart_create_wiki_page(
|
||||
topic: str,
|
||||
tags: list[str],
|
||||
path: str | None = None,
|
||||
path: str = "",
|
||||
include_web_research: bool = True,
|
||||
include_wiki_search: bool = True,
|
||||
) -> str:
|
||||
@@ -860,7 +995,7 @@ async def smart_create_wiki_page(
|
||||
Args:
|
||||
topic: The topic to research and create a page about
|
||||
tags: List of tags/dossiers for categorization
|
||||
path: Optional custom path (auto-generated from topic if not provided)
|
||||
path: Optional custom path (empty = auto-generated from topic)
|
||||
include_web_research: Whether to search the web (default: True)
|
||||
include_wiki_search: Whether to search existing wiki (default: True)
|
||||
|
||||
@@ -876,7 +1011,7 @@ async def smart_create_wiki_page(
|
||||
response = await client.smart_create_wiki_page(
|
||||
topic=topic,
|
||||
tags=tags,
|
||||
path=path,
|
||||
path=path if path else None,
|
||||
include_web_research=include_web_research,
|
||||
include_wiki_search=include_wiki_search,
|
||||
)
|
||||
@@ -921,7 +1056,7 @@ async def smart_create_wiki_page(
|
||||
|
||||
except Exception as e:
|
||||
logger.error("librarian_smart_create_error", error=str(e), topic=topic)
|
||||
return f"Error creating page about '{topic}': {str(e)}"
|
||||
return f"I was unable to create a page about '{topic}'."
|
||||
|
||||
|
||||
# ============================================================================
|
||||
|
||||
+5
-189
@@ -1,180 +1,11 @@
|
||||
"""
|
||||
Agent communication protocol for multi-agent coordination.
|
||||
Agent error protocol.
|
||||
|
||||
Defines standardized request/response formats for communication between:
|
||||
- Steward (request analysis) → Tatlock (coordination)
|
||||
- Tatlock (coordination) → Expert agents (Librarian, Developer, etc.)
|
||||
Structured exceptions raised by expert agents (e.g. The Librarian) so
|
||||
callers - the delegation wrappers in src/agents/delegation.py - can
|
||||
report success=False and map failures to curated user-safe messages
|
||||
while exception detail stays in the logs.
|
||||
"""
|
||||
from enum import Enum
|
||||
from typing import Any, Optional
|
||||
|
||||
from pydantic import BaseModel, Field
|
||||
|
||||
|
||||
class DelegationReason(str, Enum):
|
||||
"""Why a task is being delegated to an expert agent."""
|
||||
DOMAIN_EXPERTISE = "domain_expertise" # Expert has specialized knowledge
|
||||
TOOL_ACCESS = "tool_access" # Expert has required tools
|
||||
RESOURCE_EFFICIENCY = "resource_efficiency" # Better handled by specialist
|
||||
USER_PREFERENCE = "user_preference" # User requested specific agent
|
||||
|
||||
|
||||
class TaskComplexity(str, Enum):
|
||||
"""Complexity estimate for task execution."""
|
||||
SIMPLE = "simple" # Single tool call, fast
|
||||
MODERATE = "moderate" # Multiple steps, moderate time
|
||||
COMPLEX = "complex" # Multi-agent, significant processing
|
||||
|
||||
|
||||
class AgentRequest(BaseModel):
|
||||
"""
|
||||
Request to an expert agent.
|
||||
|
||||
Contains everything the agent needs to execute a task,
|
||||
including context from the conversation and delegation intent.
|
||||
"""
|
||||
task: str = Field(
|
||||
...,
|
||||
description="Clear description of what the agent should do"
|
||||
)
|
||||
context: str = Field(
|
||||
default="",
|
||||
description="Relevant context from conversation history"
|
||||
)
|
||||
constraints: list[str] = Field(
|
||||
default_factory=list,
|
||||
description="Any constraints or requirements for the task"
|
||||
)
|
||||
delegation_reason: DelegationReason = Field(
|
||||
default=DelegationReason.DOMAIN_EXPERTISE,
|
||||
description="Why this task was delegated to this agent"
|
||||
)
|
||||
user_id: str = Field(
|
||||
default="default",
|
||||
description="User identifier for multi-tenant operations"
|
||||
)
|
||||
max_tokens: Optional[int] = Field(
|
||||
default=None,
|
||||
description="Optional token limit for response"
|
||||
)
|
||||
timeout_seconds: Optional[int] = Field(
|
||||
default=60,
|
||||
description="Maximum time for task completion"
|
||||
)
|
||||
|
||||
|
||||
class ToolCallRecord(BaseModel):
|
||||
"""Record of a tool call made during execution."""
|
||||
tool_name: str
|
||||
arguments: dict[str, Any]
|
||||
result: str
|
||||
duration_ms: int
|
||||
|
||||
|
||||
class AgentResponse(BaseModel):
|
||||
"""
|
||||
Response from an expert agent.
|
||||
|
||||
Contains the result, reasoning, and metadata about execution.
|
||||
"""
|
||||
success: bool = Field(
|
||||
...,
|
||||
description="Whether the task completed successfully"
|
||||
)
|
||||
result: str = Field(
|
||||
...,
|
||||
description="The main output/answer from the agent"
|
||||
)
|
||||
reasoning: str = Field(
|
||||
default="",
|
||||
description="Agent's reasoning process (for transparency)"
|
||||
)
|
||||
tool_calls: list[ToolCallRecord] = Field(
|
||||
default_factory=list,
|
||||
description="Tools called during execution"
|
||||
)
|
||||
confidence: float = Field(
|
||||
default=1.0,
|
||||
ge=0.0,
|
||||
le=1.0,
|
||||
description="Agent's confidence in the result (0.0-1.0)"
|
||||
)
|
||||
sources: list[str] = Field(
|
||||
default_factory=list,
|
||||
description="Sources or references used"
|
||||
)
|
||||
error_message: Optional[str] = Field(
|
||||
default=None,
|
||||
description="Error details if success=False"
|
||||
)
|
||||
duration_ms: int = Field(
|
||||
default=0,
|
||||
description="Total execution time in milliseconds"
|
||||
)
|
||||
|
||||
|
||||
class DelegationIntent(BaseModel):
|
||||
"""
|
||||
Intent to delegate a task to an expert agent.
|
||||
|
||||
Created by Tatlock when deciding to delegate, based on
|
||||
Steward's recommendations.
|
||||
"""
|
||||
target_agent: str = Field(
|
||||
...,
|
||||
description="Name of the expert agent to delegate to"
|
||||
)
|
||||
task: str = Field(
|
||||
...,
|
||||
description="Task description for the agent"
|
||||
)
|
||||
reason: DelegationReason = Field(
|
||||
default=DelegationReason.DOMAIN_EXPERTISE,
|
||||
description="Why delegating to this agent"
|
||||
)
|
||||
expected_outcome: str = Field(
|
||||
default="",
|
||||
description="What we expect the agent to provide"
|
||||
)
|
||||
priority: int = Field(
|
||||
default=1,
|
||||
ge=1,
|
||||
le=10,
|
||||
description="Priority (1=highest, 10=lowest)"
|
||||
)
|
||||
depends_on: list[str] = Field(
|
||||
default_factory=list,
|
||||
description="Other delegation IDs this depends on (for sequencing)"
|
||||
)
|
||||
|
||||
|
||||
class CoordinationResult(BaseModel):
|
||||
"""
|
||||
Result of multi-agent coordination.
|
||||
|
||||
Aggregates results from multiple expert agents into
|
||||
a single coherent response.
|
||||
"""
|
||||
final_response: str = Field(
|
||||
...,
|
||||
description="Synthesized response from all agents"
|
||||
)
|
||||
agent_responses: dict[str, AgentResponse] = Field(
|
||||
default_factory=dict,
|
||||
description="Individual responses keyed by agent name"
|
||||
)
|
||||
delegation_intents: list[DelegationIntent] = Field(
|
||||
default_factory=list,
|
||||
description="All delegations that were executed"
|
||||
)
|
||||
total_duration_ms: int = Field(
|
||||
default=0,
|
||||
description="Total coordination time"
|
||||
)
|
||||
agents_consulted: list[str] = Field(
|
||||
default_factory=list,
|
||||
description="Names of agents that contributed"
|
||||
)
|
||||
|
||||
|
||||
class AgentError(Exception):
|
||||
@@ -184,18 +15,3 @@ class AgentError(Exception):
|
||||
self.message = message
|
||||
self.agent_name = agent_name
|
||||
super().__init__(f"[{agent_name}] {message}")
|
||||
|
||||
|
||||
class AgentTimeoutError(AgentError):
|
||||
"""Agent execution timed out."""
|
||||
pass
|
||||
|
||||
|
||||
class AgentUnavailableError(AgentError):
|
||||
"""Agent is not available or registered."""
|
||||
pass
|
||||
|
||||
|
||||
class DelegationError(AgentError):
|
||||
"""Error during task delegation."""
|
||||
pass
|
||||
|
||||
+24
-10
@@ -11,7 +11,7 @@ Uses plain text output (not JSON) for reliability. Supports both Claude
|
||||
import httpx
|
||||
from typing import Optional
|
||||
|
||||
from src.anthropic.model_selector import is_claude_available, get_model_info
|
||||
from src.anthropic.model_selector import get_model_info, is_claude_available, resolve_backend
|
||||
from src.core.config import config
|
||||
from src.core.household_registry import get_household_registry
|
||||
from src.core.logging_config import get_logger
|
||||
@@ -113,18 +113,19 @@ class StewardAgent:
|
||||
|
||||
def __init__(self):
|
||||
"""Initialize Steward with backend selection based on availability."""
|
||||
# Ollama config (fallback)
|
||||
# Ollama config (primary)
|
||||
self.ollama_host = str(config.OLLAMA_HOST).rstrip('/')
|
||||
self.ollama_model = config.OLLAMA_DEFAULT_MODEL
|
||||
|
||||
# Claude config (preferred)
|
||||
# Claude config (fallback)
|
||||
self.claude_model = config.ANTHROPIC_MODEL
|
||||
self._anthropic_client = None
|
||||
|
||||
# Determine which backend to use
|
||||
self._use_claude = config.PREFER_CLOUD_BACKEND and is_claude_available()
|
||||
# Determine which backend to use (Ollama-first, Claude when
|
||||
# preferred via config or when Ollama is down)
|
||||
self._use_claude = resolve_backend() == "claude"
|
||||
|
||||
self.timeout = 30.0 # 30 second timeout for analysis
|
||||
self.timeout = float(config.STEWARD_TIMEOUT)
|
||||
|
||||
model_info = get_model_info()
|
||||
logger.info(
|
||||
@@ -145,12 +146,12 @@ class StewardAgent:
|
||||
"""Call Claude API directly for plain text generation."""
|
||||
client = self._get_anthropic_client()
|
||||
|
||||
# No temperature: rejected by Claude Sonnet 5+ (sampling params deprecated)
|
||||
response = await client.messages.create(
|
||||
model=self.claude_model,
|
||||
max_tokens=1024,
|
||||
system=system_prompt,
|
||||
messages=[{"role": "user", "content": user_message}],
|
||||
temperature=0.3, # Lower = more consistent
|
||||
)
|
||||
|
||||
return response.content[0].text.strip()
|
||||
@@ -227,20 +228,33 @@ class StewardAgent:
|
||||
return analysis_text
|
||||
|
||||
except Exception as e:
|
||||
# If Claude fails, try Ollama as fallback
|
||||
# Mid-request fallback: retry on the other backend when possible
|
||||
if self._use_claude:
|
||||
logger.warning(
|
||||
"steward_claude_fallback",
|
||||
error=str(e),
|
||||
)
|
||||
analysis_text = await self._call_ollama(prompt)
|
||||
fallback_backend = "ollama_fallback"
|
||||
elif is_claude_available():
|
||||
logger.warning(
|
||||
"steward_ollama_fallback",
|
||||
error=str(e),
|
||||
)
|
||||
analysis_text = await self._call_claude(
|
||||
system_prompt="You are the Steward of the household, advising the Butler (Tatlock) on which capabilities to use. Be concise and specific.",
|
||||
user_message=prompt,
|
||||
)
|
||||
fallback_backend = "claude_fallback"
|
||||
else:
|
||||
raise
|
||||
|
||||
logger.debug(
|
||||
"steward_analysis_received",
|
||||
backend="ollama_fallback",
|
||||
backend=fallback_backend,
|
||||
text_preview=analysis_text[:150],
|
||||
)
|
||||
return analysis_text
|
||||
raise
|
||||
|
||||
|
||||
# Global Steward instance
|
||||
|
||||
@@ -19,35 +19,88 @@ from .schemas import ConversationContext, StewardRecommendation
|
||||
logger = get_logger(__name__)
|
||||
|
||||
|
||||
_DELEGATE_LINE_RE = re.compile(r"^[ \t]*DELEGATE:[ \t]*(.+)$", re.IGNORECASE | re.MULTILINE)
|
||||
|
||||
|
||||
def _mentions(needle: str, haystack: str) -> bool:
|
||||
"""Whole-word containment. Substring matching is what made this go wrong."""
|
||||
return re.search(rf"(?<!\w){re.escape(needle)}(?!\w)", haystack) is not None
|
||||
|
||||
|
||||
def _extract_capabilities(text: str) -> list[str]:
|
||||
"""
|
||||
Extract capability names from Steward's text response.
|
||||
Extract capability names from the Steward's declared delegation.
|
||||
|
||||
Uses keyword matching to find mentioned capabilities.
|
||||
The prompt instructs the Steward to answer in a fixed shape::
|
||||
|
||||
DELEGATE: <capability> to <action> <task>
|
||||
REASON: ...
|
||||
COMPLEXITY: ...
|
||||
CONTEXT: ...
|
||||
|
||||
Only the DELEGATE line states intent; the rest is free prose. An earlier
|
||||
version substring-matched capability *domains* across the whole response,
|
||||
which routed on ordinary English: "description" contains "script" and
|
||||
"discover" contains "cover" (both housekeeper domains), "acknowledge"
|
||||
contains "knowledge" and "know" (librarian, biographer), and "economy"
|
||||
contains "my" (biographer). Any REASON line could therefore summon agents
|
||||
the Steward never asked for, and a spurious librarian is a real
|
||||
multi-second web call.
|
||||
|
||||
It also made prose length a routing input, so anything that shortened the
|
||||
Steward's output — such as disabling model thinking — would look like it had
|
||||
improved routing.
|
||||
|
||||
Resolution is layered, most explicit first:
|
||||
1. a DELEGATE line beginning with a capability name — the documented shape
|
||||
2. a capability named anywhere on a DELEGATE line
|
||||
3. a capability *domain* on a DELEGATE line, for a loosely worded answer
|
||||
4. no DELEGATE line: capability names only, never domains
|
||||
|
||||
Args:
|
||||
text: Steward's plain text analysis
|
||||
|
||||
Returns:
|
||||
List of capability names (e.g., ['tatlock_core'])
|
||||
List of capability names (e.g. ['tatlock_core']), de-duplicated.
|
||||
"""
|
||||
text_lower = text.lower()
|
||||
registry = get_household_registry()
|
||||
capabilities = registry.get_all_capabilities()
|
||||
delegate_lines = [line.strip().lower() for line in _DELEGATE_LINE_RE.findall(text or "")]
|
||||
|
||||
found_caps = []
|
||||
found_caps: list[str] = []
|
||||
|
||||
def _add(name: str) -> None:
|
||||
if name not in found_caps:
|
||||
found_caps.append(name)
|
||||
|
||||
if not delegate_lines:
|
||||
# Either the Steward judged no capability necessary — the prompt's
|
||||
# conversational path, whose correct answer is [] — or it ignored the
|
||||
# format. Names only: domain words are ordinary English and would fire
|
||||
# on any prose, which is the bug described above.
|
||||
haystack = (text or "").lower()
|
||||
for cap in capabilities:
|
||||
# Check if capability name is mentioned
|
||||
if cap.name.lower() in text_lower:
|
||||
found_caps.append(cap.name)
|
||||
if _mentions(cap.name.lower(), haystack):
|
||||
_add(cap.name)
|
||||
return found_caps
|
||||
|
||||
for line in delegate_lines:
|
||||
leading = next((c for c in capabilities if line.startswith(c.name.lower())), None)
|
||||
if leading is not None:
|
||||
_add(leading.name)
|
||||
continue
|
||||
|
||||
# Check if any domains are mentioned
|
||||
for domain in cap.domains:
|
||||
if domain.lower() in text_lower:
|
||||
found_caps.append(cap.name)
|
||||
break
|
||||
named = [c for c in capabilities if _mentions(c.name.lower(), line)]
|
||||
if named:
|
||||
for cap in named:
|
||||
_add(cap.name)
|
||||
continue
|
||||
|
||||
# Last resort. Scoped to this line, so the REASON and CONTEXT prose that
|
||||
# caused the original misrouting can no longer reach it.
|
||||
for cap in capabilities:
|
||||
if any(_mentions(domain.lower(), line) for domain in cap.domains):
|
||||
_add(cap.name)
|
||||
|
||||
return found_caps
|
||||
|
||||
|
||||
+18
-2
@@ -129,6 +129,22 @@ or
|
||||
"""
|
||||
|
||||
|
||||
# Tool-phase prompt for orchestrate_tool_calls(). The butler personality prompt
|
||||
# suppresses tool calling on small local models (gemma4 reasons about the tool,
|
||||
# then answers from memory with wrong arithmetic), so the orchestration phase
|
||||
# uses a terse operator prompt; synthesize_from_results() applies the persona.
|
||||
TATLOCK_ORCHESTRATION_PROMPT = """You are the tool-execution phase of Tatlock, \
|
||||
a butler assistant. Your only job is to gather accurate results by calling the \
|
||||
provided tools.
|
||||
|
||||
- ALWAYS use tools for the task - never answer from memory and never do mental math.
|
||||
- Mathematics: call the calculate tool, even for trivial arithmetic.
|
||||
- Dates and times: call the date/time tools, never guess.
|
||||
- When the instructions say DELEGATE to an agent, call the matching delegate_to_* tool.
|
||||
- After the tool results arrive, reply with a one-line factual summary of the results. \
|
||||
A later step writes the polished reply, so do not add personality."""
|
||||
|
||||
|
||||
class TatlockAgent(AgentInterface):
|
||||
"""
|
||||
Tatlock - The Butler agent using PydanticAI with Ollama.
|
||||
@@ -654,10 +670,10 @@ class TatlockAgent(AgentInterface):
|
||||
# Create a fresh agent instance with scoped tools only
|
||||
model = get_model()
|
||||
|
||||
# Create agent with scoped tools
|
||||
# Create agent with scoped tools, using the tool-phase prompt
|
||||
scoped_agent = Agent(
|
||||
model,
|
||||
system_prompt=TATLOCK_SYSTEM_PROMPT,
|
||||
system_prompt=TATLOCK_ORCHESTRATION_PROMPT,
|
||||
tools=scoped_tools,
|
||||
)
|
||||
|
||||
|
||||
@@ -1,19 +1,26 @@
|
||||
"""
|
||||
Anthropic/Claude integration module.
|
||||
|
||||
Provides model selection with automatic fallback between Claude and Ollama.
|
||||
Provides model selection with Ollama as primary backend and Claude
|
||||
as the cloud fallback.
|
||||
"""
|
||||
|
||||
from src.anthropic.model_selector import (
|
||||
check_claude_health,
|
||||
check_ollama_health,
|
||||
get_model,
|
||||
get_tool_choice_settings,
|
||||
is_claude_available,
|
||||
is_ollama_available,
|
||||
resolve_backend,
|
||||
)
|
||||
|
||||
__all__ = [
|
||||
"check_claude_health",
|
||||
"check_ollama_health",
|
||||
"get_model",
|
||||
"get_tool_choice_settings",
|
||||
"is_claude_available",
|
||||
"is_ollama_available",
|
||||
"resolve_backend",
|
||||
]
|
||||
|
||||
+146
-22
@@ -1,23 +1,84 @@
|
||||
"""
|
||||
Model selector for Claude/Ollama backend switching.
|
||||
Model selector for Ollama/Claude backend switching.
|
||||
|
||||
Provides automatic model selection with Claude as preferred backend
|
||||
and Ollama as offline fallback.
|
||||
Provides automatic model selection with Ollama as the primary local backend
|
||||
and Claude as the cloud fallback. Claude is used when PREFER_CLOUD_BACKEND
|
||||
is enabled, or automatically when Ollama is unavailable at startup.
|
||||
|
||||
The Anthropic SDK is imported lazily so a missing or broken `anthropic`
|
||||
package degrades to Ollama-only operation instead of crashing the app.
|
||||
"""
|
||||
|
||||
from typing import Union
|
||||
from __future__ import annotations
|
||||
|
||||
from pydantic_ai.models.anthropic import AnthropicModel
|
||||
from pydantic_ai.models.openai import OpenAIChatModel
|
||||
from pydantic_ai.providers.anthropic import AnthropicProvider
|
||||
from typing import TYPE_CHECKING
|
||||
|
||||
import httpx
|
||||
|
||||
from src.core.config import config
|
||||
from src.core.logging_config import get_logger
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from pydantic_ai.models.anthropic import AnthropicModel
|
||||
from pydantic_ai.models.openai import OpenAIChatModel
|
||||
from pydantic_ai.settings import ModelSettings
|
||||
|
||||
logger = get_logger(__name__)
|
||||
|
||||
# Cached health check result (set once at startup)
|
||||
# Cached health check results (set once at startup)
|
||||
_claude_available: bool | None = None
|
||||
_ollama_available: bool | None = None
|
||||
|
||||
|
||||
async def check_ollama_health() -> bool:
|
||||
"""
|
||||
Check if the Ollama server is reachable and has the configured model.
|
||||
|
||||
This should be called once at application startup.
|
||||
The result is cached in `_ollama_available`.
|
||||
|
||||
Returns:
|
||||
True if Ollama is reachable and OLLAMA_DEFAULT_MODEL is pulled.
|
||||
"""
|
||||
global _ollama_available
|
||||
|
||||
host = str(config.OLLAMA_HOST).rstrip("/")
|
||||
model = config.OLLAMA_DEFAULT_MODEL
|
||||
|
||||
try:
|
||||
async with httpx.AsyncClient(timeout=5.0) as client:
|
||||
response = await client.get(f"{host}/api/tags")
|
||||
response.raise_for_status()
|
||||
names = [m.get("name", "") for m in response.json().get("models", [])]
|
||||
|
||||
if model in names or f"{model}:latest" in names:
|
||||
_ollama_available = True
|
||||
logger.info(
|
||||
"ollama_health_check_passed",
|
||||
host=host,
|
||||
model=model,
|
||||
)
|
||||
return True
|
||||
|
||||
_ollama_available = False
|
||||
logger.warning(
|
||||
"ollama_health_check_failed",
|
||||
reason="model_not_pulled",
|
||||
host=host,
|
||||
model=model,
|
||||
hint=f"run `ollama pull {model}`",
|
||||
)
|
||||
return False
|
||||
|
||||
except Exception as e:
|
||||
_ollama_available = False
|
||||
logger.warning(
|
||||
"ollama_health_check_failed",
|
||||
reason="server_unreachable",
|
||||
host=host,
|
||||
error=str(e),
|
||||
)
|
||||
return False
|
||||
|
||||
|
||||
async def check_claude_health() -> bool:
|
||||
@@ -85,28 +146,69 @@ def is_claude_available() -> bool:
|
||||
return _claude_available is True
|
||||
|
||||
|
||||
def get_model(prefer_cloud: bool | None = None) -> Union[AnthropicModel, OpenAIChatModel]:
|
||||
def is_ollama_available() -> bool:
|
||||
"""
|
||||
Check if Ollama is available (from cached health check result).
|
||||
|
||||
Returns:
|
||||
False only if the startup health check confirmed Ollama is down.
|
||||
Unknown (check not run yet) counts as available so that contexts
|
||||
without lifespan events keep the local-first behavior.
|
||||
"""
|
||||
return _ollama_available is not False
|
||||
|
||||
|
||||
def resolve_backend(prefer_cloud: bool | None = None) -> str:
|
||||
"""
|
||||
Resolve which backend should serve requests.
|
||||
|
||||
Ollama is the primary backend. Claude is used when explicitly
|
||||
preferred via PREFER_CLOUD_BACKEND, or as automatic fallback
|
||||
when the startup health check found Ollama down.
|
||||
|
||||
Args:
|
||||
prefer_cloud: Override config.PREFER_CLOUD_BACKEND for this call.
|
||||
|
||||
Returns:
|
||||
"claude" or "ollama".
|
||||
"""
|
||||
use_cloud = prefer_cloud if prefer_cloud is not None else config.PREFER_CLOUD_BACKEND
|
||||
|
||||
if use_cloud and is_claude_available():
|
||||
return "claude"
|
||||
|
||||
if not is_ollama_available() and is_claude_available():
|
||||
logger.warning(
|
||||
"backend_fallback_to_claude",
|
||||
reason="ollama_unavailable",
|
||||
)
|
||||
return "claude"
|
||||
|
||||
return "ollama"
|
||||
|
||||
|
||||
def get_model(prefer_cloud: bool | None = None) -> AnthropicModel | OpenAIChatModel:
|
||||
"""
|
||||
Get the best available model.
|
||||
|
||||
Returns Claude if available and preferred, otherwise Ollama.
|
||||
Returns Ollama unless Claude is preferred (or Ollama is down).
|
||||
|
||||
Args:
|
||||
prefer_cloud: Override config.PREFER_CLOUD_BACKEND for this call.
|
||||
If None, uses the config value.
|
||||
|
||||
Returns:
|
||||
PydanticAI model instance (AnthropicModel or OpenAIChatModel).
|
||||
PydanticAI model instance (OpenAIChatModel or AnthropicModel).
|
||||
|
||||
Example:
|
||||
>>> model = get_model()
|
||||
>>> agent = Agent(model, system_prompt="...")
|
||||
"""
|
||||
# Determine preference
|
||||
use_cloud = prefer_cloud if prefer_cloud is not None else config.PREFER_CLOUD_BACKEND
|
||||
if resolve_backend(prefer_cloud) == "claude":
|
||||
try:
|
||||
from pydantic_ai.models.anthropic import AnthropicModel
|
||||
from pydantic_ai.providers.anthropic import AnthropicProvider
|
||||
|
||||
# Use Claude if available and preferred
|
||||
if use_cloud and is_claude_available():
|
||||
logger.debug(
|
||||
"model_selected",
|
||||
backend="claude",
|
||||
@@ -116,15 +218,21 @@ def get_model(prefer_cloud: bool | None = None) -> Union[AnthropicModel, OpenAIC
|
||||
model_name=config.ANTHROPIC_MODEL,
|
||||
provider=AnthropicProvider(api_key=config.ANTHROPIC_API_KEY),
|
||||
)
|
||||
except ImportError as e:
|
||||
logger.error(
|
||||
"claude_backend_import_failed",
|
||||
error=str(e),
|
||||
hint="anthropic package missing or incompatible; using Ollama",
|
||||
)
|
||||
|
||||
from pydantic_ai.models.openai import OpenAIChatModel
|
||||
|
||||
# Fall back to Ollama
|
||||
from src.ollama.provider import get_ollama_provider
|
||||
|
||||
logger.debug(
|
||||
"model_selected",
|
||||
backend="ollama",
|
||||
model=config.OLLAMA_DEFAULT_MODEL,
|
||||
reason="fallback" if use_cloud else "preferred_local",
|
||||
)
|
||||
return OpenAIChatModel(
|
||||
model_name=config.OLLAMA_DEFAULT_MODEL,
|
||||
@@ -132,7 +240,7 @@ def get_model(prefer_cloud: bool | None = None) -> Union[AnthropicModel, OpenAIC
|
||||
)
|
||||
|
||||
|
||||
def get_tool_choice_settings() -> 'ModelSettings':
|
||||
def get_tool_choice_settings() -> ModelSettings:
|
||||
"""
|
||||
Get model_settings for forcing tool calls on the first request.
|
||||
|
||||
@@ -141,7 +249,7 @@ def get_tool_choice_settings() -> 'ModelSettings':
|
||||
"""
|
||||
from pydantic_ai.settings import ModelSettings
|
||||
|
||||
if is_claude_available() and config.PREFER_CLOUD_BACKEND:
|
||||
if resolve_backend() == "claude":
|
||||
# PydanticAI's Anthropic model handles tool_choice internally
|
||||
return ModelSettings()
|
||||
else:
|
||||
@@ -149,6 +257,20 @@ def get_tool_choice_settings() -> 'ModelSettings':
|
||||
return ModelSettings(extra_body={"tool_choice": "required"})
|
||||
|
||||
|
||||
def get_sampling_settings(temperature: float) -> ModelSettings:
|
||||
"""
|
||||
Get model_settings with a sampling temperature where the backend allows it.
|
||||
|
||||
Ollama accepts a temperature; Claude Sonnet 5+ rejects sampling
|
||||
parameters, so the Claude backend gets empty settings.
|
||||
"""
|
||||
from pydantic_ai.settings import ModelSettings
|
||||
|
||||
if resolve_backend() == "claude":
|
||||
return ModelSettings()
|
||||
return ModelSettings(temperature=temperature)
|
||||
|
||||
|
||||
def get_model_info() -> dict:
|
||||
"""
|
||||
Get information about the current model configuration.
|
||||
@@ -158,12 +280,14 @@ def get_model_info() -> dict:
|
||||
Returns:
|
||||
Dict with backend, model name, and availability info.
|
||||
"""
|
||||
use_cloud = config.PREFER_CLOUD_BACKEND and is_claude_available()
|
||||
backend = resolve_backend()
|
||||
|
||||
return {
|
||||
"backend": "claude" if use_cloud else "ollama",
|
||||
"model": config.ANTHROPIC_MODEL if use_cloud else config.OLLAMA_DEFAULT_MODEL,
|
||||
"backend": backend,
|
||||
"model": config.ANTHROPIC_MODEL if backend == "claude" else config.OLLAMA_DEFAULT_MODEL,
|
||||
"claude_available": is_claude_available(),
|
||||
"claude_configured": bool(config.ANTHROPIC_API_KEY),
|
||||
"ollama_available": is_ollama_available(),
|
||||
"ollama_model": config.OLLAMA_DEFAULT_MODEL,
|
||||
"prefer_cloud": config.PREFER_CLOUD_BACKEND,
|
||||
}
|
||||
|
||||
+17
-13
@@ -7,7 +7,7 @@ import logging
|
||||
from typing import AsyncGenerator
|
||||
|
||||
from fastapi import APIRouter
|
||||
from sse_starlette.sse import EventSourceResponse
|
||||
from starlette.responses import StreamingResponse
|
||||
|
||||
from src.chat import service
|
||||
from src.chat.schemas import (
|
||||
@@ -22,36 +22,33 @@ router = APIRouter(prefix="/chat", tags=["chat"])
|
||||
|
||||
async def _stream_response(
|
||||
request: ChatCompletionRequest,
|
||||
) -> AsyncGenerator[dict, None]:
|
||||
) -> AsyncGenerator[str, None]:
|
||||
"""
|
||||
Generate SSE stream for chat completion.
|
||||
|
||||
EventSourceResponse adds "data: " prefix automatically.
|
||||
We just yield the dict/string content.
|
||||
Yields raw SSE-formatted strings matching OpenAI's format exactly:
|
||||
data: {json}\n\n
|
||||
"""
|
||||
try:
|
||||
async for chunk in service.create_chat_completion_stream(request):
|
||||
# Yield dict - EventSourceResponse will format as SSE
|
||||
yield {"data": chunk.model_dump_json()}
|
||||
yield f"data: {chunk.model_dump_json(exclude_unset=True)}\n\n"
|
||||
|
||||
# Send [DONE] message
|
||||
yield {"data": "[DONE]"}
|
||||
yield "data: [DONE]\n\n"
|
||||
|
||||
except Exception as e:
|
||||
logger.error(f"Error in streaming response: {e}")
|
||||
error_data = {"error": {"message": str(e), "type": "internal_error"}}
|
||||
yield {"data": json.dumps(error_data)}
|
||||
error_data = json.dumps({"error": {"message": str(e), "type": "internal_error"}})
|
||||
yield f"data: {error_data}\n\n"
|
||||
|
||||
|
||||
@router.post("/completions", response_model=ChatCompletionResponse)
|
||||
async def create_chat_completion(
|
||||
request: ChatCompletionRequest,
|
||||
) -> ChatCompletionResponse | EventSourceResponse:
|
||||
) -> ChatCompletionResponse | StreamingResponse:
|
||||
"""
|
||||
Create chat completion (OpenAI-compatible).
|
||||
|
||||
Supports both regular and streaming responses.
|
||||
Currently returns mock lorem ipsum responses.
|
||||
|
||||
Args:
|
||||
request: Chat completion request
|
||||
@@ -63,6 +60,13 @@ async def create_chat_completion(
|
||||
|
||||
if request.stream:
|
||||
logger.info("Streaming response requested")
|
||||
return EventSourceResponse(_stream_response(request))
|
||||
return StreamingResponse(
|
||||
_stream_response(request),
|
||||
media_type="text/event-stream",
|
||||
headers={
|
||||
"Cache-Control": "no-store",
|
||||
"X-Accel-Buffering": "no",
|
||||
},
|
||||
)
|
||||
|
||||
return await service.create_chat_completion(request)
|
||||
|
||||
+86
-22
@@ -6,9 +6,17 @@ from enum import Enum
|
||||
from functools import lru_cache
|
||||
from pathlib import Path
|
||||
|
||||
from pydantic import Field, HttpUrl
|
||||
from pydantic import Field, HttpUrl, model_validator
|
||||
from pydantic_settings import BaseSettings, SettingsConfigDict
|
||||
|
||||
# Tenant isolation constants (see docs: tenant-based isolation, no separate
|
||||
# test infrastructure). The production tenant owns real data in the shared
|
||||
# services (Qdrant/Neo4j/Wiki.js/Redis); everything non-production must run
|
||||
# under the reserved test tenant or an explicit test_-prefixed namespace.
|
||||
PRODUCTION_TENANT = "jpmschweitzer"
|
||||
TEST_TENANT = "llm_tester"
|
||||
TEST_TENANT_PREFIX = "test_"
|
||||
|
||||
|
||||
def _get_version_from_pyproject() -> str:
|
||||
"""
|
||||
@@ -64,33 +72,37 @@ class Config(BaseSettings):
|
||||
API_PORT: int = Field(default=8000, description="API port")
|
||||
API_PREFIX: str = Field(default="/v1", description="API route prefix")
|
||||
|
||||
# Anthropic Configuration (Claude - preferred backend)
|
||||
# Anthropic Configuration (Claude - cloud fallback)
|
||||
ANTHROPIC_API_KEY: str | None = Field(
|
||||
default=None,
|
||||
description="Anthropic API key for Claude access"
|
||||
description="Anthropic API key for the Claude fallback backend"
|
||||
)
|
||||
ANTHROPIC_MODEL: str = Field(
|
||||
default="claude-sonnet-4-20250514",
|
||||
description="Claude model to use"
|
||||
default="claude-sonnet-5",
|
||||
description="Claude model for the fallback backend"
|
||||
)
|
||||
PREFER_CLOUD_BACKEND: bool = Field(
|
||||
default=True,
|
||||
description="Prefer Claude over Ollama when available"
|
||||
default=False,
|
||||
description="Prefer Claude over Ollama (default: local-first)"
|
||||
)
|
||||
|
||||
# Ollama Configuration (local fallback)
|
||||
# Ollama Configuration (local - primary backend)
|
||||
OLLAMA_HOST: HttpUrl = Field(
|
||||
default="http://localhost:11434",
|
||||
description="Ollama server URL"
|
||||
)
|
||||
OLLAMA_DEFAULT_MODEL: str = Field(
|
||||
default="mistral-nemo:latest",
|
||||
default="gemma4:e2b",
|
||||
description="Default Ollama model"
|
||||
)
|
||||
OLLAMA_TIMEOUT: int = Field(
|
||||
default=120,
|
||||
description="Ollama request timeout in seconds"
|
||||
)
|
||||
STEWARD_TIMEOUT: int = Field(
|
||||
default=60,
|
||||
description="Steward analysis timeout in seconds (gemma4 needs ~35s warm)"
|
||||
)
|
||||
STREAM_TIMEOUT: int = Field(
|
||||
default=20,
|
||||
description="Timeout for each streaming turn in seconds"
|
||||
@@ -98,8 +110,8 @@ class Config(BaseSettings):
|
||||
|
||||
# SearXNG Configuration
|
||||
SEARXNG_HOST: HttpUrl = Field(
|
||||
default="http://localhost:8087",
|
||||
description="SearXNG server URL"
|
||||
default="http://searxng:8080",
|
||||
description="SearXNG server URL (container name; internal port 8080)"
|
||||
)
|
||||
SEARXNG_TIMEOUT: int = Field(
|
||||
default=30,
|
||||
@@ -121,9 +133,13 @@ class Config(BaseSettings):
|
||||
)
|
||||
|
||||
# Library-Desk Configuration (The Librarian backend)
|
||||
LIBRARIAN_TIMEOUT: int = Field(
|
||||
default=180,
|
||||
description="Total time budget for a librarian delegation in seconds"
|
||||
)
|
||||
LIBRARY_DESK_HOST: HttpUrl = Field(
|
||||
default="http://localhost:8089",
|
||||
description="Library-Desk API URL"
|
||||
default="http://library-desk:8089",
|
||||
description="Library-Desk API URL (container name; internal port 8089)"
|
||||
)
|
||||
LIBRARY_DESK_API_KEY: str = Field(
|
||||
default="",
|
||||
@@ -136,8 +152,8 @@ class Config(BaseSettings):
|
||||
|
||||
# Core-API Configuration (The Housekeeper backend)
|
||||
CORE_API_HOST: HttpUrl = Field(
|
||||
default="http://localhost:8090",
|
||||
description="Core-API URL for Home Assistant integration"
|
||||
default="http://core-api:8083",
|
||||
description="Core-API URL for Home Assistant integration (container name; internal port 8083)"
|
||||
)
|
||||
CORE_API_KEY: str = Field(
|
||||
default="",
|
||||
@@ -199,6 +215,38 @@ class Config(BaseSettings):
|
||||
CORS_ALLOW_METHODS: list[str] = ["*"]
|
||||
CORS_ALLOW_HEADERS: list[str] = ["*"]
|
||||
|
||||
@model_validator(mode="after")
|
||||
def _refuse_production_tenant_outside_production(self) -> "Config":
|
||||
"""
|
||||
Refuse startup when a non-production environment is explicitly
|
||||
configured with the production tenant.
|
||||
|
||||
This is the hard stop of the tenant isolation guard: a dev/test
|
||||
instance must never be able to read or write the production
|
||||
tenant's data in the shared services.
|
||||
|
||||
The comparison is on the sanitized form: namespaces are derived
|
||||
through sanitize_user_id(), so variants like "JPMSchweitzer" or
|
||||
"jpmschweitzer." collide with the production namespaces and are
|
||||
refused just as loudly.
|
||||
"""
|
||||
from src.core.multi_tenancy import sanitize_user_id
|
||||
|
||||
if (
|
||||
self.ENVIRONMENT != Environment.PRODUCTION
|
||||
and self.DEFAULT_USER is not None
|
||||
and sanitize_user_id(self.DEFAULT_USER)
|
||||
== sanitize_user_id(PRODUCTION_TENANT)
|
||||
):
|
||||
raise ValueError(
|
||||
f"Refusing to start: ENVIRONMENT={self.ENVIRONMENT.value} is "
|
||||
f"explicitly configured with the production tenant "
|
||||
f"'{PRODUCTION_TENANT}'. Non-production environments must use "
|
||||
f"'{TEST_TENANT}' or a '{TEST_TENANT_PREFIX}'-prefixed tenant. "
|
||||
f"Unset DEFAULT_USER or set ENVIRONMENT=production."
|
||||
)
|
||||
return self
|
||||
|
||||
@property
|
||||
def redis_memory_url(self) -> str:
|
||||
"""Construct Redis connection URL for memory cache."""
|
||||
@@ -239,16 +287,32 @@ class Config(BaseSettings):
|
||||
@property
|
||||
def effective_default_user(self) -> str:
|
||||
"""
|
||||
Get effective default user, auto-determining from environment if not set.
|
||||
Get effective default user (tenant), enforcing tenant isolation.
|
||||
|
||||
- development/testing: llm_tester (isolated test scope)
|
||||
- production: jpmschweitzer (real user)
|
||||
- production: DEFAULT_USER if set, else the production tenant
|
||||
- development/testing: FORCED to the reserved test tenant
|
||||
("llm_tester") - the only accepted overrides are the test tenant
|
||||
itself or a "test_"-prefixed namespace. Any other DEFAULT_USER
|
||||
value is treated as misconfiguration and ignored.
|
||||
"""
|
||||
if self.DEFAULT_USER is not None:
|
||||
return self.DEFAULT_USER
|
||||
if self.ENVIRONMENT == Environment.PRODUCTION:
|
||||
return "jpmschweitzer"
|
||||
return "llm_tester"
|
||||
return self.DEFAULT_USER or PRODUCTION_TENANT
|
||||
|
||||
if self.DEFAULT_USER is not None and (
|
||||
self.DEFAULT_USER == TEST_TENANT
|
||||
or self.DEFAULT_USER.startswith(TEST_TENANT_PREFIX)
|
||||
):
|
||||
return self.DEFAULT_USER
|
||||
return TEST_TENANT
|
||||
|
||||
@property
|
||||
def tenant_forced(self) -> bool:
|
||||
"""Whether the tenant guard overrode a misconfigured DEFAULT_USER."""
|
||||
return (
|
||||
self.ENVIRONMENT != Environment.PRODUCTION
|
||||
and self.DEFAULT_USER is not None
|
||||
and self.effective_default_user != self.DEFAULT_USER
|
||||
)
|
||||
|
||||
|
||||
@lru_cache
|
||||
|
||||
+38
-1
@@ -41,6 +41,41 @@ current_conversation: ContextVar[str | None] = ContextVar(
|
||||
)
|
||||
|
||||
|
||||
def apply_tenant_guard(user: str) -> str:
|
||||
"""
|
||||
Enforce tenant isolation at request-context resolution.
|
||||
|
||||
In non-production environments the production tenant must never be
|
||||
the effective user - a request that explicitly asks for it is forced
|
||||
to the reserved test tenant instead (with a loud log line).
|
||||
|
||||
Comparison happens on the *sanitized* form of the user: every local
|
||||
namespace (Qdrant collection, Redis key) is derived through
|
||||
sanitize_user_id(), so any raw variant that collides with the
|
||||
production tenant after sanitization ("JPMSchweitzer",
|
||||
"jpmschweitzer.", " jpmschweitzer", ...) would otherwise resolve to
|
||||
the production namespaces. Those variants are forced too.
|
||||
"""
|
||||
# Import here to avoid circular dependency
|
||||
from src.core.config import PRODUCTION_TENANT, TEST_TENANT, Environment, config
|
||||
from src.core.multi_tenancy import sanitize_user_id
|
||||
|
||||
if (
|
||||
config.ENVIRONMENT != Environment.PRODUCTION
|
||||
and sanitize_user_id(user) == sanitize_user_id(PRODUCTION_TENANT)
|
||||
):
|
||||
from src.core.logging_config import get_logger
|
||||
|
||||
get_logger(__name__).warning(
|
||||
"tenant_guard_forced",
|
||||
environment=config.ENVIRONMENT.value,
|
||||
requested_tenant=user,
|
||||
forced_tenant=TEST_TENANT,
|
||||
)
|
||||
return TEST_TENANT
|
||||
return user
|
||||
|
||||
|
||||
def get_user() -> str:
|
||||
"""
|
||||
Get current user from request context.
|
||||
@@ -48,6 +83,8 @@ def get_user() -> str:
|
||||
Returns:
|
||||
User identifier for the current request.
|
||||
Falls back to environment-aware default if not set.
|
||||
In non-production environments the production tenant is never
|
||||
returned - the tenant guard forces the reserved test tenant.
|
||||
|
||||
Example:
|
||||
user = get_user() # "llm_tester" (dev) or "jpmschweitzer" (prod)
|
||||
@@ -55,7 +92,7 @@ def get_user() -> str:
|
||||
user = current_user.get()
|
||||
if user == _USER_NOT_SET:
|
||||
return get_default_user()
|
||||
return user
|
||||
return apply_tenant_guard(user)
|
||||
|
||||
|
||||
def get_conversation_id() -> str | None:
|
||||
|
||||
@@ -273,65 +273,6 @@ class HouseholdRegistry:
|
||||
|
||||
return tools
|
||||
|
||||
def get_streaming_delegation_tools(self, names: list[str]) -> list[Any]:
|
||||
"""
|
||||
Get streaming delegation wrapper tools for specified capabilities.
|
||||
|
||||
Similar to get_delegation_tools() but returns streaming wrappers
|
||||
that yield butler-perspective think messages during execution.
|
||||
|
||||
These wrappers emit think slugs like:
|
||||
- "Allow me to consult the archives, sir."
|
||||
- "The Librarian has compiled the relevant findings."
|
||||
|
||||
Args:
|
||||
names: List of member names to include
|
||||
|
||||
Returns:
|
||||
List of streaming delegation wrappers and/or raw tools
|
||||
|
||||
Example:
|
||||
>>> tools = registry.get_streaming_delegation_tools(["librarian"])
|
||||
>>> async for chunk in tools[0](task="Search for Docker"):
|
||||
... print(chunk) # Yields think messages then result
|
||||
"""
|
||||
from src.agents.delegation import STREAMING_DELEGATION_WRAPPERS
|
||||
|
||||
tools = []
|
||||
for name in names:
|
||||
member = self._members.get(name)
|
||||
if not member:
|
||||
logger.warning(
|
||||
"household_member_not_found",
|
||||
requested_name=name,
|
||||
available_names=list(self._members.keys()),
|
||||
)
|
||||
continue
|
||||
|
||||
# Check if this member has a streaming delegation wrapper
|
||||
if name in STREAMING_DELEGATION_WRAPPERS and member.agent is not None:
|
||||
tools.append(STREAMING_DELEGATION_WRAPPERS[name])
|
||||
logger.debug(
|
||||
"streaming_delegation_wrapper_added",
|
||||
member=name,
|
||||
)
|
||||
else:
|
||||
# No agent = direct tools (e.g., tatlock_core)
|
||||
tools.extend(member.tools)
|
||||
logger.debug(
|
||||
"raw_tools_added",
|
||||
member=name,
|
||||
tool_count=len(member.tools),
|
||||
)
|
||||
|
||||
logger.info(
|
||||
"streaming_delegation_tools_created",
|
||||
requested_members=names,
|
||||
total_tools=len(tools),
|
||||
)
|
||||
|
||||
return tools
|
||||
|
||||
def list_members(self) -> list[str]:
|
||||
"""
|
||||
List all registered member names.
|
||||
|
||||
+38
-3
@@ -9,13 +9,43 @@ from src.agents.biographer import register_biographer
|
||||
from src.agents.housekeeper import register_housekeeper
|
||||
from src.agents.librarian import register_librarian
|
||||
from src.agents.tatlock_core import TATLOCK_CORE_CAPABILITY, tatlock_core_tools
|
||||
from src.anthropic.model_selector import check_claude_health, get_model_info
|
||||
from src.anthropic.model_selector import (
|
||||
check_claude_health,
|
||||
check_ollama_health,
|
||||
get_model_info,
|
||||
)
|
||||
from src.core.config import Environment, config
|
||||
from src.core.household_registry import get_household_registry
|
||||
from src.core.logging_config import get_logger
|
||||
|
||||
logger = get_logger(__name__)
|
||||
|
||||
|
||||
def log_tenant_guard() -> None:
|
||||
"""
|
||||
Emit one loud startup log line stating the effective tenant.
|
||||
|
||||
In non-production environments the tenant guard forces the reserved
|
||||
test tenant regardless of DEFAULT_USER misconfiguration - this line
|
||||
makes that override visible at startup.
|
||||
"""
|
||||
if config.ENVIRONMENT == Environment.PRODUCTION:
|
||||
logger.info(
|
||||
"tenant_guard_production",
|
||||
environment=config.ENVIRONMENT.value,
|
||||
tenant=config.effective_default_user,
|
||||
)
|
||||
return
|
||||
|
||||
logger.warning(
|
||||
"tenant_guard_active",
|
||||
environment=config.ENVIRONMENT.value,
|
||||
forced_tenant=config.effective_default_user,
|
||||
default_user_overridden=config.tenant_forced,
|
||||
configured_default_user=config.DEFAULT_USER,
|
||||
)
|
||||
|
||||
|
||||
def register_household_members():
|
||||
"""
|
||||
Register all household members with the registry.
|
||||
@@ -87,7 +117,7 @@ async def initialize_application():
|
||||
Initialize the application.
|
||||
|
||||
Performs all startup tasks:
|
||||
1. Check Claude API health (for backend selection)
|
||||
1. Check Ollama (primary) and Claude (fallback) health for backend selection
|
||||
2. Register household members
|
||||
3. (Future) Initialize connections
|
||||
|
||||
@@ -95,13 +125,18 @@ async def initialize_application():
|
||||
"""
|
||||
logger.info("application_initialization_starting")
|
||||
|
||||
# Check Claude API health for backend selection
|
||||
# Tenant isolation guard: state the effective tenant loudly
|
||||
log_tenant_guard()
|
||||
|
||||
# Check backend health: Ollama is primary, Claude is the fallback
|
||||
await check_ollama_health()
|
||||
await check_claude_health()
|
||||
model_info = get_model_info()
|
||||
logger.info(
|
||||
"model_backend_configured",
|
||||
backend=model_info["backend"],
|
||||
model=model_info["model"],
|
||||
ollama_available=model_info["ollama_available"],
|
||||
claude_available=model_info["claude_available"],
|
||||
)
|
||||
|
||||
|
||||
+17
-6
@@ -40,14 +40,21 @@ class TatlockOllamaProvider(OllamaProvider):
|
||||
# Override the client with our sanitized version
|
||||
self._openai_client = _SanitizedAsyncOpenAI(base_url=base_url)
|
||||
|
||||
logger.debug("tatlock_ollama_provider_created", base_url=base_url)
|
||||
logger.debug(
|
||||
"tatlock_ollama_provider_created",
|
||||
base_url=base_url,
|
||||
timeout=config.OLLAMA_TIMEOUT,
|
||||
)
|
||||
|
||||
|
||||
class _SanitizedAsyncOpenAI(AsyncOpenAI):
|
||||
"""AsyncOpenAI client that sanitizes messages before sending."""
|
||||
|
||||
def __init__(self, **kwargs: Any):
|
||||
# Ollama doesn't need an API key
|
||||
# Ollama doesn't need an API key. Cap each LLM call at the
|
||||
# configured Ollama timeout instead of the SDK default (~600s),
|
||||
# so one stuck request cannot eat the whole delegation budget.
|
||||
kwargs.setdefault("timeout", float(config.OLLAMA_TIMEOUT))
|
||||
super().__init__(api_key="ollama", **kwargs)
|
||||
|
||||
@property
|
||||
@@ -106,13 +113,17 @@ def _sanitize_messages(messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
|
||||
for msg in messages:
|
||||
msg_copy = dict(msg)
|
||||
|
||||
# Fix null content in assistant messages with tool calls
|
||||
if msg_copy.get("role") == "assistant":
|
||||
if msg_copy.get("content") is None and msg_copy.get("tool_calls"):
|
||||
# Fix null content in ANY message: Ollama rejects content: null with
|
||||
# "invalid message content type: <nil>". The tool-call-only assistant
|
||||
# case is the common one, but gemma thinking-only turns produce
|
||||
# assistant messages with null content and NO tool_calls, which
|
||||
# previously slipped through and 400'd the whole agent run.
|
||||
if "content" in msg_copy and msg_copy.get("content") is None:
|
||||
msg_copy["content"] = ""
|
||||
logger.debug(
|
||||
"sanitized_null_content",
|
||||
tool_call_count=len(msg_copy["tool_calls"]),
|
||||
role=msg_copy.get("role"),
|
||||
tool_call_count=len(msg_copy.get("tool_calls") or []),
|
||||
)
|
||||
|
||||
sanitized.append(msg_copy)
|
||||
|
||||
+98
-49
@@ -6,32 +6,32 @@ Tracks conversation history for analytics and future vector memory.
|
||||
Integrates with Steward preprocessing for Phase 2 two-tier architecture.
|
||||
"""
|
||||
|
||||
import time
|
||||
import asyncio
|
||||
import re
|
||||
import secrets
|
||||
from typing import AsyncGenerator
|
||||
import time
|
||||
from collections.abc import AsyncGenerator
|
||||
|
||||
from src.agents.delegation import build_delegation_context, get_think_message
|
||||
from src.agents.registry import ModelRegistry
|
||||
from src.agents.steward.schemas import StewardRecommendation
|
||||
from src.core.context import current_conversation, current_user, get_default_user
|
||||
from src.core.logging_config import get_logger
|
||||
from src.core.preprocessing import preprocess_request
|
||||
from src.core.tool_tracking import ToolCallTracker
|
||||
from src.core.tracing import SpanType, end_trace, start_span, start_trace
|
||||
from src.responses.context import ContextWindow
|
||||
from src.responses.history import ConversationHistory
|
||||
from src.responses.schemas import (
|
||||
FunctionCallOutputItem,
|
||||
MessageOutputItem,
|
||||
OutputTextContent,
|
||||
ReasoningOutputItem,
|
||||
Response,
|
||||
ResponseRequest,
|
||||
ResponseUsage,
|
||||
MessageOutputItem,
|
||||
ReasoningOutputItem,
|
||||
FunctionCallOutputItem,
|
||||
OutputTextContent,
|
||||
)
|
||||
from src.responses.streaming import StreamingCoordinator
|
||||
from src.responses.history import ConversationHistory
|
||||
from src.responses.context import ContextWindow
|
||||
from src.core.preprocessing import preprocess_request
|
||||
from src.core.tool_tracking import ToolCallTracker
|
||||
from src.core.logging_config import get_logger
|
||||
from src.core.tracing import start_trace, end_trace, start_span, SpanType
|
||||
from src.core.context import current_user, current_conversation, get_default_user
|
||||
from src.agents.steward.schemas import StewardRecommendation
|
||||
|
||||
import re
|
||||
import asyncio
|
||||
|
||||
logger = get_logger(__name__)
|
||||
|
||||
@@ -63,7 +63,8 @@ async def _execute_single_delegation(
|
||||
agent_name: str,
|
||||
task: str,
|
||||
tracker: "ToolCallTracker",
|
||||
) -> tuple[str, str]:
|
||||
context: str = "",
|
||||
) -> tuple[str, str, bool]:
|
||||
"""
|
||||
Execute a single delegation to an agent.
|
||||
|
||||
@@ -71,36 +72,38 @@ async def _execute_single_delegation(
|
||||
agent_name: Name of agent (biographer, librarian, housekeeper)
|
||||
task: Task description
|
||||
tracker: Tool call tracker
|
||||
context: Trimmed conversation context for the expert
|
||||
|
||||
Returns:
|
||||
tuple: (agent_name, result_summary)
|
||||
tuple: (agent_name, result_summary, success). On failure the
|
||||
result summary is a curated user-safe sentence.
|
||||
"""
|
||||
import time
|
||||
start_time = time.time()
|
||||
|
||||
if agent_name == "biographer":
|
||||
from src.agents.delegation import delegate_to_biographer
|
||||
result = await delegate_to_biographer(task=task)
|
||||
result = await delegate_to_biographer(task=task, context=context)
|
||||
duration = time.time() - start_time
|
||||
await tracker.track_call("delegate_to_biographer", duration)
|
||||
return (agent_name, result.output)
|
||||
return (agent_name, result.output, result.success)
|
||||
|
||||
elif agent_name == "librarian":
|
||||
from src.agents.delegation import delegate_to_librarian
|
||||
result = await delegate_to_librarian(task=task)
|
||||
result = await delegate_to_librarian(task=task, context=context)
|
||||
duration = time.time() - start_time
|
||||
await tracker.track_call("delegate_to_librarian", duration)
|
||||
return (agent_name, result.output)
|
||||
return (agent_name, result.output, result.success)
|
||||
|
||||
elif agent_name == "housekeeper":
|
||||
from src.agents.delegation import delegate_to_housekeeper
|
||||
result = await delegate_to_housekeeper(task=task)
|
||||
result = await delegate_to_housekeeper(task=task, context=context)
|
||||
duration = time.time() - start_time
|
||||
await tracker.track_call("delegate_to_housekeeper", duration)
|
||||
return (agent_name, result.output)
|
||||
return (agent_name, result.output, result.success)
|
||||
|
||||
else:
|
||||
return (agent_name, f"Unknown agent: {agent_name}")
|
||||
return (agent_name, f"Unknown agent: {agent_name}", False)
|
||||
|
||||
|
||||
async def _handle_text_delegation(
|
||||
@@ -175,13 +178,39 @@ async def _handle_text_delegation(
|
||||
]
|
||||
results = await asyncio.gather(*tasks, return_exceptions=True)
|
||||
|
||||
# Combine results
|
||||
# asyncio.gather returns exactly one item per task; a length
|
||||
# mismatch would mean results are attributed to the wrong
|
||||
# agent, so fail loudly instead of mispairing silently.
|
||||
if len(results) != len(matches):
|
||||
logger.error(
|
||||
"delegation_result_count_mismatch",
|
||||
expected=len(matches),
|
||||
got=len(results),
|
||||
conversation_id=conversation_id,
|
||||
)
|
||||
return (
|
||||
"I apologize, sir. I was unable to complete the "
|
||||
"requested delegations."
|
||||
)
|
||||
|
||||
# Combine results (failures carry curated user-safe sentences)
|
||||
summaries = []
|
||||
for agent_name, result in results:
|
||||
if isinstance(result, Exception):
|
||||
summaries.append(f"**{agent_name}**: Error - {result}")
|
||||
for (agent, task), item in zip(matches, results, strict=True):
|
||||
agent_name = agent.lower()
|
||||
if isinstance(item, BaseException):
|
||||
logger.error(
|
||||
"delegation_failed",
|
||||
agent=agent_name,
|
||||
error=str(item),
|
||||
conversation_id=conversation_id,
|
||||
)
|
||||
summaries.append(
|
||||
f"**{agent_name}**: "
|
||||
f"{get_think_message(agent_name, task, 'error')}"
|
||||
)
|
||||
else:
|
||||
summaries.append(f"**{agent_name}**: {result}")
|
||||
_, output, _ = item
|
||||
summaries.append(f"**{agent_name}**: {output}")
|
||||
|
||||
return "\n\n".join(summaries)
|
||||
|
||||
@@ -197,20 +226,19 @@ async def _handle_text_delegation(
|
||||
conversation_id=conversation_id,
|
||||
)
|
||||
try:
|
||||
_, result = await _execute_single_delegation(
|
||||
_, output, _ = await _execute_single_delegation(
|
||||
agent_name, task, tracker
|
||||
)
|
||||
summaries.append(result)
|
||||
summaries.append(output)
|
||||
except Exception as e:
|
||||
logger.error(
|
||||
"delegation_failed",
|
||||
agent=agent_name,
|
||||
error=str(e),
|
||||
conversation_id=conversation_id,
|
||||
exc_info=True,
|
||||
)
|
||||
summaries.append(
|
||||
f"I apologize, sir. Delegation to {agent_name} failed: {e}"
|
||||
)
|
||||
summaries.append(get_think_message(agent_name, task, "error"))
|
||||
|
||||
return "\n\n".join(summaries)
|
||||
|
||||
@@ -219,8 +247,9 @@ async def _handle_text_delegation(
|
||||
"text_delegation_failed",
|
||||
error=str(e),
|
||||
conversation_id=conversation_id,
|
||||
exc_info=True,
|
||||
)
|
||||
return f"I apologize, sir. I encountered an error processing delegations: {e}"
|
||||
return "I apologize, sir. I was unable to complete the requested delegations."
|
||||
|
||||
|
||||
async def _direct_delegation(
|
||||
@@ -254,13 +283,14 @@ async def _direct_delegation(
|
||||
results = []
|
||||
for agent in recommendation.recommended_capabilities:
|
||||
try:
|
||||
agent_name, result = await _execute_single_delegation(
|
||||
agent_name, result, success = await _execute_single_delegation(
|
||||
agent, user_message, tracker
|
||||
)
|
||||
results.append(result)
|
||||
logger.info(
|
||||
"direct_delegation_complete",
|
||||
agent=agent_name,
|
||||
success=success,
|
||||
result_preview=result[:100] if result else "empty",
|
||||
conversation_id=conversation_id,
|
||||
)
|
||||
@@ -270,8 +300,9 @@ async def _direct_delegation(
|
||||
agent=agent,
|
||||
error=str(e),
|
||||
conversation_id=conversation_id,
|
||||
exc_info=True,
|
||||
)
|
||||
results.append(f"I apologize, sir. Delegation to {agent} failed: {e}")
|
||||
results.append(get_think_message(agent, user_message, "error"))
|
||||
|
||||
return "\n\n".join(results) if results else "I apologize, sir. No delegation results available."
|
||||
|
||||
@@ -281,6 +312,7 @@ async def _direct_delegation_with_results(
|
||||
recommendation: "StewardRecommendation",
|
||||
tracker: "ToolCallTracker",
|
||||
conversation_id: str,
|
||||
conversation_history: list | None = None,
|
||||
) -> dict:
|
||||
"""
|
||||
Directly delegate to expert agents and return structured results.
|
||||
@@ -294,6 +326,7 @@ async def _direct_delegation_with_results(
|
||||
recommendation: Steward's recommendation
|
||||
tracker: Tool call tracker
|
||||
conversation_id: Conversation ID
|
||||
conversation_history: Prior turns, trimmed into expert context
|
||||
|
||||
Returns:
|
||||
dict: Orchestration results with expert_results, tool_outputs, etc.
|
||||
@@ -306,18 +339,21 @@ async def _direct_delegation_with_results(
|
||||
|
||||
expert_results = {}
|
||||
tools_called = []
|
||||
context = build_delegation_context(conversation_history)
|
||||
|
||||
for agent in recommendation.recommended_capabilities:
|
||||
try:
|
||||
agent_name, result = await _execute_single_delegation(
|
||||
agent, user_message, tracker
|
||||
agent_name, result, success = await _execute_single_delegation(
|
||||
agent, user_message, tracker, context=context
|
||||
)
|
||||
expert_results[agent_name] = result
|
||||
if success:
|
||||
tools_called.append(f"delegate_to_{agent_name}")
|
||||
|
||||
logger.info(
|
||||
"direct_delegation_result",
|
||||
agent=agent_name,
|
||||
success=success,
|
||||
result_preview=result[:100] if result else "empty",
|
||||
conversation_id=conversation_id,
|
||||
)
|
||||
@@ -327,8 +363,9 @@ async def _direct_delegation_with_results(
|
||||
agent=agent,
|
||||
error=str(e),
|
||||
conversation_id=conversation_id,
|
||||
exc_info=True,
|
||||
)
|
||||
expert_results[agent] = f"Error: {e}"
|
||||
expert_results[agent] = get_think_message(agent, user_message, "error")
|
||||
|
||||
return {
|
||||
"tools_called": tools_called,
|
||||
@@ -439,7 +476,7 @@ async def create_response(request: ResponseRequest) -> Response:
|
||||
user_input = _extract_user_input(request.input)
|
||||
|
||||
# Start trace
|
||||
trace = start_trace(
|
||||
start_trace(
|
||||
conversation_id=conversation_id,
|
||||
user=effective_user,
|
||||
request={
|
||||
@@ -451,7 +488,7 @@ async def create_response(request: ResponseRequest) -> Response:
|
||||
)
|
||||
|
||||
# Start service span
|
||||
service_span = start_span(
|
||||
start_span(
|
||||
"create_response",
|
||||
SpanType.ROUTER,
|
||||
metadata={"model": request.model, "user": effective_user},
|
||||
@@ -509,7 +546,7 @@ async def create_response(request: ResponseRequest) -> Response:
|
||||
|
||||
return response
|
||||
|
||||
except Exception as e:
|
||||
except Exception:
|
||||
end_trace(status="error")
|
||||
raise
|
||||
|
||||
@@ -550,7 +587,7 @@ async def create_response_with_steward(request: ResponseRequest) -> Response:
|
||||
user_input = _extract_user_input(request.input)
|
||||
|
||||
# Start trace
|
||||
trace = start_trace(
|
||||
start_trace(
|
||||
conversation_id=conversation_id,
|
||||
user=effective_user,
|
||||
request={
|
||||
@@ -562,7 +599,7 @@ async def create_response_with_steward(request: ResponseRequest) -> Response:
|
||||
)
|
||||
|
||||
# Start service span
|
||||
service_span = start_span(
|
||||
start_span(
|
||||
"create_response_with_steward",
|
||||
SpanType.ROUTER,
|
||||
metadata={"model": request.model, "user": effective_user},
|
||||
@@ -617,7 +654,11 @@ async def create_response_with_steward(request: ResponseRequest) -> Response:
|
||||
if delegation_only:
|
||||
# Direct delegation path - collect results then synthesize
|
||||
orchestration_results = await _direct_delegation_with_results(
|
||||
effective_query, enriched.recommendation, tracker, conversation_id
|
||||
effective_query,
|
||||
enriched.recommendation,
|
||||
tracker,
|
||||
conversation_id,
|
||||
conversation_history=conversation_history,
|
||||
)
|
||||
else:
|
||||
# Phase 1: Orchestrate tool calls
|
||||
@@ -651,6 +692,14 @@ async def create_response_with_steward(request: ResponseRequest) -> Response:
|
||||
# Build response output items
|
||||
output_items = []
|
||||
|
||||
# Add Steward reasoning as reasoning output
|
||||
if enriched.steward_reasoning:
|
||||
output_items.append(ReasoningOutputItem(
|
||||
id=f"rs_{generate_id()}",
|
||||
summary=[enriched.steward_reasoning],
|
||||
status="completed"
|
||||
))
|
||||
|
||||
# Add Tatlock's message
|
||||
output_items.append(MessageOutputItem(
|
||||
id=f"msg_{generate_id()}",
|
||||
@@ -698,7 +747,7 @@ async def create_response_with_steward(request: ResponseRequest) -> Response:
|
||||
|
||||
return response
|
||||
|
||||
except Exception as e:
|
||||
except Exception:
|
||||
end_trace(status="error")
|
||||
raise
|
||||
|
||||
|
||||
+90
-53
@@ -8,14 +8,22 @@ Handles Server-Sent Events (SSE) streaming with proper event types:
|
||||
- response.done
|
||||
"""
|
||||
|
||||
from enum import Enum
|
||||
from typing import Literal, AsyncGenerator
|
||||
import json
|
||||
import time
|
||||
from collections.abc import AsyncGenerator
|
||||
from enum import Enum
|
||||
from typing import TYPE_CHECKING, Literal
|
||||
|
||||
from src.agents.registry import ModelRegistry
|
||||
from src.core.logging_config import get_logger
|
||||
from src.core.models import CustomBaseModel
|
||||
from src.responses.schemas import Response
|
||||
from src.agents.registry import ModelRegistry
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from src.agents.steward.schemas import StewardRecommendation
|
||||
from src.core.tool_tracking import ToolCallTracker
|
||||
from src.responses.schemas import ResponseRequest
|
||||
|
||||
logger = get_logger(__name__)
|
||||
|
||||
|
||||
# ============================================================================
|
||||
@@ -131,18 +139,17 @@ class StreamingCoordinator:
|
||||
Yields:
|
||||
StreamEvent: Stream of SSE events
|
||||
"""
|
||||
from src.responses.service import (
|
||||
_calculate_usage,
|
||||
generate_id,
|
||||
_conversation_history,
|
||||
_direct_delegation_with_results,
|
||||
)
|
||||
import asyncio
|
||||
|
||||
from src.agents.tatlock import TatlockAgent
|
||||
from src.core.preprocessing import preprocess_request
|
||||
from src.core.tool_tracking import ToolCallTracker
|
||||
from src.responses.schemas import MessageOutputItem, ReasoningOutputItem, OutputTextContent
|
||||
from src.agents.tatlock import TatlockAgent
|
||||
from src.agents.delegation import get_think_message, STREAMING_DELEGATION_WRAPPERS
|
||||
import asyncio
|
||||
from src.responses.schemas import MessageOutputItem, OutputTextContent
|
||||
from src.responses.service import (
|
||||
_calculate_usage,
|
||||
_conversation_history,
|
||||
generate_id,
|
||||
)
|
||||
|
||||
output_items = []
|
||||
|
||||
@@ -182,20 +189,18 @@ class StreamingCoordinator:
|
||||
tatlock = TatlockAgent()
|
||||
|
||||
if delegation_only:
|
||||
# Direct delegation path with streaming think slugs
|
||||
orchestration_results = await self._stream_direct_delegation(
|
||||
# Direct delegation path - think slugs stream in real time,
|
||||
# BEFORE and after each expert runs (not after the fact)
|
||||
orchestration_results: dict = {}
|
||||
async for event in self._stream_direct_delegation(
|
||||
user_message=user_message,
|
||||
recommendation=enriched.recommendation,
|
||||
tracker=tracker,
|
||||
conversation_id=conversation_id,
|
||||
)
|
||||
|
||||
# Stream think slugs that were collected during delegation
|
||||
# Each think message is complete, so we signal done after each
|
||||
for think_msg in orchestration_results.get("think_messages", []):
|
||||
yield ReasoningSummaryDelta(delta=think_msg)
|
||||
yield ReasoningSummaryDone()
|
||||
await asyncio.sleep(0.05)
|
||||
conversation_history=conversation_history,
|
||||
results=orchestration_results,
|
||||
):
|
||||
yield event
|
||||
|
||||
else:
|
||||
# Phase 1: Orchestrate tool calls
|
||||
@@ -265,47 +270,66 @@ class StreamingCoordinator:
|
||||
recommendation: "StewardRecommendation", # type: ignore
|
||||
tracker: "ToolCallTracker", # type: ignore
|
||||
conversation_id: str,
|
||||
) -> dict:
|
||||
conversation_history: list | None = None,
|
||||
results: dict | None = None,
|
||||
) -> AsyncGenerator[StreamEvent, None]:
|
||||
"""
|
||||
Execute direct delegation with streaming think messages.
|
||||
Execute direct delegation, streaming think messages in real time.
|
||||
|
||||
Collects think messages as delegations execute for streaming to client.
|
||||
An async generator: the "start" think message for each expert is
|
||||
yielded BEFORE its research runs (so the user sees 'Allow me to
|
||||
consult the archives, sir.' while waiting), and the success/error
|
||||
message right after it finishes.
|
||||
|
||||
Args:
|
||||
user_message: User's request
|
||||
recommendation: Steward's recommendation
|
||||
tracker: Tool call tracker
|
||||
conversation_id: Conversation ID
|
||||
conversation_history: Prior turns, trimmed into expert context
|
||||
results: Mutable dict populated with orchestration results
|
||||
(expert_results, tools_called, think_messages, ...)
|
||||
|
||||
Returns:
|
||||
dict: Orchestration results with think_messages list
|
||||
Yields:
|
||||
StreamEvent: Reasoning summary events as delegation progresses
|
||||
"""
|
||||
import time as time_module
|
||||
|
||||
from src.agents.delegation import (
|
||||
get_think_message,
|
||||
delegate_to_librarian,
|
||||
build_delegation_context,
|
||||
delegate_to_biographer,
|
||||
delegate_to_housekeeper,
|
||||
delegate_to_librarian,
|
||||
get_think_message,
|
||||
)
|
||||
import time as time_module
|
||||
|
||||
expert_results = {}
|
||||
tools_called = []
|
||||
think_messages = []
|
||||
context = build_delegation_context(conversation_history)
|
||||
|
||||
for agent in recommendation.recommended_capabilities:
|
||||
# Emit start think message
|
||||
# Emit start think message BEFORE the expert runs
|
||||
start_msg = get_think_message(agent, user_message, "start")
|
||||
think_messages.append(start_msg + "\n")
|
||||
yield ReasoningSummaryDelta(delta=start_msg + "\n")
|
||||
yield ReasoningSummaryDone()
|
||||
|
||||
start_time = time_module.time()
|
||||
try:
|
||||
# Execute delegation
|
||||
if agent == "librarian":
|
||||
result = await delegate_to_librarian(task=user_message)
|
||||
result = await delegate_to_librarian(
|
||||
task=user_message, context=context
|
||||
)
|
||||
elif agent == "biographer":
|
||||
result = await delegate_to_biographer(task=user_message)
|
||||
result = await delegate_to_biographer(
|
||||
task=user_message, context=context
|
||||
)
|
||||
elif agent == "housekeeper":
|
||||
result = await delegate_to_housekeeper(task=user_message)
|
||||
result = await delegate_to_housekeeper(
|
||||
task=user_message, context=context
|
||||
)
|
||||
else:
|
||||
result = None
|
||||
|
||||
@@ -316,27 +340,39 @@ class StreamingCoordinator:
|
||||
expert_results[agent] = result.output
|
||||
tools_called.append(f"delegate_to_{agent}")
|
||||
# Emit success think message
|
||||
success_msg = get_think_message(agent, user_message, "success")
|
||||
think_messages.append(success_msg + "\n")
|
||||
phase_msg = get_think_message(agent, user_message, "success")
|
||||
else:
|
||||
error_msg = result.error if result else "Unknown error"
|
||||
expert_results[agent] = f"Error: {error_msg}"
|
||||
# Emit error think message
|
||||
error_think = get_think_message(agent, user_message, "error")
|
||||
think_messages.append(error_think + "\n")
|
||||
# Failed delegations carry a curated user-safe sentence
|
||||
# in output; exception detail is already in the logs.
|
||||
phase_msg = get_think_message(agent, user_message, "error")
|
||||
if result and result.output:
|
||||
expert_results[agent] = result.output
|
||||
else:
|
||||
expert_results[agent] = phase_msg
|
||||
|
||||
except Exception as e:
|
||||
expert_results[agent] = f"Error: {e}"
|
||||
error_think = get_think_message(agent, user_message, "error")
|
||||
think_messages.append(error_think + "\n")
|
||||
logger.error(
|
||||
"direct_delegation_stream_error",
|
||||
agent=agent,
|
||||
error=str(e),
|
||||
conversation_id=conversation_id,
|
||||
exc_info=True,
|
||||
)
|
||||
phase_msg = get_think_message(agent, user_message, "error")
|
||||
expert_results[agent] = phase_msg
|
||||
|
||||
return {
|
||||
think_messages.append(phase_msg + "\n")
|
||||
yield ReasoningSummaryDelta(delta=phase_msg + "\n")
|
||||
yield ReasoningSummaryDone()
|
||||
|
||||
if results is not None:
|
||||
results.update({
|
||||
"tools_called": tools_called,
|
||||
"expert_results": expert_results,
|
||||
"tool_outputs": {},
|
||||
"raw_output": "",
|
||||
"think_messages": think_messages,
|
||||
}
|
||||
})
|
||||
|
||||
async def stream_response(
|
||||
self,
|
||||
@@ -361,9 +397,10 @@ class StreamingCoordinator:
|
||||
event: response.done
|
||||
data: {"response": {...}}
|
||||
"""
|
||||
from src.responses.service import _calculate_usage, generate_id
|
||||
import asyncio
|
||||
|
||||
from src.responses.service import _calculate_usage, generate_id
|
||||
|
||||
output_items = []
|
||||
last_message_text = "" # Track last streamed message text to compute deltas
|
||||
|
||||
@@ -488,10 +525,10 @@ class StreamingCoordinator:
|
||||
def _convert_output_items(self, items: list) -> list:
|
||||
"""Convert agent OutputItem objects to schema OutputItem objects."""
|
||||
from src.responses.schemas import (
|
||||
MessageOutputItem,
|
||||
ReasoningOutputItem,
|
||||
FunctionCallOutputItem,
|
||||
MessageOutputItem,
|
||||
OutputTextContent,
|
||||
ReasoningOutputItem,
|
||||
)
|
||||
|
||||
converted = []
|
||||
@@ -521,9 +558,9 @@ class StreamingCoordinator:
|
||||
def _create_error_event(self, error: Exception) -> ErrorEvent:
|
||||
"""Create error event from exception."""
|
||||
from src.core.exceptions import (
|
||||
RateLimitError,
|
||||
ContextLengthError,
|
||||
AppException,
|
||||
ContextLengthError,
|
||||
RateLimitError,
|
||||
)
|
||||
|
||||
if isinstance(error, RateLimitError):
|
||||
|
||||
@@ -0,0 +1,268 @@
|
||||
{
|
||||
"query": "home server infrastructure",
|
||||
"keywords": {
|
||||
"core_keywords": [
|
||||
"home",
|
||||
"server",
|
||||
"infrastructure"
|
||||
],
|
||||
"entities": [],
|
||||
"synonyms": {},
|
||||
"expansions": {}
|
||||
},
|
||||
"results": [
|
||||
{
|
||||
"source_type": "wiki",
|
||||
"title": "Tower of Joy - AI Butler System",
|
||||
"content": "",
|
||||
"url": null,
|
||||
"page_id": 146,
|
||||
"page_path": "users/jpmschweitzer/projects/tower-of-joy",
|
||||
"paperless_id": null,
|
||||
"rrf_score": 0.01639344262295082,
|
||||
"final_rank": 1,
|
||||
"sources": [
|
||||
"graph"
|
||||
],
|
||||
"related_dossiers": [
|
||||
{
|
||||
"page_id": 161,
|
||||
"title": "Library Desk - Knowledge Management",
|
||||
"path": "users/jpmschweitzer/projects/tower-of-joy/applications/library-desk",
|
||||
"tag": "ai",
|
||||
"shared_entities": 13
|
||||
},
|
||||
{
|
||||
"page_id": 161,
|
||||
"title": "Library Desk - Knowledge Management",
|
||||
"path": "users/jpmschweitzer/projects/tower-of-joy/applications/library-desk",
|
||||
"tag": "dossier:tatlock",
|
||||
"shared_entities": 13
|
||||
},
|
||||
{
|
||||
"page_id": 161,
|
||||
"title": "Library Desk - Knowledge Management",
|
||||
"path": "users/jpmschweitzer/projects/tower-of-joy/applications/library-desk",
|
||||
"tag": "applications",
|
||||
"shared_entities": 13
|
||||
},
|
||||
{
|
||||
"page_id": 167,
|
||||
"title": "Qdrant - Vector Database",
|
||||
"path": "users/jpmschweitzer/projects/tower-of-joy/applications/qdrant",
|
||||
"tag": "vector",
|
||||
"shared_entities": 12
|
||||
},
|
||||
{
|
||||
"page_id": 167,
|
||||
"title": "Qdrant - Vector Database",
|
||||
"path": "users/jpmschweitzer/projects/tower-of-joy/applications/qdrant",
|
||||
"tag": "dossier:tatlock",
|
||||
"shared_entities": 12
|
||||
}
|
||||
],
|
||||
"metadata": {
|
||||
"entity_matches": 3,
|
||||
"matched_entities": [
|
||||
"Infrastructure Services",
|
||||
"Infrastructure Layer\nThe"
|
||||
],
|
||||
"engine": null
|
||||
}
|
||||
},
|
||||
{
|
||||
"source_type": "web",
|
||||
"title": "What do I need to start a home server ? Can I go in almost blind",
|
||||
"content": "You don't need industrial grade hardware to be a server. You may get better reliability and management options from that, but they can all run\u00a0...",
|
||||
"url": "https://www.reddit.com/r/HomeServer/comments/1rx7udl/what_do_i_need_to_start_a_home_server_can_i_go_in/",
|
||||
"page_id": null,
|
||||
"page_path": null,
|
||||
"paperless_id": null,
|
||||
"rrf_score": 0.01639344262295082,
|
||||
"final_rank": 2,
|
||||
"sources": [
|
||||
"web"
|
||||
],
|
||||
"related_dossiers": [],
|
||||
"metadata": {
|
||||
"entity_matches": null,
|
||||
"matched_entities": null,
|
||||
"engine": "startpage"
|
||||
}
|
||||
},
|
||||
{
|
||||
"source_type": "wiki",
|
||||
"title": "PostgreSQL Shared - Database Server",
|
||||
"content": "",
|
||||
"url": null,
|
||||
"page_id": 148,
|
||||
"page_path": "users/jpmschweitzer/projects/tower-of-joy/infrastructure/postgres",
|
||||
"paperless_id": null,
|
||||
"rrf_score": 0.016129032258064516,
|
||||
"final_rank": 3,
|
||||
"sources": [
|
||||
"graph"
|
||||
],
|
||||
"related_dossiers": [
|
||||
{
|
||||
"page_id": 149,
|
||||
"title": "Redis Shared - Cache and Session Store",
|
||||
"path": "users/jpmschweitzer/projects/tower-of-joy/infrastructure/redis",
|
||||
"tag": "infrastructure",
|
||||
"shared_entities": 5
|
||||
},
|
||||
{
|
||||
"page_id": 149,
|
||||
"title": "Redis Shared - Cache and Session Store",
|
||||
"path": "users/jpmschweitzer/projects/tower-of-joy/infrastructure/redis",
|
||||
"tag": "dossier:tatlock",
|
||||
"shared_entities": 5
|
||||
},
|
||||
{
|
||||
"page_id": 149,
|
||||
"title": "Redis Shared - Cache and Session Store",
|
||||
"path": "users/jpmschweitzer/projects/tower-of-joy/infrastructure/redis",
|
||||
"tag": "cache",
|
||||
"shared_entities": 5
|
||||
},
|
||||
{
|
||||
"page_id": 105,
|
||||
"title": "Google Cloud Platform",
|
||||
"path": "users/jpmschweitzer/technology/cloud-platforms/gcp",
|
||||
"tag": "technology",
|
||||
"shared_entities": 4
|
||||
},
|
||||
{
|
||||
"page_id": 105,
|
||||
"title": "Google Cloud Platform",
|
||||
"path": "users/jpmschweitzer/technology/cloud-platforms/gcp",
|
||||
"tag": "cloud-platforms",
|
||||
"shared_entities": 4
|
||||
}
|
||||
],
|
||||
"metadata": {
|
||||
"entity_matches": 1,
|
||||
"matched_entities": [
|
||||
"Database Server"
|
||||
],
|
||||
"engine": null
|
||||
}
|
||||
},
|
||||
{
|
||||
"source_type": "web",
|
||||
"title": "25+ Must-Have Home Server Services for 2025 (Ultimate Guide)",
|
||||
"content": "I\u2019ve been running a home server setup for years now, and it\u2019s been an incredible journey of discovery, learning, and practical benefits.\nIf you\u2019re considering setting up a home server or looking to expand your existing home lab, you\u2019re in the right place.\nIn this comprehensive guide, I\u2019ll walk you through the essential services that can transform your home server from a simple file storage system into a powerful, versatile hub that enhances your digital life.\nFrom media streaming to home automation, security, productivity, and more \u2013 we\u2019ll cover it all.\nWhether you\u2019re a seasoned self-hosting veteran or just taking your first steps into home server territory, this guide will help you discover new possibilities and build a setup that perfectly suits your needs.\nFoundation Services: The Building Blocks\nBefore diving into specific applications, let\u2019s cover the fundamental services that form the backbone of any robust home server setup.\nThese core components provide the infrastructure for everything else to run smoothly.\nHypervisors & Virtualization Platforms\nHypervisors allow you to run multiple virtual machines on a single physical server, making them crucial for efficient resource utilization.\nProxmox VE: The Homelab Virtualization King\nProxmox is my top recommendation for home server virtualization.\nThis open-source solution combines KVM virtualization with LXC containers, a powerful web interface, and built-in features like clustering, backups, and storage management.\nProxmox gives you the ability to run both full virtual machines and lightweight containers on the same hardware.\nIt\u2019s been extremely reliable in my setup, and its active community provides excellent support.\nI\u2019ve been using Proxmox for about three years, after switching from ESXi.\nThe transition was straightforward, and I\u2019ve found it much more suitable for home lab use.\nYou can create clusters with multiple nodes, run HA setups, and even use distributed storage with Ceph.\nTrueNAS SCALE: Storage with Ad...",
|
||||
"url": "https://hostbor.com/25-must-have-home-server-services/",
|
||||
"page_id": null,
|
||||
"page_path": null,
|
||||
"paperless_id": null,
|
||||
"rrf_score": 0.016129032258064516,
|
||||
"final_rank": 4,
|
||||
"sources": [
|
||||
"web"
|
||||
],
|
||||
"related_dossiers": [],
|
||||
"metadata": {
|
||||
"entity_matches": null,
|
||||
"matched_entities": null,
|
||||
"engine": "duckduckgo"
|
||||
}
|
||||
},
|
||||
{
|
||||
"source_type": "wiki",
|
||||
"title": "Bazzite",
|
||||
"content": "",
|
||||
"url": null,
|
||||
"page_id": 108,
|
||||
"page_path": "users/jpmschweitzer/technology/linux_distributions/bazzite",
|
||||
"paperless_id": null,
|
||||
"rrf_score": 0.015873015873015872,
|
||||
"final_rank": 5,
|
||||
"sources": [
|
||||
"graph"
|
||||
],
|
||||
"related_dossiers": [
|
||||
{
|
||||
"page_id": 110,
|
||||
"title": "Zorin OS",
|
||||
"path": "users/jpmschweitzer/technology/linux_distributions/zorin_os",
|
||||
"tag": "technology",
|
||||
"shared_entities": 22
|
||||
},
|
||||
{
|
||||
"page_id": 110,
|
||||
"title": "Zorin OS",
|
||||
"path": "users/jpmschweitzer/technology/linux_distributions/zorin_os",
|
||||
"tag": "linux_distributions",
|
||||
"shared_entities": 22
|
||||
},
|
||||
{
|
||||
"page_id": 110,
|
||||
"title": "Zorin OS",
|
||||
"path": "users/jpmschweitzer/technology/linux_distributions/zorin_os",
|
||||
"tag": "zorin_os",
|
||||
"shared_entities": 22
|
||||
},
|
||||
{
|
||||
"page_id": 109,
|
||||
"title": "Linux",
|
||||
"path": "users/jpmschweitzer/technology/linux",
|
||||
"tag": "technology",
|
||||
"shared_entities": 21
|
||||
},
|
||||
{
|
||||
"page_id": 109,
|
||||
"title": "Linux",
|
||||
"path": "users/jpmschweitzer/technology/linux",
|
||||
"tag": "linux",
|
||||
"shared_entities": 21
|
||||
}
|
||||
],
|
||||
"metadata": {
|
||||
"entity_matches": 1,
|
||||
"matched_entities": [
|
||||
"Display Server"
|
||||
],
|
||||
"engine": null
|
||||
}
|
||||
}
|
||||
],
|
||||
"context": "1. [WIKI] Tower of Joy - AI Butler System\n (no content)...\n Related research: ai, dossier:tatlock, applications\n\n2. [WEB] What do I need to start a home server ? Can I go in almost blind\n You don't need industrial grade hardware to be a server. You may get better reliability and management options from that, but they can all run\u00a0......\n\n3. [WIKI] PostgreSQL Shared - Database Server\n (no content)...\n Related research: infrastructure, dossier:tatlock, cache\n\n4. [WEB] 25+ Must-Have Home Server Services for 2025 (Ultimate Guide)\n I\u2019ve been running a home server setup for years now, and it\u2019s been an incredible journey of discovery, learning, and practical benefits.\nIf you\u2019re considering setting up a home server or looking to expand your existing home lab, you\u2019re in the right place.\nIn this comprehensive guide, I\u2019ll walk you t...\n\n5. [WIKI] Bazzite\n (no content)...\n Related research: technology, linux_distributions, zorin_os",
|
||||
"source_counts": {
|
||||
"graph": 3,
|
||||
"web": 2
|
||||
},
|
||||
"total_results": 5,
|
||||
"timing": {
|
||||
"query_enhancement_ms": 30.002593994140625,
|
||||
"vector_ms": 105.46708106994629,
|
||||
"graph_ms": 21.07977867126465,
|
||||
"web_ms": 1577.7764320373535,
|
||||
"volatile_ms": 0.0,
|
||||
"document_ms": 1.8155574798583984,
|
||||
"fusion_ms": 0.1761913299560547,
|
||||
"enrichment_ms": 14.33563232421875,
|
||||
"reranking_ms": 0.0002384185791015625,
|
||||
"persistence_ms": 33.80393981933594,
|
||||
"total_ms": 1624.767780303955
|
||||
},
|
||||
"config_used": {
|
||||
"vector_limit": 3,
|
||||
"graph_limit": 3,
|
||||
"web_limit": 2,
|
||||
"volatile_limit": 1,
|
||||
"document_limit": 2,
|
||||
"enable_vector": true,
|
||||
"enable_graph": true,
|
||||
"enable_web": true,
|
||||
"enable_volatile": false,
|
||||
"enable_documents": true,
|
||||
"enable_reranking": false,
|
||||
"enable_enrichment": true,
|
||||
"final_result_count": 6,
|
||||
"rrf_k": 60,
|
||||
"volatile_threshold": 0.8,
|
||||
"document_threshold": 0.6
|
||||
},
|
||||
"search_id": "01062bc7-ca65-4d9a-a210-e1a8f44b93c1"
|
||||
}
|
||||
@@ -0,0 +1,39 @@
|
||||
"""
|
||||
Tests for structured failure behavior of The Librarian entry point.
|
||||
|
||||
run_librarian must raise AgentError on failure instead of returning
|
||||
error text as if it were research output, and the raised error must
|
||||
not leak exception detail (internal URLs etc.).
|
||||
"""
|
||||
|
||||
from unittest.mock import AsyncMock, MagicMock, patch
|
||||
|
||||
import pytest
|
||||
|
||||
from src.agents.librarian.agent import run_librarian
|
||||
from src.agents.protocol import AgentError
|
||||
|
||||
|
||||
@pytest.mark.unit
|
||||
class TestRunLibrarianFailures:
|
||||
"""run_librarian raises structured errors instead of returning text."""
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_run_librarian_raises_agent_error(self):
|
||||
"""Failures raise AgentError rather than returning error prose."""
|
||||
mock_agent = MagicMock()
|
||||
mock_agent.run = AsyncMock(
|
||||
side_effect=RuntimeError("Connection refused to http://internal:8089")
|
||||
)
|
||||
|
||||
with patch(
|
||||
"src.agents.librarian.agent.get_librarian_agent",
|
||||
return_value=mock_agent,
|
||||
):
|
||||
with pytest.raises(AgentError) as exc_info:
|
||||
await run_librarian(task="Find Docker docs")
|
||||
|
||||
assert exc_info.value.agent_name == "librarian"
|
||||
# Exception detail stays in logs only
|
||||
assert "internal" not in str(exc_info.value)
|
||||
assert "Connection refused" not in str(exc_info.value)
|
||||
@@ -2,22 +2,23 @@
|
||||
Tests for the Library-Desk HTTP client.
|
||||
"""
|
||||
|
||||
import pytest
|
||||
from unittest.mock import AsyncMock, MagicMock, patch
|
||||
|
||||
import httpx
|
||||
import pytest
|
||||
|
||||
from src.agents.librarian.client import (
|
||||
LibraryDeskClient,
|
||||
Dossier,
|
||||
EntityLinking,
|
||||
GraphNode,
|
||||
HybridRAGResponse,
|
||||
HybridSearchResult,
|
||||
LibraryDeskClient,
|
||||
ResearchSummary,
|
||||
SmartCreateResponse,
|
||||
VectorSearchResult,
|
||||
WikiPage,
|
||||
WikiSearchResult,
|
||||
VectorSearchResult,
|
||||
GraphNode,
|
||||
Dossier,
|
||||
SmartCreateResponse,
|
||||
ResearchSummary,
|
||||
EntityLinking,
|
||||
)
|
||||
|
||||
|
||||
@@ -549,6 +550,181 @@ class TestSmartCreateWikiPage:
|
||||
assert result.research_summary.web_results == 0
|
||||
|
||||
|
||||
# All tenant-scoped client methods with minimal call kwargs. Used to sweep
|
||||
# the explicit-user contract: every library-desk request must carry a
|
||||
# non-empty user (the service is removing its server-side default).
|
||||
TENANT_SCOPED_METHODS = [
|
||||
("hybrid_search", {"query": "q"}),
|
||||
("search_wiki", {"query": "q"}),
|
||||
("get_wiki_page", {"page_id": 1}),
|
||||
("list_wiki_pages", {}),
|
||||
("create_wiki_page", {"title": "t", "path": "/p", "content": "c"}),
|
||||
("update_wiki_page", {"page_id": 1, "content": "c"}),
|
||||
("smart_create_wiki_page", {"topic": "t", "tags": ["x"]}),
|
||||
("list_dossiers", {}),
|
||||
("semantic_search", {"query": "q"}),
|
||||
("query_graph", {"cypher_query": "MATCH (n) RETURN n"}),
|
||||
("list_graph_nodes", {}),
|
||||
("get_graph_node", {"node_id": "n1"}),
|
||||
("search_web", {"query": "q"}),
|
||||
("extract_content", {"url": "http://example.com"}),
|
||||
("extract_content_batch", {"urls": ["http://example.com"]}),
|
||||
]
|
||||
|
||||
# One permissive response body that satisfies every method's parser
|
||||
# (extra keys are ignored by the pydantic models).
|
||||
UNIVERSAL_RESPONSE = {
|
||||
"id": 1,
|
||||
"path": "/p",
|
||||
"title": "T",
|
||||
"results": [],
|
||||
"pages": [],
|
||||
"dossiers": [],
|
||||
"records": [],
|
||||
"nodes": [],
|
||||
"keywords": [],
|
||||
"page": {"id": 1, "path": "/p", "title": "T"},
|
||||
"result": {"url": "http://example.com", "success": True},
|
||||
}
|
||||
|
||||
|
||||
@pytest.mark.unit
|
||||
class TestExplicitUserContract:
|
||||
"""Every library-desk request sends a non-empty user explicitly."""
|
||||
|
||||
def _wire_client(self):
|
||||
mock_response = MagicMock()
|
||||
mock_response.status_code = 200
|
||||
mock_response.json.return_value = UNIVERSAL_RESPONSE
|
||||
mock_response.raise_for_status = MagicMock()
|
||||
|
||||
mock_httpx = AsyncMock(spec=httpx.AsyncClient)
|
||||
mock_httpx.get.return_value = mock_response
|
||||
mock_httpx.post.return_value = mock_response
|
||||
mock_httpx.put.return_value = mock_response
|
||||
|
||||
client = LibraryDeskClient(base_url="http://test:8089", api_key="k")
|
||||
client._client = mock_httpx
|
||||
return client, mock_httpx
|
||||
|
||||
def _sent_user(self, mock_httpx) -> str:
|
||||
"""Extract the user sent on the single outgoing request."""
|
||||
calls = (
|
||||
mock_httpx.get.call_args_list
|
||||
+ mock_httpx.post.call_args_list
|
||||
+ mock_httpx.put.call_args_list
|
||||
)
|
||||
assert len(calls) == 1, "expected exactly one outgoing request"
|
||||
kwargs = calls[0].kwargs
|
||||
params = kwargs.get("params") or {}
|
||||
payload = kwargs.get("json") or {}
|
||||
return params.get("user") or payload.get("user") or ""
|
||||
|
||||
@pytest.mark.asyncio
|
||||
@pytest.mark.parametrize("method_name,kwargs", TENANT_SCOPED_METHODS)
|
||||
async def test_user_from_context_is_sent_on_the_wire(
|
||||
self, method_name, kwargs
|
||||
):
|
||||
"""With no explicit user, the context user is resolved and sent."""
|
||||
client, mock_httpx = self._wire_client()
|
||||
|
||||
with patch(
|
||||
"src.agents.librarian.client.get_user", return_value="llm_tester"
|
||||
):
|
||||
await getattr(client, method_name)(**kwargs)
|
||||
|
||||
assert self._sent_user(mock_httpx) == "llm_tester"
|
||||
|
||||
@pytest.mark.asyncio
|
||||
@pytest.mark.parametrize("method_name,kwargs", TENANT_SCOPED_METHODS)
|
||||
async def test_explicit_user_is_sent_on_the_wire(self, method_name, kwargs):
|
||||
"""An explicitly passed user is sent unchanged."""
|
||||
client, mock_httpx = self._wire_client()
|
||||
|
||||
await getattr(client, method_name)(user="test_phase_b", **kwargs)
|
||||
|
||||
assert self._sent_user(mock_httpx) == "test_phase_b"
|
||||
|
||||
@pytest.mark.asyncio
|
||||
@pytest.mark.parametrize("method_name,kwargs", TENANT_SCOPED_METHODS)
|
||||
async def test_empty_context_user_fails_before_any_request(
|
||||
self, method_name, kwargs
|
||||
):
|
||||
"""An empty resolved user raises before any bytes hit the wire."""
|
||||
client, mock_httpx = self._wire_client()
|
||||
|
||||
with patch("src.agents.librarian.client.get_user", return_value=""):
|
||||
with pytest.raises(ValueError, match="non-empty user"):
|
||||
await getattr(client, method_name)(**kwargs)
|
||||
|
||||
mock_httpx.get.assert_not_called()
|
||||
mock_httpx.post.assert_not_called()
|
||||
mock_httpx.put.assert_not_called()
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_explicit_whitespace_user_is_rejected(self):
|
||||
"""A whitespace-only explicit user is rejected."""
|
||||
client, mock_httpx = self._wire_client()
|
||||
|
||||
with pytest.raises(ValueError, match="non-empty user"):
|
||||
await client.hybrid_search("q", user=" ")
|
||||
|
||||
mock_httpx.post.assert_not_called()
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_explicit_padded_user_is_stripped_on_the_wire(self):
|
||||
"""Padded explicit users are stripped, not sent verbatim."""
|
||||
client, mock_httpx = self._wire_client()
|
||||
|
||||
await client.hybrid_search("q", user=" llm_tester ")
|
||||
|
||||
assert self._sent_user(mock_httpx) == "llm_tester"
|
||||
|
||||
@pytest.mark.asyncio
|
||||
@pytest.mark.parametrize(
|
||||
"explicit_user",
|
||||
["jpmschweitzer", "JPMSchweitzer", "jpmschweitzer.", " jpmschweitzer"],
|
||||
)
|
||||
@pytest.mark.parametrize("method_name,kwargs", TENANT_SCOPED_METHODS)
|
||||
async def test_explicit_production_tenant_is_guarded_in_dev(
|
||||
self, monkeypatch, method_name, kwargs, explicit_user
|
||||
):
|
||||
"""
|
||||
An explicit production-tenant argument (or a sanitization-collision
|
||||
variant) never reaches library-desk from a non-production
|
||||
environment - the client applies the same tenant guard as
|
||||
context resolution.
|
||||
"""
|
||||
from src.core import config as config_module
|
||||
from src.core.config import Environment
|
||||
|
||||
monkeypatch.setattr(
|
||||
config_module.config, "ENVIRONMENT", Environment.DEVELOPMENT
|
||||
)
|
||||
client, mock_httpx = self._wire_client()
|
||||
|
||||
await getattr(client, method_name)(user=explicit_user, **kwargs)
|
||||
|
||||
assert self._sent_user(mock_httpx) == "llm_tester"
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_explicit_production_tenant_passes_through_in_prod(
|
||||
self, monkeypatch
|
||||
):
|
||||
"""In production the production tenant is sent unchanged."""
|
||||
from src.core import config as config_module
|
||||
from src.core.config import Environment
|
||||
|
||||
monkeypatch.setattr(
|
||||
config_module.config, "ENVIRONMENT", Environment.PRODUCTION
|
||||
)
|
||||
client, mock_httpx = self._wire_client()
|
||||
|
||||
await client.hybrid_search("q", user="jpmschweitzer")
|
||||
|
||||
assert self._sent_user(mock_httpx) == "jpmschweitzer"
|
||||
|
||||
|
||||
@pytest.mark.unit
|
||||
class TestNewResponseModels:
|
||||
"""Tests for new response models."""
|
||||
|
||||
@@ -0,0 +1,232 @@
|
||||
"""
|
||||
Tests for bounded retries, timeout wiring, and client reuse in
|
||||
LibraryDeskClient, plus ModelRetry escalation from the read tools.
|
||||
"""
|
||||
|
||||
from unittest.mock import AsyncMock, MagicMock, patch
|
||||
|
||||
import httpx
|
||||
import pytest
|
||||
from pydantic_ai import ModelRetry
|
||||
|
||||
from src.agents.librarian.client import (
|
||||
LibraryDeskClient,
|
||||
library_client_session,
|
||||
)
|
||||
from src.agents.librarian.tools import (
|
||||
create_wiki_page,
|
||||
hybrid_search,
|
||||
search_wiki,
|
||||
)
|
||||
from src.core.config import config
|
||||
|
||||
|
||||
@pytest.fixture(autouse=True)
|
||||
def _no_backoff(monkeypatch):
|
||||
"""Skip the retry backoff sleep in tests."""
|
||||
monkeypatch.setattr("src.agents.librarian.client._RETRY_BACKOFF_SECONDS", 0)
|
||||
|
||||
|
||||
def _ok_response(payload: dict) -> MagicMock:
|
||||
response = MagicMock()
|
||||
response.status_code = 200
|
||||
response.json.return_value = payload
|
||||
response.raise_for_status = MagicMock()
|
||||
return response
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def client_with_mock():
|
||||
client = LibraryDeskClient(base_url="http://test:8089", api_key="test-key")
|
||||
client._client = AsyncMock(spec=httpx.AsyncClient)
|
||||
return client
|
||||
|
||||
|
||||
@pytest.mark.unit
|
||||
class TestBoundedRetries:
|
||||
"""2-attempt retry for GETs and read-only POST /query/*, /rag/search."""
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_get_retries_once_on_transport_error(self, client_with_mock):
|
||||
mock_httpx = client_with_mock._client
|
||||
mock_httpx.get.side_effect = [
|
||||
httpx.ConnectError("Connection refused"),
|
||||
_ok_response({"results": []}),
|
||||
]
|
||||
|
||||
results = await client_with_mock.search_wiki("docker", user="u")
|
||||
|
||||
assert results == []
|
||||
assert mock_httpx.get.call_count == 2
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_get_gives_up_after_two_attempts(self, client_with_mock):
|
||||
mock_httpx = client_with_mock._client
|
||||
mock_httpx.get.side_effect = httpx.ConnectError("Connection refused")
|
||||
|
||||
with pytest.raises(httpx.ConnectError):
|
||||
await client_with_mock.search_wiki("docker", user="u")
|
||||
|
||||
assert mock_httpx.get.call_count == 2
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_query_hybrid_retries_on_503(self, client_with_mock):
|
||||
mock_httpx = client_with_mock._client
|
||||
bad = MagicMock()
|
||||
bad.status_code = 503
|
||||
mock_httpx.post.side_effect = [
|
||||
bad,
|
||||
_ok_response({"results": [], "keywords": {}, "context": ""}),
|
||||
]
|
||||
|
||||
response = await client_with_mock.hybrid_search("docker", user="u")
|
||||
|
||||
assert response.results == []
|
||||
assert mock_httpx.post.call_count == 2
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_wiki_write_is_never_retried(self, client_with_mock):
|
||||
"""POST /wiki/pages must not retry - it could duplicate pages."""
|
||||
mock_httpx = client_with_mock._client
|
||||
mock_httpx.post.side_effect = httpx.ConnectError("Connection refused")
|
||||
|
||||
with pytest.raises(httpx.ConnectError):
|
||||
await client_with_mock.create_wiki_page(
|
||||
title="T", path="/t", content="c", user="u"
|
||||
)
|
||||
|
||||
assert mock_httpx.post.call_count == 1
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_smart_create_is_never_retried(self, client_with_mock):
|
||||
mock_httpx = client_with_mock._client
|
||||
mock_httpx.post.side_effect = httpx.ConnectError("Connection refused")
|
||||
|
||||
with pytest.raises(httpx.ConnectError):
|
||||
await client_with_mock.smart_create_wiki_page(
|
||||
topic="T", tags=["x"], user="u"
|
||||
)
|
||||
|
||||
assert mock_httpx.post.call_count == 1
|
||||
|
||||
|
||||
@pytest.mark.unit
|
||||
class TestTimeoutWiring:
|
||||
"""LIBRARY_DESK_TIMEOUT config replaces the hardcoded 60s/30s."""
|
||||
|
||||
def test_default_timeout_from_config(self):
|
||||
client = LibraryDeskClient()
|
||||
|
||||
assert client.timeout == config.LIBRARY_DESK_TIMEOUT
|
||||
|
||||
def test_explicit_timeout_wins(self):
|
||||
client = LibraryDeskClient(timeout=5)
|
||||
|
||||
assert client.timeout == 5
|
||||
|
||||
|
||||
@pytest.mark.unit
|
||||
class TestClientReuse:
|
||||
"""One shared HTTP connection per librarian run."""
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_clients_share_connection_inside_session(self):
|
||||
async with library_client_session():
|
||||
async with LibraryDeskClient() as c1:
|
||||
http1 = c1._client
|
||||
# shared connection survives client exit
|
||||
assert http1 is not None
|
||||
assert not http1.is_closed
|
||||
|
||||
async with LibraryDeskClient() as c2:
|
||||
assert c2._client is http1
|
||||
|
||||
# session close tears the shared connection down
|
||||
assert http1.is_closed
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_nested_sessions_are_noops(self):
|
||||
async with library_client_session():
|
||||
async with LibraryDeskClient() as c1:
|
||||
http1 = c1._client
|
||||
async with library_client_session():
|
||||
async with LibraryDeskClient() as c2:
|
||||
assert c2._client is http1
|
||||
# inner session exit must not close the shared connection
|
||||
assert not http1.is_closed
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_client_owns_connection_outside_session(self):
|
||||
async with LibraryDeskClient() as client:
|
||||
http_client = client._client
|
||||
|
||||
assert http_client.is_closed
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_custom_target_does_not_reuse_shared(self):
|
||||
async with library_client_session():
|
||||
async with LibraryDeskClient() as shared_client:
|
||||
shared_http = shared_client._client
|
||||
async with LibraryDeskClient(base_url="http://other:9999") as custom:
|
||||
assert custom._client is not shared_http
|
||||
|
||||
|
||||
@pytest.mark.unit
|
||||
class TestModelRetryEscalation:
|
||||
"""Read tools raise ModelRetry on transient errors so Agent(retries=2) engages."""
|
||||
|
||||
def _patched_client(self, mock_client):
|
||||
factory = MagicMock()
|
||||
factory.return_value.__aenter__ = AsyncMock(return_value=mock_client)
|
||||
factory.return_value.__aexit__ = AsyncMock(return_value=None)
|
||||
return patch("src.agents.librarian.tools.LibraryDeskClient", factory)
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_read_tool_raises_model_retry_on_transport_error(self):
|
||||
mock_client = AsyncMock()
|
||||
mock_client.hybrid_search.side_effect = httpx.ConnectError(
|
||||
"Connection refused"
|
||||
)
|
||||
|
||||
with self._patched_client(mock_client):
|
||||
with pytest.raises(ModelRetry):
|
||||
await hybrid_search("docker")
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_read_tool_raises_model_retry_on_5xx(self):
|
||||
request = httpx.Request("GET", "http://test:8089/wiki/search")
|
||||
response = httpx.Response(502, request=request)
|
||||
mock_client = AsyncMock()
|
||||
mock_client.search_wiki.side_effect = httpx.HTTPStatusError(
|
||||
"bad gateway", request=request, response=response
|
||||
)
|
||||
|
||||
with self._patched_client(mock_client):
|
||||
with pytest.raises(ModelRetry):
|
||||
await search_wiki("docker")
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_read_tool_returns_safe_message_on_non_transient(self):
|
||||
mock_client = AsyncMock()
|
||||
mock_client.hybrid_search.side_effect = ValueError("bad parse")
|
||||
|
||||
with self._patched_client(mock_client):
|
||||
result = await hybrid_search("docker")
|
||||
|
||||
assert "unable" in result
|
||||
assert "bad parse" not in result
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_write_tool_never_raises_model_retry(self):
|
||||
mock_client = AsyncMock()
|
||||
mock_client.create_wiki_page.side_effect = httpx.ConnectError(
|
||||
"Connection refused"
|
||||
)
|
||||
|
||||
with self._patched_client(mock_client):
|
||||
result = await create_wiki_page(
|
||||
title="T", path="/t", content="c", tags=["x"]
|
||||
)
|
||||
|
||||
assert "unable" in result
|
||||
assert "Connection refused" not in result
|
||||
@@ -0,0 +1,344 @@
|
||||
"""
|
||||
Contract tests for HybridRAG parsing against a recorded live response.
|
||||
|
||||
The fixture in fixtures/hybrid_query_recorded.json is a real (recorded)
|
||||
response from library-desk's POST /query/hybrid. These tests pin the
|
||||
field mapping (source_type/sources, rrf_score, context, per-item
|
||||
related_dossiers, keywords dict with nested synonyms) so a drift in
|
||||
either side shows up as a test failure instead of every result
|
||||
rendering as "unknown (score: 0.00)".
|
||||
"""
|
||||
|
||||
import json
|
||||
from pathlib import Path
|
||||
from unittest.mock import AsyncMock, MagicMock
|
||||
|
||||
import httpx
|
||||
import pytest
|
||||
|
||||
from src.agents.librarian.client import HybridRAGResponse, LibraryDeskClient
|
||||
from src.agents.librarian.tools import SOURCE_ICONS, _coverage_note, hybrid_search
|
||||
|
||||
FIXTURE_PATH = Path(__file__).parent / "fixtures" / "hybrid_query_recorded.json"
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def recorded_response() -> dict:
|
||||
"""Load the recorded /query/hybrid response."""
|
||||
return json.loads(FIXTURE_PATH.read_text())
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def client_with_recorded_response(recorded_response):
|
||||
"""LibraryDeskClient whose httpx client replays the recorded response."""
|
||||
mock_response = MagicMock()
|
||||
mock_response.json.return_value = recorded_response
|
||||
mock_response.raise_for_status = MagicMock()
|
||||
|
||||
mock_httpx = AsyncMock(spec=httpx.AsyncClient)
|
||||
mock_httpx.post.return_value = mock_response
|
||||
|
||||
client = LibraryDeskClient(base_url="http://test:8089", api_key="test-key")
|
||||
client._client = mock_httpx
|
||||
return client
|
||||
|
||||
|
||||
@pytest.mark.unit
|
||||
class TestHybridRAGContract:
|
||||
"""Contract tests for parsing the live /query/hybrid response shape."""
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_sources_are_not_unknown(self, client_with_recorded_response):
|
||||
"""Every result maps source_type - nothing falls back to 'unknown'."""
|
||||
response = await client_with_recorded_response.hybrid_search(
|
||||
"home server infrastructure", user="testuser"
|
||||
)
|
||||
|
||||
assert isinstance(response, HybridRAGResponse)
|
||||
assert response.results, "recorded fixture must contain results"
|
||||
for result in response.results:
|
||||
assert result.source != "unknown"
|
||||
assert result.source in {"wiki", "web", "volatile", "document"}
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_scores_are_non_zero(self, client_with_recorded_response):
|
||||
"""rrf_score maps to score - no silent 0.00 fallback."""
|
||||
response = await client_with_recorded_response.hybrid_search(
|
||||
"home server infrastructure", user="testuser"
|
||||
)
|
||||
|
||||
for result in response.results:
|
||||
assert result.score > 0.0
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_sources_list_and_icons(self, client_with_recorded_response):
|
||||
"""Per-item sources list is parsed and every value has an icon."""
|
||||
response = await client_with_recorded_response.hybrid_search(
|
||||
"home server infrastructure", user="testuser"
|
||||
)
|
||||
|
||||
for result in response.results:
|
||||
assert result.sources, f"result '{result.title}' has empty sources"
|
||||
for source in result.sources:
|
||||
assert source in SOURCE_ICONS, f"no icon for source '{source}'"
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_context_maps_to_formatted_context(
|
||||
self, client_with_recorded_response
|
||||
):
|
||||
"""Top-level 'context' field maps to formatted_context."""
|
||||
response = await client_with_recorded_response.hybrid_search(
|
||||
"home server infrastructure", user="testuser"
|
||||
)
|
||||
|
||||
assert response.formatted_context != ""
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_keywords_and_synonyms_from_dict(
|
||||
self, client_with_recorded_response
|
||||
):
|
||||
"""keywords is a dict: core_keywords + nested synonyms map."""
|
||||
response = await client_with_recorded_response.hybrid_search(
|
||||
"home server infrastructure", user="testuser"
|
||||
)
|
||||
|
||||
assert response.keywords, "core_keywords should be extracted"
|
||||
assert all(isinstance(k, str) for k in response.keywords)
|
||||
# synonyms map in the fixture is empty, but must parse to a list
|
||||
assert isinstance(response.synonyms, list)
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_per_item_related_dossiers(self, client_with_recorded_response):
|
||||
"""related_dossiers live per result and aggregate to unique titles."""
|
||||
response = await client_with_recorded_response.hybrid_search(
|
||||
"home server infrastructure", user="testuser"
|
||||
)
|
||||
|
||||
per_item = [d for r in response.results for d in r.related_dossiers]
|
||||
assert per_item, "recorded fixture contains per-item related_dossiers"
|
||||
for dossier in per_item:
|
||||
assert "title" in dossier
|
||||
assert "tag" in dossier
|
||||
|
||||
assert response.related_dossiers, "top-level titles are aggregated"
|
||||
assert len(response.related_dossiers) == len(set(response.related_dossiers))
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_payload_never_sends_zero_limits(
|
||||
self, client_with_recorded_response
|
||||
):
|
||||
"""The live service 422s on limits < 1; disabled legs use enable_* flags."""
|
||||
await client_with_recorded_response.hybrid_search(
|
||||
"home server infrastructure",
|
||||
user="testuser",
|
||||
web_limit=0,
|
||||
document_limit=0,
|
||||
volatile_limit=0,
|
||||
)
|
||||
|
||||
payload = client_with_recorded_response._client.post.call_args.kwargs["json"]
|
||||
config = payload["config"]
|
||||
for key in (
|
||||
"vector_limit",
|
||||
"graph_limit",
|
||||
"web_limit",
|
||||
"document_limit",
|
||||
"volatile_limit",
|
||||
):
|
||||
assert config[key] >= 1
|
||||
assert config["enable_web"] is False
|
||||
assert config["enable_documents"] is False
|
||||
assert config["enable_volatile"] is False
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_user_always_sent_as_query_param(
|
||||
self, client_with_recorded_response
|
||||
):
|
||||
"""The tenant is always sent explicitly - library-desk is removing
|
||||
its server-side default, so a missing user would 422."""
|
||||
await client_with_recorded_response.hybrid_search(
|
||||
"home server infrastructure", user="testuser"
|
||||
)
|
||||
|
||||
params = client_with_recorded_response._client.post.call_args.kwargs[
|
||||
"params"
|
||||
]
|
||||
assert params["user"] == "testuser"
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_source_counts_and_timing_parsed(
|
||||
self, client_with_recorded_response
|
||||
):
|
||||
"""source_counts and timing map into the response model."""
|
||||
response = await client_with_recorded_response.hybrid_search(
|
||||
"home server infrastructure", user="testuser"
|
||||
)
|
||||
|
||||
assert response.source_counts == {"graph": 3, "web": 2}
|
||||
assert response.timing.get("total_ms", 0) > 0
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_source_status_absent_is_tolerated(
|
||||
self, client_with_recorded_response
|
||||
):
|
||||
"""Recorded response predates source_status/degraded - defaults apply."""
|
||||
response = await client_with_recorded_response.hybrid_search(
|
||||
"home server infrastructure", user="testuser"
|
||||
)
|
||||
|
||||
assert response.source_status == {}
|
||||
assert response.degraded is False
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_source_status_parsed_when_present(self, recorded_response):
|
||||
"""Additive source_status/degraded fields parse when the service sends them."""
|
||||
enriched = dict(recorded_response)
|
||||
enriched["source_status"] = {
|
||||
"vector": "ok",
|
||||
"graph": "ok",
|
||||
"web": "failed",
|
||||
"volatile": "disabled",
|
||||
"documents": "ok",
|
||||
}
|
||||
enriched["degraded"] = True
|
||||
|
||||
mock_response = MagicMock()
|
||||
mock_response.json.return_value = enriched
|
||||
mock_response.raise_for_status = MagicMock()
|
||||
mock_httpx = AsyncMock(spec=httpx.AsyncClient)
|
||||
mock_httpx.post.return_value = mock_response
|
||||
|
||||
client = LibraryDeskClient(base_url="http://test:8089", api_key="test-key")
|
||||
client._client = mock_httpx
|
||||
|
||||
response = await client.hybrid_search("home server infrastructure", user="u")
|
||||
|
||||
assert response.degraded is True
|
||||
assert response.source_status["web"] == "failed"
|
||||
assert response.source_status["volatile"] == "disabled"
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_tool_renders_no_unknown_results(self, client_with_recorded_response, monkeypatch):
|
||||
"""The hybrid_search tool renders real sources and non-zero scores."""
|
||||
|
||||
class _Factory:
|
||||
def __call__(self):
|
||||
return self
|
||||
|
||||
async def __aenter__(self):
|
||||
return client_with_recorded_response
|
||||
|
||||
async def __aexit__(self, *args):
|
||||
return None
|
||||
|
||||
monkeypatch.setattr(
|
||||
"src.agents.librarian.tools.LibraryDeskClient", _Factory()
|
||||
)
|
||||
|
||||
output = await hybrid_search("home server infrastructure")
|
||||
|
||||
assert "unknown" not in output
|
||||
assert "score: 0.00" not in output
|
||||
assert "•" not in output, "every source value should map to an icon"
|
||||
|
||||
|
||||
@pytest.mark.unit
|
||||
class TestCoverageNote:
|
||||
"""Coverage note makes degraded searches visible to model and user."""
|
||||
|
||||
def _response(self, **kwargs) -> HybridRAGResponse:
|
||||
return HybridRAGResponse(**kwargs)
|
||||
|
||||
def test_no_note_when_all_legs_report(self):
|
||||
response = self._response(
|
||||
source_counts={
|
||||
"vector": 2,
|
||||
"graph": 1,
|
||||
"web": 2,
|
||||
"documents": 1,
|
||||
"volatile": 1,
|
||||
},
|
||||
)
|
||||
note = _coverage_note(
|
||||
response, include_web=True, include_documents=True, include_volatile=True
|
||||
)
|
||||
assert note == ""
|
||||
|
||||
def test_note_when_enabled_leg_missing_from_counts(self):
|
||||
response = self._response(source_counts={"graph": 3, "web": 2})
|
||||
note = _coverage_note(
|
||||
response, include_web=True, include_documents=True, include_volatile=True
|
||||
)
|
||||
assert "Coverage note" in note
|
||||
assert "documents" in note
|
||||
assert "volatile" in note
|
||||
# Always-on wiki legs are never inferred from count absence
|
||||
assert "vector" not in note
|
||||
assert "graph" not in note
|
||||
|
||||
def test_wiki_leg_absence_is_not_degradation(self):
|
||||
"""vector/graph missing from top-N counts is healthy ranking, not outage."""
|
||||
response = self._response(
|
||||
source_counts={"web": 2, "documents": 1, "volatile": 1}
|
||||
)
|
||||
note = _coverage_note(
|
||||
response, include_web=True, include_documents=True, include_volatile=True
|
||||
)
|
||||
assert note == ""
|
||||
|
||||
def test_disabled_legs_are_not_reported_missing(self):
|
||||
response = self._response(source_counts={"vector": 2, "graph": 1})
|
||||
note = _coverage_note(
|
||||
response,
|
||||
include_web=False,
|
||||
include_documents=False,
|
||||
include_volatile=False,
|
||||
)
|
||||
assert note == ""
|
||||
|
||||
def test_note_prefers_source_status_failures(self):
|
||||
response = self._response(
|
||||
source_counts={"vector": 2, "graph": 1},
|
||||
source_status={
|
||||
"vector": "ok",
|
||||
"graph": "ok",
|
||||
"web": "failed",
|
||||
"volatile": "disabled",
|
||||
"documents": "ok",
|
||||
},
|
||||
degraded=True,
|
||||
)
|
||||
note = _coverage_note(
|
||||
response, include_web=True, include_documents=True, include_volatile=True
|
||||
)
|
||||
assert "failed" in note
|
||||
assert "web" in note
|
||||
# disabled legs are not reported as failures
|
||||
assert "volatile" not in note
|
||||
|
||||
def test_no_note_when_status_all_ok(self):
|
||||
response = self._response(
|
||||
source_counts={"graph": 1},
|
||||
source_status={
|
||||
"vector": "ok",
|
||||
"graph": "ok",
|
||||
"web": "ok",
|
||||
"volatile": "ok",
|
||||
"documents": "ok",
|
||||
},
|
||||
degraded=False,
|
||||
)
|
||||
note = _coverage_note(
|
||||
response, include_web=True, include_documents=True, include_volatile=True
|
||||
)
|
||||
assert note == ""
|
||||
|
||||
def test_degraded_without_named_failures(self):
|
||||
response = self._response(
|
||||
source_status={"vector": "ok", "graph": "ok"},
|
||||
degraded=True,
|
||||
)
|
||||
note = _coverage_note(
|
||||
response, include_web=True, include_documents=True, include_volatile=True
|
||||
)
|
||||
assert "partial" in note
|
||||
@@ -0,0 +1,49 @@
|
||||
"""
|
||||
Snapshot tests for the JSON schemas emitted for librarian tools.
|
||||
|
||||
Ollama's OpenAI-compatible API mishandles anyOf[X, null] parameter
|
||||
schemas, so tool parameters must use empty-string/empty-list sentinels
|
||||
translated to None inside the tool (same pattern as the biographer
|
||||
tools, commit 9d7ce39). This test fails if a X | None parameter ever
|
||||
creeps back in.
|
||||
"""
|
||||
|
||||
import pytest
|
||||
from pydantic_ai.tools import Tool
|
||||
|
||||
from src.agents.librarian.tools import LIBRARIAN_TOOLS
|
||||
|
||||
|
||||
def _nullable_anyof_paths(schema: object, path: str = "") -> list[str]:
|
||||
"""Recursively collect JSON-schema paths that are anyOf[..., null]."""
|
||||
offenders: list[str] = []
|
||||
if isinstance(schema, dict):
|
||||
any_of = schema.get("anyOf")
|
||||
if isinstance(any_of, list) and any(
|
||||
isinstance(sub, dict) and sub.get("type") == "null" for sub in any_of
|
||||
):
|
||||
offenders.append(path or "<root>")
|
||||
for key, value in schema.items():
|
||||
offenders.extend(_nullable_anyof_paths(value, f"{path}/{key}"))
|
||||
elif isinstance(schema, list):
|
||||
for i, item in enumerate(schema):
|
||||
offenders.extend(_nullable_anyof_paths(item, f"{path}[{i}]"))
|
||||
return offenders
|
||||
|
||||
|
||||
@pytest.mark.unit
|
||||
class TestLibrarianToolSchemas:
|
||||
"""All registered librarian tools emit Ollama-safe parameter schemas."""
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
"tool_func", LIBRARIAN_TOOLS, ids=lambda f: f.__name__
|
||||
)
|
||||
def test_no_nullable_anyof_in_schema(self, tool_func):
|
||||
schema = Tool(tool_func).function_schema.json_schema
|
||||
|
||||
offenders = _nullable_anyof_paths(schema)
|
||||
|
||||
assert offenders == [], (
|
||||
f"{tool_func.__name__} emits anyOf[..., null] at {offenders}; "
|
||||
"use empty-string/empty-list sentinels instead of X | None"
|
||||
)
|
||||
@@ -5,21 +5,23 @@ Tests the tool functions that wrap the Library-Desk API,
|
||||
including the new web search and content extraction tools.
|
||||
"""
|
||||
|
||||
import pytest
|
||||
from unittest.mock import AsyncMock, MagicMock, patch
|
||||
from unittest.mock import AsyncMock, patch
|
||||
|
||||
import pytest
|
||||
|
||||
from src.agents.librarian.client import (
|
||||
BatchExtractionResponse,
|
||||
ContentExtractionResult,
|
||||
WebSearchResponse,
|
||||
WebSearchResult,
|
||||
WikiPage,
|
||||
)
|
||||
from src.agents.librarian.tools import (
|
||||
search_web,
|
||||
CLEAR_TAGS_SENTINEL,
|
||||
read_url,
|
||||
read_urls_batch,
|
||||
hybrid_search,
|
||||
search_wiki,
|
||||
)
|
||||
from src.agents.librarian.client import (
|
||||
WebSearchResult,
|
||||
WebSearchResponse,
|
||||
ContentExtractionResult,
|
||||
BatchExtractionResponse,
|
||||
search_web,
|
||||
update_wiki_page,
|
||||
)
|
||||
|
||||
|
||||
@@ -104,8 +106,10 @@ class TestSearchWeb:
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_search_web_error_handling(self, mock_client):
|
||||
"""Test web search error handling."""
|
||||
mock_client.search_web.side_effect = Exception("Connection failed")
|
||||
"""Test web search errors return a user-safe message without internals."""
|
||||
mock_client.search_web.side_effect = Exception(
|
||||
"Connection failed to http://internal-host:8089"
|
||||
)
|
||||
|
||||
with patch(
|
||||
"src.agents.librarian.tools.LibraryDeskClient"
|
||||
@@ -115,8 +119,10 @@ class TestSearchWeb:
|
||||
|
||||
result = await search_web("test query")
|
||||
|
||||
assert "Error" in result
|
||||
assert "Connection failed" in result
|
||||
assert "unable to search the web" in result
|
||||
# Exception detail (internal URLs etc.) must not leak
|
||||
assert "Connection failed" not in result
|
||||
assert "internal-host" not in result
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_search_web_with_news_type(self, mock_client):
|
||||
@@ -227,7 +233,7 @@ class TestReadUrl:
|
||||
mock_client_class.return_value.__aenter__.return_value = mock_client
|
||||
mock_client_class.return_value.__aexit__.return_value = None
|
||||
|
||||
result = await read_url("https://example.com/long", max_length=2000)
|
||||
await read_url("https://example.com/long", max_length=2000)
|
||||
|
||||
mock_client.extract_content.assert_called_with(
|
||||
url="https://example.com/long",
|
||||
@@ -424,3 +430,59 @@ class TestWebSearchModels:
|
||||
assert response.total_urls == 2
|
||||
assert response.successful == 1
|
||||
assert response.failed == 1
|
||||
|
||||
|
||||
# ============================================================================
|
||||
# Wiki Update Tests (tag sentinel behavior)
|
||||
# ============================================================================
|
||||
|
||||
@pytest.mark.unit
|
||||
class TestUpdateWikiPageTagSentinels:
|
||||
"""Empty list leaves tags unchanged; the clear sentinel empties them."""
|
||||
|
||||
def _page(self, tags: list[str]) -> WikiPage:
|
||||
return WikiPage(id=42, path="test/page", title="Test Page", tags=tags)
|
||||
|
||||
def _patched_client(self, mock_client):
|
||||
patcher = patch("src.agents.librarian.tools.LibraryDeskClient")
|
||||
mock_client_class = patcher.start()
|
||||
mock_client_class.return_value.__aenter__.return_value = mock_client
|
||||
mock_client_class.return_value.__aexit__.return_value = None
|
||||
return patcher
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_empty_tags_means_leave_unchanged(self, mock_client):
|
||||
mock_client.update_wiki_page.return_value = self._page(["existing"])
|
||||
patcher = self._patched_client(mock_client)
|
||||
try:
|
||||
await update_wiki_page(42, content="new content")
|
||||
finally:
|
||||
patcher.stop()
|
||||
|
||||
_, kwargs = mock_client.update_wiki_page.call_args
|
||||
assert kwargs["tags"] is None
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_clear_sentinel_sends_empty_tag_list(self, mock_client):
|
||||
mock_client.update_wiki_page.return_value = self._page([])
|
||||
patcher = self._patched_client(mock_client)
|
||||
try:
|
||||
result = await update_wiki_page(42, tags=[CLEAR_TAGS_SENTINEL])
|
||||
finally:
|
||||
patcher.stop()
|
||||
|
||||
_, kwargs = mock_client.update_wiki_page.call_args
|
||||
assert kwargs["tags"] == []
|
||||
assert "tags (cleared)" in result
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_real_tags_are_passed_through(self, mock_client):
|
||||
mock_client.update_wiki_page.return_value = self._page(["a", "b"])
|
||||
patcher = self._patched_client(mock_client)
|
||||
try:
|
||||
await update_wiki_page(42, tags=["a", "b"])
|
||||
finally:
|
||||
patcher.stop()
|
||||
|
||||
_, kwargs = mock_client.update_wiki_page.call_args
|
||||
assert kwargs["tags"] == ["a", "b"]
|
||||
|
||||
@@ -8,14 +8,19 @@ from unittest.mock import AsyncMock, MagicMock, patch
|
||||
import pytest
|
||||
|
||||
from src.agents.steward.schemas import ConversationContext, StewardRecommendation
|
||||
from src.agents.steward.service import analyze_request, format_steward_note, _build_enriched_query
|
||||
from src.core.startup import initialize_application
|
||||
from src.agents.steward.service import (
|
||||
_build_enriched_query,
|
||||
_extract_capabilities,
|
||||
analyze_request,
|
||||
format_steward_note,
|
||||
)
|
||||
from src.core.startup import register_household_members
|
||||
|
||||
|
||||
@pytest.fixture(scope="module", autouse=True)
|
||||
def setup_household_registry():
|
||||
"""Initialize household registry before running tests."""
|
||||
initialize_application()
|
||||
register_household_members()
|
||||
|
||||
|
||||
class TestAnalyzeRequest:
|
||||
@@ -29,9 +34,6 @@ class TestAnalyzeRequest:
|
||||
mock_agent.analyze = AsyncMock(return_value="Simple greeting requires no tools. This is a simple request.")
|
||||
|
||||
with patch("src.agents.steward.service.get_steward_agent", return_value=mock_agent):
|
||||
with patch("src.agents.steward.service.get_benchmark_store") as mock_store:
|
||||
mock_store.return_value.record = AsyncMock()
|
||||
|
||||
result = await analyze_request(
|
||||
"Hello!",
|
||||
conversation_history=[],
|
||||
@@ -50,9 +52,6 @@ class TestAnalyzeRequest:
|
||||
)
|
||||
|
||||
with patch("src.agents.steward.service.get_steward_agent", return_value=mock_agent):
|
||||
with patch("src.agents.steward.service.get_benchmark_store") as mock_store:
|
||||
mock_store.return_value.record = AsyncMock()
|
||||
|
||||
result = await analyze_request(
|
||||
"What's sqrt(144)?",
|
||||
conversation_history=[],
|
||||
@@ -75,9 +74,6 @@ class TestAnalyzeRequest:
|
||||
]
|
||||
|
||||
with patch("src.agents.steward.service.get_steward_agent", return_value=mock_agent):
|
||||
with patch("src.agents.steward.service.get_benchmark_store") as mock_store:
|
||||
mock_store.return_value.record = AsyncMock()
|
||||
|
||||
result = await analyze_request(
|
||||
"And what's that times 5?",
|
||||
conversation_history=conversation_history,
|
||||
@@ -100,9 +96,6 @@ class TestAnalyzeRequest:
|
||||
)
|
||||
|
||||
with patch("src.agents.steward.service.get_steward_agent", return_value=mock_agent):
|
||||
with patch("src.agents.steward.service.get_benchmark_store") as mock_store:
|
||||
mock_store.return_value.record = AsyncMock()
|
||||
|
||||
result = await analyze_request(
|
||||
"Generate an image of a sunset",
|
||||
conversation_history=[],
|
||||
@@ -120,9 +113,6 @@ class TestAnalyzeRequest:
|
||||
)
|
||||
|
||||
with patch("src.agents.steward.service.get_steward_agent", return_value=mock_agent):
|
||||
with patch("src.agents.steward.service.get_benchmark_store") as mock_store:
|
||||
mock_store.return_value.record = AsyncMock()
|
||||
|
||||
result = await analyze_request(
|
||||
"Test request",
|
||||
conversation_history=[],
|
||||
@@ -298,3 +288,89 @@ class TestBuildEnrichedQuery:
|
||||
result = _build_enriched_query(query, memory_context)
|
||||
|
||||
assert result == query
|
||||
|
||||
|
||||
class TestExtractCapabilities:
|
||||
"""Capability extraction reads the declared DELEGATE line, not free prose.
|
||||
|
||||
The prompt tells the Steward to state its choice on a DELEGATE line and to
|
||||
explain itself on REASON/COMPLEXITY/CONTEXT lines. An earlier version
|
||||
substring-matched capability domains across the entire response, so ordinary
|
||||
English in the explanation routed requests: "description" contains the
|
||||
housekeeper domain "script", "acknowledge" contains "know". These tests pin
|
||||
that the explanation can no longer influence routing.
|
||||
"""
|
||||
|
||||
# (prose, why it used to misroute)
|
||||
SUBSTRING_TRAPS = [
|
||||
("The user wants a description of the algorithm.", "script -> housekeeper"),
|
||||
("I should discover what the answer is.", "cover -> housekeeper"),
|
||||
("That sounds fantastic, let me compute it.", "fan -> housekeeper"),
|
||||
("I acknowledge the request to add two numbers.", "knowledge/know -> librarian, biographer"),
|
||||
("The user asks about the economy myth.", "my -> biographer"),
|
||||
("Convert 98.6 Fahrenheit to Celsius.", "temperature is a housekeeper domain"),
|
||||
]
|
||||
|
||||
@pytest.mark.parametrize("prose,reason", SUBSTRING_TRAPS)
|
||||
def test_reason_prose_cannot_add_capabilities(self, prose, reason):
|
||||
"""Explanatory prose must not summon agents the Steward did not request."""
|
||||
text = f"DELEGATE: tatlock_core to calculate\nREASON: {prose}\nCOMPLEXITY: simple"
|
||||
|
||||
assert _extract_capabilities(text) == ["tatlock_core"], f"regression: {reason}"
|
||||
|
||||
def test_delegate_line_task_text_does_not_leak(self):
|
||||
"""A domain word inside the task description must not add a capability.
|
||||
|
||||
"home" is a housekeeper domain, but this is plainly a memory recall.
|
||||
"""
|
||||
text = "DELEGATE: biographer to recall the user's home address\nREASON: personal data"
|
||||
|
||||
assert _extract_capabilities(text) == ["biographer"]
|
||||
|
||||
def test_multiple_delegate_lines(self):
|
||||
"""Each DELEGATE line contributes its capability, in order, deduplicated."""
|
||||
text = (
|
||||
"DELEGATE: biographer to recall the user's location\n"
|
||||
"DELEGATE: librarian to search_web for the forecast\n"
|
||||
"DELEGATE: biographer to recall preferences\n"
|
||||
)
|
||||
|
||||
assert _extract_capabilities(text) == ["biographer", "librarian"]
|
||||
|
||||
def test_capability_named_later_on_the_line(self):
|
||||
"""A loosely worded DELEGATE line still resolves by name."""
|
||||
text = "DELEGATE: ask the librarian to search the web"
|
||||
|
||||
assert _extract_capabilities(text) == ["librarian"]
|
||||
|
||||
def test_domain_fallback_within_delegate_line(self):
|
||||
"""With no capability named, domains on the DELEGATE line still resolve."""
|
||||
text = "DELEGATE: turn on the lights in the kitchen"
|
||||
|
||||
assert _extract_capabilities(text) == ["housekeeper"]
|
||||
|
||||
def test_conversational_response_selects_nothing(self):
|
||||
"""No DELEGATE line means no capability, which is the prompt's chat path."""
|
||||
text = "This is a simple greeting. No capabilities are needed. COMPLEXITY: simple"
|
||||
|
||||
assert _extract_capabilities(text) == []
|
||||
|
||||
def test_malformed_response_still_routes_by_name(self):
|
||||
"""If the format is ignored, a named capability is still honoured."""
|
||||
text = "I think the librarian should handle this research request."
|
||||
|
||||
assert _extract_capabilities(text) == ["librarian"]
|
||||
|
||||
def test_malformed_response_does_not_route_on_domains(self):
|
||||
"""...but bare prose must not route on domain words alone."""
|
||||
text = "The user wants a description of home automation, and I acknowledge it."
|
||||
|
||||
assert _extract_capabilities(text) == []
|
||||
|
||||
def test_case_insensitive_delegate_marker(self):
|
||||
text = "delegate: Librarian to search_web"
|
||||
|
||||
assert _extract_capabilities(text) == ["librarian"]
|
||||
|
||||
def test_empty_input(self):
|
||||
assert _extract_capabilities("") == []
|
||||
|
||||
@@ -1,339 +0,0 @@
|
||||
"""
|
||||
Tests for multi-agent coordination engine.
|
||||
"""
|
||||
|
||||
import pytest
|
||||
from unittest.mock import AsyncMock, MagicMock, patch
|
||||
|
||||
from src.agents.coordination import (
|
||||
CoordinationEngine,
|
||||
get_coordination_engine,
|
||||
delegate_to_librarian,
|
||||
)
|
||||
from src.agents.protocol import (
|
||||
AgentResponse,
|
||||
AgentUnavailableError,
|
||||
DelegationIntent,
|
||||
DelegationReason,
|
||||
)
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def coordination_engine():
|
||||
"""Create a fresh coordination engine for testing."""
|
||||
return CoordinationEngine()
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def mock_registry():
|
||||
"""Mock the household registry."""
|
||||
with patch("src.agents.coordination.get_household_registry") as mock:
|
||||
registry = MagicMock()
|
||||
mock.return_value = registry
|
||||
yield registry
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def librarian_intent():
|
||||
"""Create a standard librarian delegation intent."""
|
||||
return DelegationIntent(
|
||||
target_agent="librarian",
|
||||
task="Find information about Docker networking",
|
||||
reason=DelegationReason.DOMAIN_EXPERTISE,
|
||||
expected_outcome="Documentation and examples",
|
||||
)
|
||||
|
||||
|
||||
@pytest.mark.unit
|
||||
class TestCoordinationEngine:
|
||||
"""Tests for CoordinationEngine class."""
|
||||
|
||||
def test_initialization(self, coordination_engine):
|
||||
"""Test engine initializes correctly."""
|
||||
assert coordination_engine is not None
|
||||
assert coordination_engine.registry is not None
|
||||
|
||||
def test_get_available_agents_empty(self, mock_registry):
|
||||
"""Test getting available agents when none have agents."""
|
||||
mock_registry.list_members.return_value = ["tatlock_core"]
|
||||
mock_member = MagicMock()
|
||||
mock_member.agent = None # No agent
|
||||
mock_registry.get_member.return_value = mock_member
|
||||
|
||||
engine = CoordinationEngine()
|
||||
available = engine.get_available_agents()
|
||||
|
||||
assert available == []
|
||||
|
||||
def test_get_available_agents_with_librarian(self, mock_registry):
|
||||
"""Test getting available agents with librarian registered."""
|
||||
mock_registry.list_members.return_value = ["tatlock_core", "librarian"]
|
||||
|
||||
# tatlock_core has no agent
|
||||
core_member = MagicMock()
|
||||
core_member.agent = None
|
||||
|
||||
# librarian has an agent
|
||||
librarian_member = MagicMock()
|
||||
librarian_member.agent = MagicMock()
|
||||
|
||||
def get_member_side_effect(name):
|
||||
if name == "tatlock_core":
|
||||
return core_member
|
||||
elif name == "librarian":
|
||||
return librarian_member
|
||||
return None
|
||||
|
||||
mock_registry.get_member.side_effect = get_member_side_effect
|
||||
|
||||
engine = CoordinationEngine()
|
||||
available = engine.get_available_agents()
|
||||
|
||||
assert "librarian" in available
|
||||
assert "tatlock_core" not in available
|
||||
|
||||
def test_can_delegate_to_unknown_agent(self, mock_registry):
|
||||
"""Test checking delegation to unknown agent."""
|
||||
mock_registry.get_member.return_value = None
|
||||
|
||||
engine = CoordinationEngine()
|
||||
|
||||
assert engine.can_delegate_to("unknown_agent") is False
|
||||
|
||||
def test_can_delegate_to_librarian(self, mock_registry):
|
||||
"""Test checking delegation to librarian."""
|
||||
mock_member = MagicMock()
|
||||
mock_member.agent = MagicMock() # Has an agent
|
||||
mock_registry.get_member.return_value = mock_member
|
||||
|
||||
engine = CoordinationEngine()
|
||||
|
||||
assert engine.can_delegate_to("librarian") is True
|
||||
|
||||
|
||||
@pytest.mark.unit
|
||||
class TestDelegationExecution:
|
||||
"""Tests for delegation execution."""
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_execute_delegation_unavailable_agent(
|
||||
self, mock_registry, librarian_intent
|
||||
):
|
||||
"""Test delegation fails for unavailable agent."""
|
||||
mock_registry.get_member.return_value = None
|
||||
|
||||
engine = CoordinationEngine()
|
||||
|
||||
with pytest.raises(AgentUnavailableError) as exc_info:
|
||||
await engine.execute_delegation(librarian_intent)
|
||||
|
||||
assert "librarian" in str(exc_info.value)
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_execute_delegation_success(
|
||||
self, mock_registry, librarian_intent
|
||||
):
|
||||
"""Test successful delegation execution."""
|
||||
# Setup mock member with agent
|
||||
mock_member = MagicMock()
|
||||
mock_member.agent = MagicMock()
|
||||
mock_registry.get_member.return_value = mock_member
|
||||
|
||||
# Mock the executor
|
||||
with patch(
|
||||
"src.agents.coordination.AGENT_EXECUTORS",
|
||||
{"librarian": AsyncMock(return_value="Research results here")},
|
||||
):
|
||||
engine = CoordinationEngine()
|
||||
response = await engine.execute_delegation(librarian_intent)
|
||||
|
||||
assert response.success is True
|
||||
assert response.result == "Research results here"
|
||||
# Duration might be 0 for very fast mock execution
|
||||
assert response.duration_ms >= 0
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_execute_delegation_error(
|
||||
self, mock_registry, librarian_intent
|
||||
):
|
||||
"""Test delegation handles executor errors."""
|
||||
mock_member = MagicMock()
|
||||
mock_member.agent = MagicMock()
|
||||
mock_registry.get_member.return_value = mock_member
|
||||
|
||||
# Mock executor that raises
|
||||
async def failing_executor(**kwargs):
|
||||
raise ValueError("API connection failed")
|
||||
|
||||
with patch(
|
||||
"src.agents.coordination.AGENT_EXECUTORS",
|
||||
{"librarian": failing_executor},
|
||||
):
|
||||
engine = CoordinationEngine()
|
||||
response = await engine.execute_delegation(librarian_intent)
|
||||
|
||||
assert response.success is False
|
||||
assert "API connection failed" in response.error_message
|
||||
|
||||
|
||||
@pytest.mark.unit
|
||||
class TestCoordinate:
|
||||
"""Tests for multi-agent coordination."""
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_coordinate_single_intent(self, mock_registry, librarian_intent):
|
||||
"""Test coordinating a single delegation."""
|
||||
mock_member = MagicMock()
|
||||
mock_member.agent = MagicMock()
|
||||
mock_registry.get_member.return_value = mock_member
|
||||
|
||||
with patch(
|
||||
"src.agents.coordination.AGENT_EXECUTORS",
|
||||
{"librarian": AsyncMock(return_value="Found docs")},
|
||||
):
|
||||
engine = CoordinationEngine()
|
||||
result = await engine.coordinate([librarian_intent])
|
||||
|
||||
assert result.final_response == "Found docs"
|
||||
assert "librarian" in result.agents_consulted
|
||||
# Duration might be 0 for very fast mock execution
|
||||
assert result.total_duration_ms >= 0
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_coordinate_empty_intents(self, mock_registry):
|
||||
"""Test coordinating with no intents."""
|
||||
engine = CoordinationEngine()
|
||||
result = await engine.coordinate([])
|
||||
|
||||
assert result.final_response == ""
|
||||
assert result.agents_consulted == []
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_coordinate_multiple_intents(self, mock_registry):
|
||||
"""Test coordinating multiple delegations."""
|
||||
mock_member = MagicMock()
|
||||
mock_member.agent = MagicMock()
|
||||
mock_registry.get_member.return_value = mock_member
|
||||
|
||||
intents = [
|
||||
DelegationIntent(
|
||||
target_agent="librarian",
|
||||
task="Task 1",
|
||||
reason=DelegationReason.DOMAIN_EXPERTISE,
|
||||
expected_outcome="Result 1",
|
||||
priority=1,
|
||||
),
|
||||
DelegationIntent(
|
||||
target_agent="librarian",
|
||||
task="Task 2",
|
||||
reason=DelegationReason.DOMAIN_EXPERTISE,
|
||||
expected_outcome="Result 2",
|
||||
priority=2,
|
||||
),
|
||||
]
|
||||
|
||||
call_count = 0
|
||||
|
||||
async def mock_executor(**kwargs):
|
||||
nonlocal call_count
|
||||
call_count += 1
|
||||
return f"Result {call_count}"
|
||||
|
||||
with patch(
|
||||
"src.agents.coordination.AGENT_EXECUTORS",
|
||||
{"librarian": mock_executor},
|
||||
):
|
||||
engine = CoordinationEngine()
|
||||
result = await engine.coordinate(intents)
|
||||
|
||||
# Both intents were executed (check agents_consulted count)
|
||||
assert len(result.agents_consulted) == 2
|
||||
# Current implementation replaces same-agent responses in dict
|
||||
# So final_response has the last result (or combined if different agents)
|
||||
assert len(result.final_response) > 0
|
||||
|
||||
|
||||
@pytest.mark.unit
|
||||
class TestDelegateToLibrarian:
|
||||
"""Tests for convenience delegation function."""
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_delegate_to_librarian(self, mock_registry):
|
||||
"""Test the delegate_to_librarian helper."""
|
||||
mock_member = MagicMock()
|
||||
mock_member.agent = MagicMock()
|
||||
mock_registry.get_member.return_value = mock_member
|
||||
|
||||
with patch(
|
||||
"src.agents.coordination.AGENT_EXECUTORS",
|
||||
{"librarian": AsyncMock(return_value="Wiki search results")},
|
||||
):
|
||||
# Reset global engine
|
||||
with patch(
|
||||
"src.agents.coordination._coordination_engine",
|
||||
None,
|
||||
):
|
||||
response = await delegate_to_librarian(
|
||||
task="Search for Docker docs",
|
||||
context="Setting up homelab",
|
||||
)
|
||||
|
||||
assert response.success is True
|
||||
assert response.result == "Wiki search results"
|
||||
|
||||
|
||||
@pytest.mark.unit
|
||||
class TestGetCoordinationEngine:
|
||||
"""Tests for engine singleton."""
|
||||
|
||||
def test_get_coordination_engine_singleton(self):
|
||||
"""Test engine is singleton."""
|
||||
with patch("src.agents.coordination._coordination_engine", None):
|
||||
engine1 = get_coordination_engine()
|
||||
engine2 = get_coordination_engine()
|
||||
|
||||
# Should be same instance
|
||||
assert engine1 is engine2
|
||||
|
||||
|
||||
@pytest.mark.unit
|
||||
class TestDelegationStreaming:
|
||||
"""Tests for streaming delegation."""
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_execute_delegation_stream_unavailable(
|
||||
self, mock_registry, librarian_intent
|
||||
):
|
||||
"""Test streaming fails for unavailable agent."""
|
||||
engine = CoordinationEngine()
|
||||
|
||||
# Change target to an agent that doesn't have a stream executor
|
||||
librarian_intent.target_agent = "nonexistent_agent"
|
||||
|
||||
with pytest.raises(AgentUnavailableError):
|
||||
async for _ in engine.execute_delegation_stream(librarian_intent):
|
||||
pass
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_execute_delegation_stream_success(
|
||||
self, mock_registry, librarian_intent
|
||||
):
|
||||
"""Test successful streaming delegation."""
|
||||
mock_member = MagicMock()
|
||||
mock_member.agent = MagicMock()
|
||||
mock_registry.get_member.return_value = mock_member
|
||||
|
||||
async def mock_stream(**kwargs):
|
||||
yield "Hello "
|
||||
yield "world"
|
||||
|
||||
with patch(
|
||||
"src.agents.coordination.AGENT_STREAM_EXECUTORS",
|
||||
{"librarian": mock_stream},
|
||||
):
|
||||
engine = CoordinationEngine()
|
||||
chunks = []
|
||||
async for chunk in engine.execute_delegation_stream(librarian_intent):
|
||||
chunks.append(chunk)
|
||||
|
||||
assert chunks == ["Hello ", "world"]
|
||||
@@ -4,21 +4,79 @@ Tests for delegation infrastructure.
|
||||
Tests the DelegationTask dataclass and delegation wrapper functions
|
||||
that implement the agent-as-tool pattern.
|
||||
"""
|
||||
from unittest.mock import AsyncMock, patch
|
||||
|
||||
import pytest
|
||||
from unittest.mock import AsyncMock, patch, MagicMock
|
||||
|
||||
from src.agents.delegation import (
|
||||
ActionType,
|
||||
DelegationTask,
|
||||
DelegationResult,
|
||||
HOUSEHOLD_THINK_MESSAGES,
|
||||
STREAMING_DELEGATION_WRAPPERS,
|
||||
ActionType,
|
||||
DelegationResult,
|
||||
DelegationTask,
|
||||
_detect_action_type,
|
||||
build_delegation_context,
|
||||
delegate_to_librarian,
|
||||
get_think_message,
|
||||
_detect_action_type,
|
||||
)
|
||||
|
||||
|
||||
@pytest.mark.unit
|
||||
class TestBuildDelegationContext:
|
||||
"""Tests for trimming conversation history into expert context."""
|
||||
|
||||
def test_empty_history_returns_empty(self):
|
||||
assert build_delegation_context(None) == ""
|
||||
assert build_delegation_context([]) == ""
|
||||
|
||||
def test_recent_turns_are_formatted(self):
|
||||
history = [
|
||||
{"role": "user", "content": "Tell me about Docker"},
|
||||
{"role": "assistant", "content": "Docker is a container runtime."},
|
||||
]
|
||||
|
||||
context = build_delegation_context(history)
|
||||
|
||||
assert "Recent conversation:" in context
|
||||
assert "user: Tell me about Docker" in context
|
||||
assert "assistant: Docker is a container runtime." in context
|
||||
|
||||
def test_only_last_max_turns_kept(self):
|
||||
history = [
|
||||
{"role": "user", "content": f"message {i}"} for i in range(10)
|
||||
]
|
||||
|
||||
context = build_delegation_context(history, max_turns=6)
|
||||
|
||||
assert "message 3" not in context
|
||||
assert "message 4" in context
|
||||
assert "message 9" in context
|
||||
|
||||
def test_long_turns_are_truncated(self):
|
||||
history = [{"role": "user", "content": "x" * 2000}]
|
||||
|
||||
context = build_delegation_context(history, max_chars_per_turn=500)
|
||||
|
||||
assert "x" * 500 in context
|
||||
assert "x" * 501 not in context
|
||||
|
||||
def test_structured_content_parts_tolerated(self):
|
||||
history = [
|
||||
{"role": "user", "content": [{"type": "text", "text": "hello there"}]}
|
||||
]
|
||||
|
||||
context = build_delegation_context(history)
|
||||
|
||||
assert "hello there" in context
|
||||
|
||||
def test_non_dict_entries_skipped(self):
|
||||
history = ["garbage", {"role": "user", "content": "real message"}]
|
||||
|
||||
context = build_delegation_context(history)
|
||||
|
||||
assert "real message" in context
|
||||
assert "garbage" not in context
|
||||
|
||||
|
||||
@pytest.mark.unit
|
||||
class TestDelegationTask:
|
||||
"""Tests for the DelegationTask dataclass."""
|
||||
@@ -170,11 +228,11 @@ class TestDelegateToLibrarian:
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_delegate_to_librarian_handles_error(self):
|
||||
"""Test delegation handles Librarian errors gracefully."""
|
||||
"""Test delegation maps Librarian errors to a user-safe result."""
|
||||
with patch(
|
||||
"src.agents.librarian.agent.run_librarian",
|
||||
new_callable=AsyncMock,
|
||||
side_effect=Exception("Connection refused"),
|
||||
side_effect=Exception("Connection refused to http://internal:8089"),
|
||||
):
|
||||
result = await delegate_to_librarian(
|
||||
task="Search for information",
|
||||
@@ -182,8 +240,39 @@ class TestDelegateToLibrarian:
|
||||
|
||||
assert isinstance(result, DelegationResult)
|
||||
assert result.success is False
|
||||
assert result.output == ""
|
||||
assert result.error == "Connection refused"
|
||||
# Output carries a curated butler-toned sentence
|
||||
assert result.output == get_think_message(
|
||||
"librarian", "Search for information", "error"
|
||||
)
|
||||
# Exception detail stays in logs only - never in the result
|
||||
assert "Connection refused" not in result.output
|
||||
assert result.error is not None
|
||||
assert "Connection refused" not in result.error
|
||||
assert "internal" not in result.error
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_delegate_to_librarian_timeout(self, monkeypatch):
|
||||
"""Delegation is capped by LIBRARIAN_TIMEOUT and fails honestly."""
|
||||
import asyncio
|
||||
|
||||
from src.core.config import config
|
||||
|
||||
async def slow_run(task, context=""):
|
||||
await asyncio.sleep(5)
|
||||
return "too late"
|
||||
|
||||
monkeypatch.setattr(config, "LIBRARIAN_TIMEOUT", 0.05)
|
||||
|
||||
with patch(
|
||||
"src.agents.librarian.agent.run_librarian",
|
||||
new=slow_run,
|
||||
):
|
||||
result = await delegate_to_librarian(task="Search for information")
|
||||
|
||||
assert result.success is False
|
||||
assert "longer than expected" in result.output
|
||||
assert result.error is not None
|
||||
assert "time budget" in result.error
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_delegate_to_librarian_preserves_task(self):
|
||||
@@ -340,20 +429,3 @@ class TestGetThinkMessage:
|
||||
msg = get_think_message("unknown_expert", "some task", "start")
|
||||
assert "<think>" not in msg
|
||||
assert "unknown_expert" in msg.lower()
|
||||
|
||||
|
||||
@pytest.mark.unit
|
||||
class TestStreamingDelegationWrappers:
|
||||
"""Tests for streaming delegation wrapper mapping."""
|
||||
|
||||
def test_streaming_wrappers_exist(self):
|
||||
"""Test streaming wrappers mapping has all experts."""
|
||||
assert "librarian" in STREAMING_DELEGATION_WRAPPERS
|
||||
assert "biographer" in STREAMING_DELEGATION_WRAPPERS
|
||||
assert "housekeeper" in STREAMING_DELEGATION_WRAPPERS
|
||||
|
||||
def test_streaming_wrappers_are_async_generators(self):
|
||||
"""Test streaming wrappers are async generator functions."""
|
||||
import inspect
|
||||
for name, wrapper in STREAMING_DELEGATION_WRAPPERS.items():
|
||||
assert inspect.isasyncgenfunction(wrapper), f"{name} is not an async generator"
|
||||
|
||||
+15
-240
@@ -1,256 +1,31 @@
|
||||
"""
|
||||
Tests for agent communication protocol.
|
||||
Tests for the agent error protocol.
|
||||
"""
|
||||
|
||||
import pytest
|
||||
|
||||
from src.agents.protocol import (
|
||||
AgentError,
|
||||
AgentRequest,
|
||||
AgentResponse,
|
||||
AgentTimeoutError,
|
||||
AgentUnavailableError,
|
||||
CoordinationResult,
|
||||
DelegationIntent,
|
||||
DelegationReason,
|
||||
ToolCallRecord,
|
||||
)
|
||||
from src.agents.protocol import AgentError
|
||||
|
||||
|
||||
@pytest.mark.unit
|
||||
class TestAgentRequest:
|
||||
"""Tests for AgentRequest model."""
|
||||
class TestAgentError:
|
||||
"""Tests for the AgentError exception."""
|
||||
|
||||
def test_basic_request(self):
|
||||
"""Test creating a basic agent request."""
|
||||
request = AgentRequest(task="Find information about Docker")
|
||||
|
||||
assert request.task == "Find information about Docker"
|
||||
assert request.context == ""
|
||||
assert request.timeout_seconds == 60
|
||||
|
||||
def test_request_with_context(self):
|
||||
"""Test request with additional context."""
|
||||
request = AgentRequest(
|
||||
task="Find Docker networking docs",
|
||||
context="User is setting up a homelab",
|
||||
delegation_reason=DelegationReason.DOMAIN_EXPERTISE,
|
||||
)
|
||||
|
||||
assert request.task == "Find Docker networking docs"
|
||||
assert request.context == "User is setting up a homelab"
|
||||
assert request.delegation_reason == DelegationReason.DOMAIN_EXPERTISE
|
||||
|
||||
def test_request_serialization(self):
|
||||
"""Test request can be serialized to dict."""
|
||||
request = AgentRequest(
|
||||
task="Research task",
|
||||
context="Some context",
|
||||
)
|
||||
|
||||
data = request.model_dump()
|
||||
|
||||
assert data["task"] == "Research task"
|
||||
assert data["context"] == "Some context"
|
||||
|
||||
|
||||
@pytest.mark.unit
|
||||
class TestAgentResponse:
|
||||
"""Tests for AgentResponse model."""
|
||||
|
||||
def test_successful_response(self):
|
||||
"""Test creating a successful response."""
|
||||
response = AgentResponse(
|
||||
success=True,
|
||||
result="Here are the findings...",
|
||||
reasoning="Searched wiki and found relevant docs",
|
||||
duration_ms=1500,
|
||||
)
|
||||
|
||||
assert response.success is True
|
||||
assert response.result == "Here are the findings..."
|
||||
assert response.reasoning == "Searched wiki and found relevant docs"
|
||||
assert response.duration_ms == 1500
|
||||
assert response.error_message is None
|
||||
|
||||
def test_failed_response(self):
|
||||
"""Test creating a failed response."""
|
||||
response = AgentResponse(
|
||||
success=False,
|
||||
result="",
|
||||
error_message="Connection timeout",
|
||||
duration_ms=30000,
|
||||
)
|
||||
|
||||
assert response.success is False
|
||||
assert response.result == ""
|
||||
assert response.error_message == "Connection timeout"
|
||||
|
||||
def test_response_with_tool_calls(self):
|
||||
"""Test response tracking tool calls."""
|
||||
tool_call = ToolCallRecord(
|
||||
tool_name="hybrid_search",
|
||||
arguments={"query": "Docker networking"},
|
||||
result="Found 5 results",
|
||||
duration_ms=500,
|
||||
)
|
||||
|
||||
response = AgentResponse(
|
||||
success=True,
|
||||
result="Based on search...",
|
||||
tool_calls=[tool_call],
|
||||
)
|
||||
|
||||
assert len(response.tool_calls) == 1
|
||||
assert response.tool_calls[0].tool_name == "hybrid_search"
|
||||
|
||||
|
||||
@pytest.mark.unit
|
||||
class TestDelegationIntent:
|
||||
"""Tests for DelegationIntent model."""
|
||||
|
||||
def test_basic_intent(self):
|
||||
"""Test creating a basic delegation intent."""
|
||||
intent = DelegationIntent(
|
||||
target_agent="librarian",
|
||||
task="Research Docker networking",
|
||||
reason=DelegationReason.DOMAIN_EXPERTISE,
|
||||
expected_outcome="Documentation and examples",
|
||||
)
|
||||
|
||||
assert intent.target_agent == "librarian"
|
||||
assert intent.task == "Research Docker networking"
|
||||
assert intent.reason == DelegationReason.DOMAIN_EXPERTISE
|
||||
assert intent.priority == 1 # Default
|
||||
|
||||
def test_intent_with_priority(self):
|
||||
"""Test intent with custom priority."""
|
||||
intent = DelegationIntent(
|
||||
target_agent="librarian",
|
||||
task="Urgent research",
|
||||
reason=DelegationReason.RESOURCE_EFFICIENCY,
|
||||
expected_outcome="Quick answer",
|
||||
priority=1,
|
||||
)
|
||||
|
||||
assert intent.priority == 1
|
||||
|
||||
|
||||
@pytest.mark.unit
|
||||
class TestDelegationReason:
|
||||
"""Tests for DelegationReason enum."""
|
||||
|
||||
def test_all_reasons_have_values(self):
|
||||
"""Test all delegation reasons are defined."""
|
||||
reasons = list(DelegationReason)
|
||||
|
||||
assert DelegationReason.DOMAIN_EXPERTISE in reasons
|
||||
assert DelegationReason.TOOL_ACCESS in reasons
|
||||
assert DelegationReason.RESOURCE_EFFICIENCY in reasons
|
||||
assert DelegationReason.USER_PREFERENCE in reasons
|
||||
|
||||
|
||||
@pytest.mark.unit
|
||||
class TestCoordinationResult:
|
||||
"""Tests for CoordinationResult model."""
|
||||
|
||||
def test_single_agent_result(self):
|
||||
"""Test coordination with single agent."""
|
||||
agent_response = AgentResponse(
|
||||
success=True,
|
||||
result="Research findings",
|
||||
duration_ms=1000,
|
||||
)
|
||||
|
||||
intent = DelegationIntent(
|
||||
target_agent="librarian",
|
||||
task="Research task",
|
||||
reason=DelegationReason.DOMAIN_EXPERTISE,
|
||||
expected_outcome="Findings",
|
||||
)
|
||||
|
||||
result = CoordinationResult(
|
||||
final_response="Research findings",
|
||||
agent_responses={"librarian": agent_response},
|
||||
delegation_intents=[intent],
|
||||
total_duration_ms=1200,
|
||||
agents_consulted=["librarian"],
|
||||
)
|
||||
|
||||
assert result.final_response == "Research findings"
|
||||
assert len(result.agent_responses) == 1
|
||||
assert result.agents_consulted == ["librarian"]
|
||||
|
||||
def test_empty_result(self):
|
||||
"""Test coordination with no delegations."""
|
||||
result = CoordinationResult(
|
||||
final_response="",
|
||||
agent_responses={},
|
||||
delegation_intents=[],
|
||||
total_duration_ms=0,
|
||||
agents_consulted=[],
|
||||
)
|
||||
|
||||
assert result.final_response == ""
|
||||
assert len(result.agents_consulted) == 0
|
||||
|
||||
|
||||
@pytest.mark.unit
|
||||
class TestAgentErrors:
|
||||
"""Tests for agent error types."""
|
||||
|
||||
def test_agent_error(self):
|
||||
"""Test base AgentError."""
|
||||
def test_agent_error_defaults(self):
|
||||
"""Test base AgentError with default agent name."""
|
||||
error = AgentError("Something went wrong")
|
||||
|
||||
assert "Something went wrong" in str(error)
|
||||
assert error.agent_name == "unknown"
|
||||
|
||||
def test_agent_timeout_error(self):
|
||||
"""Test AgentTimeoutError."""
|
||||
error = AgentTimeoutError(
|
||||
"Timed out after 60s",
|
||||
agent_name="librarian",
|
||||
)
|
||||
def test_agent_error_carries_agent_name(self):
|
||||
"""Agent name is stored and prefixed into the message."""
|
||||
error = AgentError("Research task failed", agent_name="librarian")
|
||||
|
||||
assert "Timed out" in str(error)
|
||||
assert error.agent_name == "librarian"
|
||||
assert str(error) == "[librarian] Research task failed"
|
||||
assert error.message == "Research task failed"
|
||||
|
||||
def test_agent_unavailable_error(self):
|
||||
"""Test AgentUnavailableError."""
|
||||
error = AgentUnavailableError(
|
||||
"Agent not registered",
|
||||
agent_name="unknown_agent",
|
||||
)
|
||||
|
||||
assert "not registered" in str(error)
|
||||
assert error.agent_name == "unknown_agent"
|
||||
|
||||
|
||||
@pytest.mark.unit
|
||||
class TestToolCallRecord:
|
||||
"""Tests for ToolCallRecord model."""
|
||||
|
||||
def test_tool_call_record(self):
|
||||
"""Test creating a tool call record."""
|
||||
record = ToolCallRecord(
|
||||
tool_name="semantic_search",
|
||||
arguments={"query": "networking concepts", "limit": 10},
|
||||
result="Found 10 relevant documents",
|
||||
duration_ms=250,
|
||||
)
|
||||
|
||||
assert record.tool_name == "semantic_search"
|
||||
assert record.arguments["query"] == "networking concepts"
|
||||
assert record.duration_ms == 250
|
||||
|
||||
def test_tool_call_with_empty_result(self):
|
||||
"""Test tool call with empty result."""
|
||||
record = ToolCallRecord(
|
||||
tool_name="query_graph",
|
||||
arguments={"cypher": "MATCH (n) RETURN n"},
|
||||
result="",
|
||||
duration_ms=100,
|
||||
)
|
||||
|
||||
assert record.result == ""
|
||||
def test_agent_error_is_catchable_as_exception(self):
|
||||
"""AgentError participates in normal exception handling."""
|
||||
with pytest.raises(AgentError):
|
||||
raise AgentError("boom", agent_name="librarian")
|
||||
|
||||
@@ -34,7 +34,7 @@ async def test_tatlock_conversation_history_memory(async_client: AsyncClient):
|
||||
response_1 = await async_client.post(
|
||||
"/v1/chat/completions",
|
||||
json=request_data_1,
|
||||
timeout=30.0
|
||||
timeout=120.0
|
||||
)
|
||||
|
||||
assert response_1.status_code == 200
|
||||
@@ -56,7 +56,7 @@ async def test_tatlock_conversation_history_memory(async_client: AsyncClient):
|
||||
response_2 = await async_client.post(
|
||||
"/v1/chat/completions",
|
||||
json=request_data_2,
|
||||
timeout=30.0
|
||||
timeout=120.0
|
||||
)
|
||||
|
||||
assert response_2.status_code == 200
|
||||
@@ -95,7 +95,7 @@ async def test_tatlock_multi_turn_context(async_client: AsyncClient):
|
||||
response_1 = await async_client.post(
|
||||
"/v1/chat/completions",
|
||||
json=request_1,
|
||||
timeout=30.0
|
||||
timeout=120.0
|
||||
)
|
||||
|
||||
assert response_1.status_code == 200
|
||||
@@ -117,7 +117,7 @@ async def test_tatlock_multi_turn_context(async_client: AsyncClient):
|
||||
response_2 = await async_client.post(
|
||||
"/v1/chat/completions",
|
||||
json=request_2,
|
||||
timeout=30.0
|
||||
timeout=120.0
|
||||
)
|
||||
|
||||
assert response_2.status_code == 200
|
||||
@@ -150,7 +150,7 @@ async def test_tatlock_tool_call_logging_search(async_client: AsyncClient):
|
||||
response = await async_client.post(
|
||||
"/v1/chat/completions",
|
||||
json=request_data,
|
||||
timeout=60.0
|
||||
timeout=120.0
|
||||
)
|
||||
|
||||
assert response.status_code == 200
|
||||
@@ -192,7 +192,7 @@ async def test_tatlock_tool_call_logging_calculator(async_client: AsyncClient):
|
||||
response = await async_client.post(
|
||||
"/v1/chat/completions",
|
||||
json=request_data,
|
||||
timeout=30.0
|
||||
timeout=120.0
|
||||
)
|
||||
|
||||
assert response.status_code == 200
|
||||
@@ -243,7 +243,7 @@ async def test_tatlock_tool_call_logging_datetime(async_client: AsyncClient):
|
||||
response = await async_client.post(
|
||||
"/v1/chat/completions",
|
||||
json=request_data,
|
||||
timeout=30.0
|
||||
timeout=120.0
|
||||
)
|
||||
|
||||
assert response.status_code == 200
|
||||
@@ -293,7 +293,7 @@ async def test_tatlock_no_tool_calls_no_logging(async_client: AsyncClient):
|
||||
response = await async_client.post(
|
||||
"/v1/chat/completions",
|
||||
json=request_data,
|
||||
timeout=30.0
|
||||
timeout=120.0
|
||||
)
|
||||
|
||||
assert response.status_code == 200
|
||||
@@ -336,7 +336,7 @@ async def test_tatlock_conversation_history_with_tools(async_client: AsyncClient
|
||||
response_1 = await async_client.post(
|
||||
"/v1/chat/completions",
|
||||
json=request_1,
|
||||
timeout=30.0
|
||||
timeout=120.0
|
||||
)
|
||||
|
||||
assert response_1.status_code == 200
|
||||
@@ -362,7 +362,7 @@ async def test_tatlock_conversation_history_with_tools(async_client: AsyncClient
|
||||
response_2 = await async_client.post(
|
||||
"/v1/chat/completions",
|
||||
json=request_2,
|
||||
timeout=30.0
|
||||
timeout=120.0
|
||||
)
|
||||
|
||||
assert response_2.status_code == 200
|
||||
@@ -378,3 +378,57 @@ async def test_tatlock_conversation_history_with_tools(async_client: AsyncClient
|
||||
)
|
||||
if not has_calculation:
|
||||
pytest.xfail(f"LLM did not remember calculation (non-deterministic): {second_response[:200]}")
|
||||
|
||||
|
||||
@pytest.mark.integration
|
||||
@pytest.mark.asyncio
|
||||
async def test_tatlock_ollama_fallback(async_client: AsyncClient):
|
||||
"""
|
||||
Test that Tatlock falls back to Ollama when Claude is unavailable.
|
||||
|
||||
Patches _claude_available to False to force the Ollama path,
|
||||
then verifies the system still produces a valid response.
|
||||
"""
|
||||
import src.anthropic.model_selector as model_selector
|
||||
|
||||
# Save original value
|
||||
original = model_selector._claude_available
|
||||
|
||||
try:
|
||||
# Force Ollama fallback
|
||||
model_selector._claude_available = False
|
||||
|
||||
# Verify we're actually using Ollama
|
||||
info = model_selector.get_model_info()
|
||||
assert info["backend"] == "ollama", f"Expected ollama backend, got {info['backend']}"
|
||||
|
||||
request_data = {
|
||||
"model": "Tatlock",
|
||||
"messages": [
|
||||
{"role": "user", "content": "Say hello to me."}
|
||||
],
|
||||
"stream": False
|
||||
}
|
||||
|
||||
# 300s: this test forbids the Claude rescue, and the full local
|
||||
# Steward -> orchestrate -> synthesize flow on gemma4 exceeds 120s
|
||||
response = await async_client.post(
|
||||
"/v1/chat/completions",
|
||||
json=request_data,
|
||||
timeout=300.0
|
||||
)
|
||||
|
||||
assert response.status_code == 200
|
||||
data = response.json()
|
||||
|
||||
# Verify response structure is valid
|
||||
assert "choices" in data
|
||||
assert len(data["choices"]) == 1
|
||||
full_response = data["choices"][0]["message"]["content"]
|
||||
assert len(full_response) > 0, "Ollama should produce a non-empty response"
|
||||
|
||||
print(f"\nOllama fallback response: {full_response[:200]}")
|
||||
|
||||
finally:
|
||||
# Restore original value
|
||||
model_selector._claude_available = original
|
||||
|
||||
@@ -0,0 +1,92 @@
|
||||
"""
|
||||
Unit tests for backend selection (Ollama primary, Claude fallback).
|
||||
|
||||
These tests set the cached health-check globals directly so they are
|
||||
deterministic regardless of which services are reachable.
|
||||
"""
|
||||
import pytest
|
||||
|
||||
from src.anthropic import model_selector
|
||||
from src.core.config import config
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def local_first(monkeypatch):
|
||||
"""Baseline: local-first config, both backends healthy."""
|
||||
monkeypatch.setattr(config, "PREFER_CLOUD_BACKEND", False)
|
||||
monkeypatch.setattr(config, "ANTHROPIC_API_KEY", "sk-test-fake")
|
||||
monkeypatch.setattr(model_selector, "_claude_available", True)
|
||||
monkeypatch.setattr(model_selector, "_ollama_available", True)
|
||||
|
||||
|
||||
class TestResolveBackend:
|
||||
def test_default_is_ollama(self, local_first):
|
||||
assert model_selector.resolve_backend() == "ollama"
|
||||
|
||||
def test_prefer_cloud_config_selects_claude(self, local_first, monkeypatch):
|
||||
monkeypatch.setattr(config, "PREFER_CLOUD_BACKEND", True)
|
||||
assert model_selector.resolve_backend() == "claude"
|
||||
|
||||
def test_prefer_cloud_override_selects_claude(self, local_first):
|
||||
assert model_selector.resolve_backend(prefer_cloud=True) == "claude"
|
||||
|
||||
def test_prefer_cloud_without_claude_falls_back_to_ollama(self, local_first, monkeypatch):
|
||||
monkeypatch.setattr(config, "PREFER_CLOUD_BACKEND", True)
|
||||
monkeypatch.setattr(model_selector, "_claude_available", False)
|
||||
assert model_selector.resolve_backend() == "ollama"
|
||||
|
||||
def test_ollama_down_falls_back_to_claude(self, local_first, monkeypatch):
|
||||
monkeypatch.setattr(model_selector, "_ollama_available", False)
|
||||
assert model_selector.resolve_backend() == "claude"
|
||||
|
||||
def test_ollama_down_without_claude_stays_ollama(self, local_first, monkeypatch):
|
||||
monkeypatch.setattr(model_selector, "_ollama_available", False)
|
||||
monkeypatch.setattr(model_selector, "_claude_available", False)
|
||||
assert model_selector.resolve_backend() == "ollama"
|
||||
|
||||
def test_unknown_ollama_state_counts_as_available(self, local_first, monkeypatch):
|
||||
monkeypatch.setattr(model_selector, "_ollama_available", None)
|
||||
assert model_selector.resolve_backend() == "ollama"
|
||||
|
||||
|
||||
class TestGetModel:
|
||||
def test_ollama_backend_returns_openai_chat_model(self, local_first):
|
||||
from pydantic_ai.models.openai import OpenAIChatModel
|
||||
|
||||
model = model_selector.get_model()
|
||||
assert isinstance(model, OpenAIChatModel)
|
||||
assert model.model_name == config.OLLAMA_DEFAULT_MODEL
|
||||
|
||||
def test_claude_backend_returns_anthropic_model(self, local_first):
|
||||
from pydantic_ai.models.anthropic import AnthropicModel
|
||||
|
||||
model = model_selector.get_model(prefer_cloud=True)
|
||||
assert isinstance(model, AnthropicModel)
|
||||
assert model.model_name == config.ANTHROPIC_MODEL
|
||||
|
||||
|
||||
class TestToolChoiceSettings:
|
||||
def test_ollama_forces_tool_choice(self, local_first):
|
||||
settings = model_selector.get_tool_choice_settings()
|
||||
assert settings.get("extra_body") == {"tool_choice": "required"}
|
||||
|
||||
def test_claude_uses_native_tool_choice(self, local_first, monkeypatch):
|
||||
monkeypatch.setattr(config, "PREFER_CLOUD_BACKEND", True)
|
||||
settings = model_selector.get_tool_choice_settings()
|
||||
assert not settings.get("extra_body")
|
||||
|
||||
|
||||
class TestGetModelInfo:
|
||||
def test_reports_ollama_primary(self, local_first):
|
||||
info = model_selector.get_model_info()
|
||||
assert info["backend"] == "ollama"
|
||||
assert info["model"] == config.OLLAMA_DEFAULT_MODEL
|
||||
assert info["ollama_available"] is True
|
||||
assert info["claude_available"] is True
|
||||
assert info["prefer_cloud"] is False
|
||||
|
||||
def test_reports_claude_when_ollama_down(self, local_first, monkeypatch):
|
||||
monkeypatch.setattr(model_selector, "_ollama_available", False)
|
||||
info = model_selector.get_model_info()
|
||||
assert info["backend"] == "claude"
|
||||
assert info["model"] == config.ANTHROPIC_MODEL
|
||||
+54
-1
@@ -2,6 +2,8 @@
|
||||
Shared test fixtures for all tests.
|
||||
Following FastAPI testing best practices.
|
||||
"""
|
||||
import asyncio
|
||||
|
||||
import pytest
|
||||
from fastapi.testclient import TestClient
|
||||
from httpx import AsyncClient, ASGITransport
|
||||
@@ -9,6 +11,57 @@ from httpx import AsyncClient, ASGITransport
|
||||
from src.main import app
|
||||
|
||||
|
||||
@pytest.fixture(scope="session", autouse=True)
|
||||
def _tenant_guard():
|
||||
"""
|
||||
Hard-fail the whole suite if the effective tenant resolves to the
|
||||
production tenant ("jpmschweitzer").
|
||||
|
||||
Isolation is tenant-based: tests that touch shared services
|
||||
(Qdrant memories collections, Wiki.js via library-desk, Neo4j,
|
||||
Redis) must run under the reserved test tenant "llm_tester" (or a
|
||||
test_-prefixed namespace). This mirrors the guard library-desk
|
||||
applies on its side.
|
||||
"""
|
||||
from src.core.config import PRODUCTION_TENANT, config
|
||||
from src.core.context import get_default_user
|
||||
from src.core.multi_tenancy import get_memory_collection_name
|
||||
|
||||
effective = get_default_user()
|
||||
if (
|
||||
effective == PRODUCTION_TENANT
|
||||
or config.effective_default_user == PRODUCTION_TENANT
|
||||
):
|
||||
pytest.exit(
|
||||
f"TENANT GUARD: refusing to run the test suite - the effective "
|
||||
f"tenant resolves to the production tenant '{PRODUCTION_TENANT}' "
|
||||
f"(ENVIRONMENT={config.ENVIRONMENT.value}, "
|
||||
f"DEFAULT_USER={config.DEFAULT_USER}). Tests must run under "
|
||||
f"'llm_tester' or a test_-prefixed tenant.",
|
||||
returncode=1,
|
||||
)
|
||||
|
||||
# The Qdrant memories namespace derived from the effective tenant
|
||||
# must never be the production collection.
|
||||
assert get_memory_collection_name(effective) != get_memory_collection_name(
|
||||
PRODUCTION_TENANT
|
||||
), "test suite would target the production memories collection"
|
||||
|
||||
|
||||
@pytest.fixture(scope="session", autouse=True)
|
||||
def _initialize_app(_tenant_guard):
|
||||
"""
|
||||
Run application lifespan (Claude health check, household registration, etc.)
|
||||
once per test session. ASGITransport doesn't trigger lifespan events,
|
||||
so we call it explicitly.
|
||||
|
||||
Depends on _tenant_guard so the suite refuses to start under the
|
||||
production tenant before any initialization happens.
|
||||
"""
|
||||
from src.core.startup import initialize_application
|
||||
asyncio.run(initialize_application())
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def client() -> TestClient:
|
||||
"""
|
||||
@@ -37,7 +90,7 @@ async def async_client() -> AsyncClient:
|
||||
def mock_chat_request() -> dict:
|
||||
"""Standard chat completion request fixture."""
|
||||
return {
|
||||
"model": "Tatlock",
|
||||
"model": "lorem-tester",
|
||||
"messages": [
|
||||
{"role": "user", "content": "Hello, world!"}
|
||||
],
|
||||
|
||||
@@ -0,0 +1,219 @@
|
||||
"""
|
||||
Wire-level contract tests for external service boundaries.
|
||||
|
||||
Each test sends the raw request the application code sends (no client
|
||||
wrappers, no mocks) and asserts on the response shape, so boundary
|
||||
breakage is caught directly instead of surfacing as agent misbehavior.
|
||||
|
||||
Semantics:
|
||||
- Service unreachable -> skip (an outage is not a contract violation)
|
||||
- Service reachable but wrong response shape -> fail
|
||||
|
||||
Run with: make test-contracts
|
||||
"""
|
||||
import json
|
||||
|
||||
import httpx
|
||||
import pytest
|
||||
|
||||
from src.core.config import config
|
||||
|
||||
OLLAMA = str(config.OLLAMA_HOST).rstrip("/")
|
||||
QDRANT = f"http://{config.QDRANT_HOST}:{config.QDRANT_PORT}"
|
||||
SEARXNG = str(config.SEARXNG_HOST).rstrip("/")
|
||||
|
||||
CALCULATOR_TOOL = {
|
||||
"type": "function",
|
||||
"function": {
|
||||
"name": "calculator",
|
||||
"description": "Evaluate a math expression",
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {"expression": {"type": "string"}},
|
||||
"required": ["expression"],
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
|
||||
async def _get_or_skip(url: str, service: str, timeout: float = 5.0) -> httpx.Response:
|
||||
"""GET a URL, skipping the test if the service is unreachable."""
|
||||
try:
|
||||
async with httpx.AsyncClient(timeout=timeout) as client:
|
||||
return await client.get(url)
|
||||
except httpx.TransportError as e:
|
||||
pytest.skip(f"{service} unreachable at {url}: {e}")
|
||||
|
||||
|
||||
async def _post_or_skip(
|
||||
url: str, service: str, payload: dict, timeout: float, headers: dict | None = None
|
||||
) -> httpx.Response:
|
||||
"""POST a payload, skipping the test if the service is unreachable."""
|
||||
try:
|
||||
async with httpx.AsyncClient(timeout=timeout) as client:
|
||||
return await client.post(url, json=payload, headers=headers)
|
||||
except httpx.TransportError as e:
|
||||
pytest.skip(f"{service} unreachable at {url}: {e}")
|
||||
|
||||
|
||||
@pytest.mark.contract
|
||||
class TestOllamaContract:
|
||||
"""Boundary: Ollama native API and its OpenAI-compat layer."""
|
||||
|
||||
async def test_tags_lists_configured_model(self):
|
||||
# Mirrors check_ollama_health()
|
||||
response = await _get_or_skip(f"{OLLAMA}/api/tags", "ollama")
|
||||
assert response.status_code == 200
|
||||
names = [m["name"] for m in response.json()["models"]]
|
||||
model = config.OLLAMA_DEFAULT_MODEL
|
||||
assert model in names or f"{model}:latest" in names, (
|
||||
f"{model} not pulled; available: {names}"
|
||||
)
|
||||
|
||||
async def test_generate_returns_plain_text(self):
|
||||
# Mirrors StewardAgent._call_ollama()
|
||||
response = await _post_or_skip(
|
||||
f"{OLLAMA}/api/generate",
|
||||
"ollama",
|
||||
{
|
||||
"model": config.OLLAMA_DEFAULT_MODEL,
|
||||
"prompt": "Reply with the single word: pong",
|
||||
"stream": False,
|
||||
"options": {"temperature": 0.3, "top_p": 0.9},
|
||||
},
|
||||
timeout=config.OLLAMA_TIMEOUT,
|
||||
)
|
||||
assert response.status_code == 200
|
||||
assert response.json()["response"].strip()
|
||||
|
||||
async def test_openai_compat_tool_calling(self):
|
||||
# Mirrors the request PydanticAI's OpenAIChatModel sends for the
|
||||
# orchestration phase, including the extra_body tool_choice.
|
||||
response = await _post_or_skip(
|
||||
f"{OLLAMA}/v1/chat/completions",
|
||||
"ollama",
|
||||
{
|
||||
"model": config.OLLAMA_DEFAULT_MODEL,
|
||||
"messages": [
|
||||
{"role": "user", "content": "What is 6 * 7? Use the calculator."}
|
||||
],
|
||||
"tools": [CALCULATOR_TOOL],
|
||||
"tool_choice": "required",
|
||||
"stream": False,
|
||||
},
|
||||
timeout=config.OLLAMA_TIMEOUT,
|
||||
)
|
||||
assert response.status_code == 200
|
||||
message = response.json()["choices"][0]["message"]
|
||||
tool_calls = message.get("tool_calls")
|
||||
assert tool_calls, f"model answered in text instead of calling the tool: {message}"
|
||||
assert tool_calls[0]["function"]["name"] == "calculator"
|
||||
arguments = json.loads(tool_calls[0]["function"]["arguments"])
|
||||
assert "expression" in arguments
|
||||
|
||||
|
||||
@pytest.mark.contract
|
||||
class TestAnthropicContract:
|
||||
"""Boundary: Anthropic Messages API (the Claude fallback backend)."""
|
||||
|
||||
HEADERS_KEY = "anthropic-version"
|
||||
|
||||
def _headers(self) -> dict:
|
||||
if not config.ANTHROPIC_API_KEY:
|
||||
pytest.skip("ANTHROPIC_API_KEY not configured")
|
||||
return {
|
||||
"x-api-key": config.ANTHROPIC_API_KEY,
|
||||
"anthropic-version": "2023-06-01",
|
||||
}
|
||||
|
||||
async def test_minimal_message_accepted(self):
|
||||
# Mirrors check_claude_health(): tiny request, no sampling params
|
||||
response = await _post_or_skip(
|
||||
"https://api.anthropic.com/v1/messages",
|
||||
"anthropic",
|
||||
{
|
||||
"model": config.ANTHROPIC_MODEL,
|
||||
"max_tokens": 1,
|
||||
"messages": [{"role": "user", "content": "hi"}],
|
||||
},
|
||||
timeout=30.0,
|
||||
headers=self._headers(),
|
||||
)
|
||||
assert response.status_code == 200, response.text
|
||||
|
||||
async def test_temperature_rejected(self):
|
||||
# Pins the Claude Sonnet 5+ contract that broke the Steward:
|
||||
# sampling parameters are rejected with a 400 (and not billed).
|
||||
response = await _post_or_skip(
|
||||
"https://api.anthropic.com/v1/messages",
|
||||
"anthropic",
|
||||
{
|
||||
"model": config.ANTHROPIC_MODEL,
|
||||
"max_tokens": 1,
|
||||
"messages": [{"role": "user", "content": "hi"}],
|
||||
"temperature": 0.3,
|
||||
},
|
||||
timeout=30.0,
|
||||
headers=self._headers(),
|
||||
)
|
||||
assert response.status_code == 400
|
||||
assert "temperature" in response.text
|
||||
|
||||
|
||||
@pytest.mark.contract
|
||||
class TestQdrantContract:
|
||||
"""Boundary: Qdrant REST API (Biographer's vector memory)."""
|
||||
|
||||
async def test_collections_endpoint(self):
|
||||
response = await _get_or_skip(f"{QDRANT}/collections", "qdrant")
|
||||
assert response.status_code == 200
|
||||
assert "collections" in response.json()["result"]
|
||||
|
||||
|
||||
@pytest.mark.contract
|
||||
class TestSearxngContract:
|
||||
"""Boundary: SearXNG JSON search API (web search tool)."""
|
||||
|
||||
async def test_json_search(self):
|
||||
response = await _get_or_skip(
|
||||
f"{SEARXNG}/search?q=test&format=json", "searxng", timeout=config.SEARXNG_TIMEOUT
|
||||
)
|
||||
assert response.status_code == 200
|
||||
assert "results" in response.json()
|
||||
|
||||
|
||||
@pytest.mark.contract
|
||||
class TestLibraryDeskContract:
|
||||
"""Boundary: library-desk research API (the Librarian's backend)."""
|
||||
|
||||
async def test_health(self):
|
||||
host = getattr(config, "LIBRARY_DESK_HOST", None)
|
||||
if not host:
|
||||
pytest.skip("LIBRARY_DESK_HOST not configured")
|
||||
response = await _get_or_skip(f"{str(host).rstrip('/')}/health", "library-desk")
|
||||
assert response.status_code == 200
|
||||
|
||||
|
||||
@pytest.mark.contract
|
||||
class TestRedisContract:
|
||||
"""Boundary: Redis on the configured memory DB."""
|
||||
|
||||
async def test_roundtrip(self):
|
||||
import redis.asyncio as redis
|
||||
|
||||
client = redis.Redis(
|
||||
host=config.REDIS_HOST,
|
||||
port=config.REDIS_PORT,
|
||||
db=config.REDIS_MEMORY_DB,
|
||||
socket_connect_timeout=3,
|
||||
)
|
||||
try:
|
||||
await client.ping()
|
||||
except Exception as e:
|
||||
pytest.skip(f"redis unreachable: {e}")
|
||||
try:
|
||||
await client.set("contract-test-key", "ok", ex=30)
|
||||
assert await client.get("contract-test-key") == b"ok"
|
||||
await client.delete("contract-test-key")
|
||||
finally:
|
||||
await client.aclose()
|
||||
@@ -0,0 +1,300 @@
|
||||
"""
|
||||
Tests for the tenant isolation guard.
|
||||
|
||||
Isolation is tenant-based: the production tenant ("jpmschweitzer") owns
|
||||
real data in the shared services, and every non-production environment
|
||||
must run under the reserved test tenant ("llm_tester") or an explicit
|
||||
"test_"-prefixed namespace.
|
||||
|
||||
Guard matrix covered here: dev/test/prod x default/explicit user, at
|
||||
both config level (effective_default_user) and request-context
|
||||
resolution (get_user).
|
||||
"""
|
||||
|
||||
import pytest
|
||||
from pydantic import ValidationError
|
||||
|
||||
from src.core.config import (
|
||||
PRODUCTION_TENANT,
|
||||
TEST_TENANT,
|
||||
Config,
|
||||
Environment,
|
||||
)
|
||||
from src.core.context import RequestContext, get_user
|
||||
|
||||
|
||||
def make_config(**overrides) -> Config:
|
||||
"""Build a Config isolated from the local .env file."""
|
||||
return Config(_env_file=None, **overrides)
|
||||
|
||||
|
||||
@pytest.mark.unit
|
||||
class TestEffectiveDefaultUserMatrix:
|
||||
"""Config-level guard: effective_default_user per environment."""
|
||||
|
||||
# --- development ---
|
||||
|
||||
def test_dev_without_default_user_forces_test_tenant(self):
|
||||
config = make_config(ENVIRONMENT=Environment.DEVELOPMENT)
|
||||
assert config.effective_default_user == TEST_TENANT
|
||||
assert config.tenant_forced is False
|
||||
|
||||
def test_dev_with_test_tenant_is_kept(self):
|
||||
config = make_config(ENVIRONMENT=Environment.DEVELOPMENT, DEFAULT_USER=TEST_TENANT)
|
||||
assert config.effective_default_user == TEST_TENANT
|
||||
assert config.tenant_forced is False
|
||||
|
||||
def test_dev_with_test_prefixed_override_is_kept(self):
|
||||
config = make_config(ENVIRONMENT=Environment.DEVELOPMENT, DEFAULT_USER="test_phase_b")
|
||||
assert config.effective_default_user == "test_phase_b"
|
||||
assert config.tenant_forced is False
|
||||
|
||||
def test_dev_with_misconfigured_user_is_forced_to_test_tenant(self):
|
||||
config = make_config(ENVIRONMENT=Environment.DEVELOPMENT, DEFAULT_USER="alice")
|
||||
assert config.effective_default_user == TEST_TENANT
|
||||
assert config.tenant_forced is True
|
||||
|
||||
def test_dev_with_production_tenant_refuses_startup(self):
|
||||
with pytest.raises(ValidationError) as exc_info:
|
||||
make_config(
|
||||
ENVIRONMENT=Environment.DEVELOPMENT,
|
||||
DEFAULT_USER=PRODUCTION_TENANT,
|
||||
)
|
||||
assert "Refusing to start" in str(exc_info.value)
|
||||
assert PRODUCTION_TENANT in str(exc_info.value)
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
"variant",
|
||||
[
|
||||
"JPMSchweitzer",
|
||||
"JPMSCHWEITZER",
|
||||
"jpmschweitzer.",
|
||||
" jpmschweitzer",
|
||||
"jpmschweitzer ",
|
||||
"_jpmschweitzer_",
|
||||
"jpmschweitzer!",
|
||||
],
|
||||
)
|
||||
def test_dev_with_production_tenant_variant_refuses_startup(self, variant):
|
||||
"""Sanitization collisions with the production tenant are refused too."""
|
||||
with pytest.raises(ValidationError, match="Refusing to start"):
|
||||
make_config(
|
||||
ENVIRONMENT=Environment.DEVELOPMENT,
|
||||
DEFAULT_USER=variant,
|
||||
)
|
||||
|
||||
# --- testing ---
|
||||
|
||||
def test_testing_without_default_user_forces_test_tenant(self):
|
||||
config = make_config(ENVIRONMENT=Environment.TESTING)
|
||||
assert config.effective_default_user == TEST_TENANT
|
||||
|
||||
def test_testing_with_misconfigured_user_is_forced_to_test_tenant(self):
|
||||
config = make_config(ENVIRONMENT=Environment.TESTING, DEFAULT_USER="bob")
|
||||
assert config.effective_default_user == TEST_TENANT
|
||||
assert config.tenant_forced is True
|
||||
|
||||
def test_testing_with_production_tenant_refuses_startup(self):
|
||||
with pytest.raises(ValidationError, match="Refusing to start"):
|
||||
make_config(
|
||||
ENVIRONMENT=Environment.TESTING,
|
||||
DEFAULT_USER=PRODUCTION_TENANT,
|
||||
)
|
||||
|
||||
def test_testing_with_test_prefixed_override_is_kept(self):
|
||||
config = make_config(ENVIRONMENT=Environment.TESTING, DEFAULT_USER="test_ci_run")
|
||||
assert config.effective_default_user == "test_ci_run"
|
||||
|
||||
# --- production ---
|
||||
|
||||
def test_prod_without_default_user_uses_production_tenant(self):
|
||||
config = make_config(ENVIRONMENT=Environment.PRODUCTION)
|
||||
assert config.effective_default_user == PRODUCTION_TENANT
|
||||
assert config.tenant_forced is False
|
||||
|
||||
def test_prod_with_explicit_production_tenant_is_kept(self):
|
||||
config = make_config(ENVIRONMENT=Environment.PRODUCTION, DEFAULT_USER=PRODUCTION_TENANT)
|
||||
assert config.effective_default_user == PRODUCTION_TENANT
|
||||
|
||||
def test_prod_with_explicit_other_user_is_kept(self):
|
||||
config = make_config(ENVIRONMENT=Environment.PRODUCTION, DEFAULT_USER="household_guest")
|
||||
assert config.effective_default_user == "household_guest"
|
||||
assert config.tenant_forced is False
|
||||
|
||||
|
||||
@pytest.mark.unit
|
||||
class TestRequestContextGuard:
|
||||
"""Request-context resolution guard: get_user() per environment."""
|
||||
|
||||
def _patch_environment(self, monkeypatch, environment: Environment):
|
||||
from src.core import config as config_module
|
||||
|
||||
monkeypatch.setattr(config_module.config, "ENVIRONMENT", environment)
|
||||
|
||||
def test_dev_default_resolution_is_test_tenant(self, monkeypatch):
|
||||
self._patch_environment(monkeypatch, Environment.DEVELOPMENT)
|
||||
assert get_user() == TEST_TENANT
|
||||
|
||||
def test_dev_explicit_production_tenant_is_forced(self, monkeypatch):
|
||||
self._patch_environment(monkeypatch, Environment.DEVELOPMENT)
|
||||
with RequestContext(user=PRODUCTION_TENANT):
|
||||
assert get_user() == TEST_TENANT
|
||||
|
||||
def test_testing_explicit_production_tenant_is_forced(self, monkeypatch):
|
||||
self._patch_environment(monkeypatch, Environment.TESTING)
|
||||
with RequestContext(user=PRODUCTION_TENANT):
|
||||
assert get_user() == TEST_TENANT
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
"variant",
|
||||
[
|
||||
"JPMSchweitzer",
|
||||
"JPMSCHWEITZER",
|
||||
"jpmschweitzer.",
|
||||
" jpmschweitzer",
|
||||
"jpmschweitzer ",
|
||||
"_jpmschweitzer_",
|
||||
"jpmschweitzer!",
|
||||
],
|
||||
)
|
||||
@pytest.mark.parametrize(
|
||||
"environment", [Environment.DEVELOPMENT, Environment.TESTING]
|
||||
)
|
||||
def test_production_tenant_sanitization_variants_are_forced(
|
||||
self, monkeypatch, environment, variant
|
||||
):
|
||||
"""
|
||||
Any raw user that sanitizes to the production tenant would resolve
|
||||
to the production namespaces (memories_jpmschweitzer,
|
||||
session:jpmschweitzer:*) - the guard must force it to the test
|
||||
tenant in non-production environments.
|
||||
"""
|
||||
from src.core.multi_tenancy import get_memory_collection_name
|
||||
|
||||
self._patch_environment(monkeypatch, environment)
|
||||
with RequestContext(user=variant):
|
||||
effective = get_user()
|
||||
assert effective == TEST_TENANT
|
||||
assert (
|
||||
get_memory_collection_name(effective)
|
||||
!= get_memory_collection_name(PRODUCTION_TENANT)
|
||||
)
|
||||
|
||||
def test_dev_non_colliding_user_is_not_forced(self, monkeypatch):
|
||||
"""A user that sanitizes to a different namespace passes through."""
|
||||
self._patch_environment(monkeypatch, Environment.DEVELOPMENT)
|
||||
with RequestContext(user="jpm.schweitzer"):
|
||||
# sanitizes to jpm_schweitzer != jpmschweitzer
|
||||
assert get_user() == "jpm.schweitzer"
|
||||
|
||||
def test_dev_explicit_other_user_passes_through(self, monkeypatch):
|
||||
self._patch_environment(monkeypatch, Environment.DEVELOPMENT)
|
||||
with RequestContext(user="testuser"):
|
||||
assert get_user() == "testuser"
|
||||
|
||||
def test_prod_explicit_production_tenant_passes_through(self, monkeypatch):
|
||||
self._patch_environment(monkeypatch, Environment.PRODUCTION)
|
||||
with RequestContext(user=PRODUCTION_TENANT):
|
||||
assert get_user() == PRODUCTION_TENANT
|
||||
|
||||
def test_prod_explicit_other_user_passes_through(self, monkeypatch):
|
||||
self._patch_environment(monkeypatch, Environment.PRODUCTION)
|
||||
with RequestContext(user="alice"):
|
||||
assert get_user() == "alice"
|
||||
|
||||
|
||||
@pytest.mark.unit
|
||||
class TestSuiteRunsUnderTestTenant:
|
||||
"""
|
||||
The live test session itself must resolve to the test tenant.
|
||||
|
||||
The session guard in tests/conftest.py hard-fails the suite when the
|
||||
effective tenant is the production tenant; these tests assert the
|
||||
namespaces every shared-service touch would use (Qdrant memories
|
||||
collection, Redis session keys) are the llm_tester ones.
|
||||
"""
|
||||
|
||||
def test_effective_tenant_is_not_production(self):
|
||||
from src.core.context import get_default_user
|
||||
|
||||
assert get_default_user() != PRODUCTION_TENANT
|
||||
|
||||
def test_effective_tenant_is_the_reserved_test_tenant(self):
|
||||
from src.core.context import get_default_user
|
||||
|
||||
assert get_default_user() == TEST_TENANT
|
||||
|
||||
def test_memories_collection_namespace_is_test_tenant(self):
|
||||
from src.core.context import get_default_user
|
||||
from src.core.multi_tenancy import get_memory_collection_name
|
||||
|
||||
assert (
|
||||
get_memory_collection_name(get_default_user())
|
||||
== f"memories_{TEST_TENANT}"
|
||||
)
|
||||
|
||||
def test_redis_session_namespace_is_test_tenant(self):
|
||||
from src.core.context import get_default_user
|
||||
from src.core.multi_tenancy import get_session_key
|
||||
|
||||
key = get_session_key(get_default_user(), "conv_test")
|
||||
assert key.startswith(f"session:{TEST_TENANT}:")
|
||||
|
||||
|
||||
@pytest.mark.unit
|
||||
class TestStartupTenantGuardLog:
|
||||
"""One loud startup log line states the effective tenant."""
|
||||
|
||||
def test_non_production_logs_forced_tenant(self, monkeypatch):
|
||||
from src.core import startup as startup_module
|
||||
|
||||
events = []
|
||||
|
||||
class _Recorder:
|
||||
def warning(self, event, **kw):
|
||||
events.append((event, kw))
|
||||
|
||||
def info(self, event, **kw):
|
||||
events.append((event, kw))
|
||||
|
||||
monkeypatch.setattr(startup_module, "logger", _Recorder())
|
||||
monkeypatch.setattr(startup_module.config, "ENVIRONMENT", Environment.DEVELOPMENT)
|
||||
|
||||
startup_module.log_tenant_guard()
|
||||
|
||||
assert events == [
|
||||
(
|
||||
"tenant_guard_active",
|
||||
{
|
||||
"environment": "development",
|
||||
"forced_tenant": TEST_TENANT,
|
||||
"default_user_overridden": startup_module.config.tenant_forced,
|
||||
"configured_default_user": startup_module.config.DEFAULT_USER,
|
||||
},
|
||||
)
|
||||
]
|
||||
|
||||
def test_production_logs_production_tenant(self, monkeypatch):
|
||||
from src.core import startup as startup_module
|
||||
|
||||
events = []
|
||||
|
||||
class _Recorder:
|
||||
def warning(self, event, **kw):
|
||||
events.append(("warning", event, kw))
|
||||
|
||||
def info(self, event, **kw):
|
||||
events.append(("info", event, kw))
|
||||
|
||||
monkeypatch.setattr(startup_module, "logger", _Recorder())
|
||||
monkeypatch.setattr(startup_module.config, "ENVIRONMENT", Environment.PRODUCTION)
|
||||
|
||||
startup_module.log_tenant_guard()
|
||||
|
||||
assert events == [
|
||||
(
|
||||
"info",
|
||||
"tenant_guard_production",
|
||||
{"environment": "production", "tenant": PRODUCTION_TENANT},
|
||||
)
|
||||
]
|
||||
@@ -3,8 +3,6 @@ Tests for tool call tracking.
|
||||
|
||||
Tests capability extraction and recommendation matching.
|
||||
"""
|
||||
from unittest.mock import AsyncMock, patch
|
||||
|
||||
import pytest
|
||||
|
||||
from src.core.tool_tracking import ToolCallTracker
|
||||
@@ -35,15 +33,11 @@ class TestToolCallTracker:
|
||||
recommended_capabilities=["librarian", "biographer"]
|
||||
)
|
||||
|
||||
with patch("src.core.tool_tracking.get_benchmark_store") as mock_store:
|
||||
mock_store.return_value.record = AsyncMock()
|
||||
|
||||
await tracker.track_call("delegate_to_librarian", 1.0)
|
||||
|
||||
# Should NOT log warning since librarian was recommended
|
||||
call_args = mock_store.return_value.record.call_args
|
||||
benchmark = call_args[0][0]
|
||||
assert benchmark.was_recommended is True
|
||||
# Should record the call
|
||||
assert "delegate_to_librarian" in tracker.actual_calls
|
||||
assert tracker.actual_calls["delegate_to_librarian"] == [1.0]
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_track_call_detects_not_recommended(self):
|
||||
@@ -52,14 +46,12 @@ class TestToolCallTracker:
|
||||
recommended_capabilities=["librarian"]
|
||||
)
|
||||
|
||||
with patch("src.core.tool_tracking.get_benchmark_store") as mock_store:
|
||||
mock_store.return_value.record = AsyncMock()
|
||||
|
||||
await tracker.track_call("delegate_to_housekeeper", 1.0)
|
||||
|
||||
call_args = mock_store.return_value.record.call_args
|
||||
benchmark = call_args[0][0]
|
||||
assert benchmark.was_recommended is False
|
||||
# Should record the call even though not recommended
|
||||
assert "delegate_to_housekeeper" in tracker.actual_calls
|
||||
summary = tracker.get_summary()
|
||||
assert summary["accuracy"]["not_recommended_but_used"] == 1
|
||||
|
||||
def test_get_summary_with_delegation_tools(self):
|
||||
"""Test summary correctly maps delegation tools to capabilities."""
|
||||
@@ -87,15 +79,9 @@ class TestToolCallTracker:
|
||||
"delegate_to_librarian": [1.0],
|
||||
}
|
||||
|
||||
with patch("src.core.tool_tracking.get_benchmark_store") as mock_store:
|
||||
mock_store.return_value.record = AsyncMock()
|
||||
|
||||
await tracker.finalize()
|
||||
|
||||
# Should record benchmark for unused biographer
|
||||
assert mock_store.return_value.record.called
|
||||
call_args = mock_store.return_value.record.call_args
|
||||
benchmark = call_args[0][0]
|
||||
assert benchmark.tool_name == "biographer"
|
||||
assert benchmark.was_recommended is True
|
||||
assert benchmark.was_actually_used is False
|
||||
# Summary should show biographer as recommended but unused
|
||||
summary = tracker.get_summary()
|
||||
assert summary["accuracy"]["recommended_and_used"] == 1 # librarian
|
||||
assert summary["accuracy"]["recommended_but_unused"] == 1 # biographer
|
||||
|
||||
+5
-5
@@ -4,8 +4,8 @@ These tests make real HTTP requests to the running Tatlock API server to verify
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. **Server must be running** on `http://localhost:8777` (use `./wakeup.sh`)
|
||||
2. **Ollama must be running** with `mistral-nemo:latest` model
|
||||
1. **Server must be running** on `http://localhost:8777` (use `make run`)
|
||||
2. **Ollama must be running** with the `gemma4:e2b` model
|
||||
3. **Redis must be running** (for benchmarking)
|
||||
4. **Qdrant must be running** on `http://localhost:6333` (for memory tests)
|
||||
|
||||
@@ -15,9 +15,9 @@ These tests make real HTTP requests to the running Tatlock API server to verify
|
||||
|
||||
```bash
|
||||
# Terminal 1: Start the server (auto-reload enabled)
|
||||
./wakeup.sh
|
||||
make run
|
||||
|
||||
# Logs are written to logs/server.log - tail them in another terminal:
|
||||
# Logs are written to build/logs/server.log - tail them in another terminal:
|
||||
tail -f logs/server.log
|
||||
```
|
||||
|
||||
@@ -132,7 +132,7 @@ memory = await qdrant.find_memory_by_key("memories_llm_tester", "favorite_color"
|
||||
|
||||
Make sure the server is running:
|
||||
```bash
|
||||
./wakeup.sh
|
||||
make run
|
||||
curl http://localhost:8777/health # Should return 200
|
||||
```
|
||||
|
||||
|
||||
@@ -11,9 +11,9 @@ These tests hit the actual running server and verify data persistence.
|
||||
They use the `llm_tester` user for isolation from production data.
|
||||
|
||||
Requirements:
|
||||
- Server running on localhost:8777 (use ./wakeup.sh)
|
||||
- Server running on localhost:8777 (use `make run`)
|
||||
- Qdrant running on localhost:6333
|
||||
- Ollama running with mistral-nemo model
|
||||
- Ollama running with the gemma4:e2b model
|
||||
|
||||
Note: LLM outputs are non-deterministic. Tests use flexible assertions
|
||||
that check for behavioral patterns rather than exact text matches.
|
||||
@@ -26,12 +26,18 @@ from typing import AsyncGenerator
|
||||
from dataclasses import dataclass
|
||||
|
||||
|
||||
from src.core.config import PRODUCTION_TENANT, TEST_TENANT
|
||||
|
||||
# Test configuration
|
||||
BASE_URL = "http://localhost:8777"
|
||||
QDRANT_URL = "http://localhost:6333"
|
||||
API_TIMEOUT = 120.0 # LLM calls can be slow
|
||||
TEST_USER = "llm_tester"
|
||||
# All e2e writes to shared services go to the reserved test tenant's
|
||||
# namespaces (Qdrant memories_llm_tester, wiki llm_tester scope) - never
|
||||
# the production tenant's.
|
||||
TEST_USER = TEST_TENANT
|
||||
TEST_COLLECTION = f"memories_{TEST_USER}"
|
||||
assert TEST_USER != PRODUCTION_TENANT
|
||||
|
||||
|
||||
@dataclass
|
||||
@@ -986,7 +992,7 @@ class TestUserContextIsolation:
|
||||
in_test_collection = any(unique_value in v for v in test_values)
|
||||
|
||||
# Check production collection (should NOT be there)
|
||||
prod_collection = "memories_jpmschweitzer"
|
||||
prod_collection = f"memories_{PRODUCTION_TENANT}"
|
||||
if await qdrant.collection_exists(prod_collection):
|
||||
prod_points = await qdrant.scroll_points(prod_collection)
|
||||
prod_values = [str(p.get("payload", {})) for p in prod_points]
|
||||
|
||||
@@ -0,0 +1,54 @@
|
||||
"""
|
||||
Tests for TatlockOllamaProvider configuration.
|
||||
|
||||
The AsyncOpenAI client must carry an explicit timeout from
|
||||
config.OLLAMA_TIMEOUT instead of the SDK default (~600s), so a stuck
|
||||
LLM call cannot consume the whole delegation budget.
|
||||
"""
|
||||
|
||||
import pytest
|
||||
|
||||
from src.core.config import config
|
||||
from src.ollama.provider import TatlockOllamaProvider, _sanitize_messages
|
||||
|
||||
|
||||
@pytest.mark.unit
|
||||
class TestProviderTimeout:
|
||||
"""Timeout configuration on the underlying AsyncOpenAI client."""
|
||||
|
||||
def test_openai_client_timeout_from_config(self):
|
||||
provider = TatlockOllamaProvider(base_url="http://localhost:11434/v1")
|
||||
|
||||
assert provider._openai_client.timeout == float(config.OLLAMA_TIMEOUT)
|
||||
|
||||
def test_timeout_is_not_sdk_default(self):
|
||||
provider = TatlockOllamaProvider(base_url="http://localhost:11434/v1")
|
||||
|
||||
# The OpenAI SDK defaults to 600s; the configured cap must win
|
||||
assert provider._openai_client.timeout < 600
|
||||
|
||||
|
||||
@pytest.mark.unit
|
||||
class TestMessageSanitization:
|
||||
"""Null content sanitization for Ollama compatibility."""
|
||||
|
||||
def test_null_content_with_tool_calls_becomes_empty_string(self):
|
||||
messages = [
|
||||
{
|
||||
"role": "assistant",
|
||||
"content": None,
|
||||
"tool_calls": [{"id": "call_1", "type": "function"}],
|
||||
}
|
||||
]
|
||||
|
||||
sanitized = _sanitize_messages(messages)
|
||||
|
||||
assert sanitized[0]["content"] == ""
|
||||
|
||||
def test_regular_messages_unchanged(self):
|
||||
messages = [
|
||||
{"role": "user", "content": "Hello"},
|
||||
{"role": "assistant", "content": "Good day, sir."},
|
||||
]
|
||||
|
||||
assert _sanitize_messages(messages) == messages
|
||||
@@ -0,0 +1,185 @@
|
||||
"""
|
||||
Tests for real-time think message streaming and context plumbing in
|
||||
the direct delegation paths.
|
||||
|
||||
_stream_direct_delegation must be an async generator that yields the
|
||||
"start" think message BEFORE the expert runs (so 'Allow me to consult
|
||||
the archives, sir.' streams while research is in flight), and both
|
||||
direct delegation paths must pass trimmed conversation history as
|
||||
expert context.
|
||||
"""
|
||||
|
||||
from types import SimpleNamespace
|
||||
from unittest.mock import AsyncMock, patch
|
||||
|
||||
import pytest
|
||||
|
||||
from src.agents.delegation import DelegationResult
|
||||
from src.responses.streaming import (
|
||||
ReasoningSummaryDelta,
|
||||
ReasoningSummaryDone,
|
||||
StreamingCoordinator,
|
||||
)
|
||||
|
||||
HISTORY = [
|
||||
{"role": "user", "content": "Tell me about my homelab wiki"},
|
||||
{"role": "assistant", "content": "It documents your services, sir."},
|
||||
]
|
||||
|
||||
|
||||
def _librarian_result(output: str = "Findings.") -> DelegationResult:
|
||||
return DelegationResult(
|
||||
expert_name="librarian",
|
||||
task="task",
|
||||
success=True,
|
||||
output=output,
|
||||
)
|
||||
|
||||
|
||||
@pytest.mark.unit
|
||||
class TestStreamDirectDelegation:
|
||||
"""Real-time streaming behavior of _stream_direct_delegation."""
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_start_think_streams_before_research_runs(self):
|
||||
coordinator = StreamingCoordinator()
|
||||
tracker = AsyncMock()
|
||||
results: dict = {}
|
||||
|
||||
with patch(
|
||||
"src.agents.delegation.delegate_to_librarian",
|
||||
new_callable=AsyncMock,
|
||||
return_value=_librarian_result(),
|
||||
) as mock_delegate:
|
||||
gen = coordinator._stream_direct_delegation(
|
||||
user_message="Search for Docker info",
|
||||
recommendation=SimpleNamespace(
|
||||
recommended_capabilities=["librarian"]
|
||||
),
|
||||
tracker=tracker,
|
||||
conversation_id="conv_1",
|
||||
conversation_history=HISTORY,
|
||||
results=results,
|
||||
)
|
||||
|
||||
# First event: the start think message, BEFORE any research
|
||||
first = await gen.__anext__()
|
||||
assert isinstance(first, ReasoningSummaryDelta)
|
||||
assert first.delta.strip() != ""
|
||||
assert mock_delegate.await_count == 0, (
|
||||
"start think message must stream before the expert runs"
|
||||
)
|
||||
|
||||
second = await gen.__anext__()
|
||||
assert isinstance(second, ReasoningSummaryDone)
|
||||
assert mock_delegate.await_count == 0
|
||||
|
||||
# Third event: completion message - research has now run
|
||||
third = await gen.__anext__()
|
||||
assert isinstance(third, ReasoningSummaryDelta)
|
||||
assert mock_delegate.await_count == 1
|
||||
|
||||
remaining = [event async for event in gen]
|
||||
assert any(isinstance(e, ReasoningSummaryDone) for e in remaining)
|
||||
|
||||
# Results dict is populated for Phase 2 synthesis
|
||||
assert results["expert_results"] == {"librarian": "Findings."}
|
||||
assert results["tools_called"] == ["delegate_to_librarian"]
|
||||
assert len(results["think_messages"]) == 2
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_conversation_history_passed_as_context(self):
|
||||
coordinator = StreamingCoordinator()
|
||||
tracker = AsyncMock()
|
||||
|
||||
with patch(
|
||||
"src.agents.delegation.delegate_to_librarian",
|
||||
new_callable=AsyncMock,
|
||||
return_value=_librarian_result(),
|
||||
) as mock_delegate:
|
||||
events = [
|
||||
event
|
||||
async for event in coordinator._stream_direct_delegation(
|
||||
user_message="And what services does it list?",
|
||||
recommendation=SimpleNamespace(
|
||||
recommended_capabilities=["librarian"]
|
||||
),
|
||||
tracker=tracker,
|
||||
conversation_id="conv_1",
|
||||
conversation_history=HISTORY,
|
||||
results={},
|
||||
)
|
||||
]
|
||||
|
||||
assert events, "generator must yield think events"
|
||||
context = mock_delegate.await_args.kwargs["context"]
|
||||
assert "Tell me about my homelab wiki" in context
|
||||
assert "It documents your services, sir." in context
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_failed_delegation_streams_error_think(self):
|
||||
coordinator = StreamingCoordinator()
|
||||
tracker = AsyncMock()
|
||||
results: dict = {}
|
||||
|
||||
failed = DelegationResult(
|
||||
expert_name="librarian",
|
||||
task="task",
|
||||
success=False,
|
||||
output="I'm afraid the archives proved difficult to access.",
|
||||
error="The Librarian was unable to complete the task.",
|
||||
)
|
||||
|
||||
with patch(
|
||||
"src.agents.delegation.delegate_to_librarian",
|
||||
new_callable=AsyncMock,
|
||||
return_value=failed,
|
||||
):
|
||||
events = [
|
||||
event
|
||||
async for event in coordinator._stream_direct_delegation(
|
||||
user_message="Search for Docker info",
|
||||
recommendation=SimpleNamespace(
|
||||
recommended_capabilities=["librarian"]
|
||||
),
|
||||
tracker=tracker,
|
||||
conversation_id="conv_1",
|
||||
results=results,
|
||||
)
|
||||
]
|
||||
|
||||
assert results["tools_called"] == []
|
||||
# Expert result carries the curated user-safe sentence
|
||||
assert "archives" in results["expert_results"]["librarian"]
|
||||
deltas = [e.delta for e in events if isinstance(e, ReasoningSummaryDelta)]
|
||||
assert len(deltas) == 2 # start + error think messages
|
||||
|
||||
|
||||
@pytest.mark.unit
|
||||
class TestServiceDelegationContext:
|
||||
"""The non-streaming direct delegation path passes trimmed history."""
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_direct_delegation_with_results_passes_context(self):
|
||||
from src.responses.service import _direct_delegation_with_results
|
||||
|
||||
tracker = AsyncMock()
|
||||
|
||||
with patch(
|
||||
"src.agents.delegation.delegate_to_librarian",
|
||||
new_callable=AsyncMock,
|
||||
return_value=_librarian_result(),
|
||||
) as mock_delegate:
|
||||
results = await _direct_delegation_with_results(
|
||||
user_message="And what services does it list?",
|
||||
recommendation=SimpleNamespace(
|
||||
recommended_capabilities=["librarian"]
|
||||
),
|
||||
tracker=tracker,
|
||||
conversation_id="conv_1",
|
||||
conversation_history=HISTORY,
|
||||
)
|
||||
|
||||
context = mock_delegate.await_args.kwargs["context"]
|
||||
assert "Tell me about my homelab wiki" in context
|
||||
assert results["expert_results"]["librarian"] == "Findings."
|
||||
@@ -1,50 +0,0 @@
|
||||
|
||||
|
||||
#!/bin/bash
|
||||
# Tatlock Server Startup Script
|
||||
|
||||
set -e
|
||||
|
||||
# Colors for output
|
||||
GREEN='\033[0;32m'
|
||||
YELLOW='\033[1;33m'
|
||||
RED='\033[0;31m'
|
||||
NC='\033[0m' # No Color
|
||||
|
||||
echo -e "${GREEN}Starting Tatlock server...${NC}"
|
||||
|
||||
# Check if port 8777 is already in use
|
||||
if lsof -Pi :8777 -sTCP:LISTEN -t >/dev/null 2>&1 ; then
|
||||
echo -e "${RED}Error: Port 8777 is already in use${NC}"
|
||||
echo "Run: lsof -i :8777 to see what's using it"
|
||||
echo "Or run: kill \$(lsof -t -i:8777) to stop it"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Activate virtual environment if not already activated
|
||||
if [ -z "$VIRTUAL_ENV" ]; then
|
||||
if [ -d ".venv" ]; then
|
||||
echo -e "${YELLOW}Activating virtual environment...${NC}"
|
||||
source .venv/bin/activate
|
||||
else
|
||||
echo -e "${RED}Error: Virtual environment not found${NC}"
|
||||
echo "Run: python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt"
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
|
||||
# Create logs directory if it doesn't exist
|
||||
LOGS_DIR="logs"
|
||||
mkdir -p "$LOGS_DIR"
|
||||
|
||||
# Clear/create log file
|
||||
LOG_FILE="$LOGS_DIR/server.log"
|
||||
> "$LOG_FILE"
|
||||
echo -e "${YELLOW}Logs will be written to: ${LOG_FILE}${NC}"
|
||||
|
||||
# Start the server
|
||||
echo -e "${GREEN}Starting uvicorn server on http://tower-of-joy:8777${NC}"
|
||||
echo -e "${YELLOW}Press Ctrl+C to stop the server${NC}"
|
||||
echo ""
|
||||
|
||||
uvicorn src.main:app --reload --host 0.0.0.0 --port 8777 2>&1 | tee "$LOG_FILE"
|
||||
Reference in New Issue
Block a user