Skip to content

README.md

Latest commit

 

History

History
112 lines (77 loc) · 4.15 KB

README.md

File metadata and controls

112 lines (77 loc) · 4.15 KB

debriefer (Python client)

Async Python HTTP client for the debriefer multi-source research orchestration server.

Install

Not yet published to PyPI. Install from source:

cd clients/python && pip install -e ".[dev]"

Requirements: Python >= 3.10, httpx >= 0.27, pydantic >= 2

Quick start

import asyncio
from debriefer import AsyncDebriefer

async def main():
    async with AsyncDebriefer("http://localhost:8090") as client:
        # Check server health
        health = await client.health()
        print(health.status, health.version)

        # List available sources
        sources = await client.list_sources()
        print(f"{len(sources)} sources available")

        # Research a subject
        result = await client.debrief("John Wayne")
        print(f"Found {len(result.findings)} findings")
        print(f"Total cost: ${result.total_cost_usd:.4f}")
        if result.synthesis_result:
            print(result.synthesis_result.data)

asyncio.run(main())

Auth

When the server is started with DEBRIEFER_API_KEYS set, pass the key as api_key:

client = AsyncDebriefer("https://your-server.example.com", api_key="your-key")

The key is sent as a Bearer token in the Authorization header.

Methods

debrief(name, *, categories, budget, synthesis, model, prompt)

Run single-subject research across multiple sources. Returns a DebriefResult.

Parameter Type Description
name str Subject name to research (required)
categories list[str] Source categories to use (optional)
budget float Per-subject budget in USD (optional)
synthesis bool Whether to run AI synthesis (optional)
model str AI model for synthesis (optional)
prompt str Custom system prompt for synthesis (optional)

list_sources(*, category)

List available research sources. Accepts an optional category filter ("structured", "news", "search", "books", "archives", "obituary"). Returns list[Source].

health()

Check server health. Returns HealthStatus.

Models

Model Key fields
DebriefResult subject, findings, synthesis_result, total_cost_usd, sources_attempted, duration_ms
Finding text, url, confidence, source_type, source_name, reliability_tier, reliability_score
SynthesisResult data, cost_usd, input_tokens, output_tokens, model
Source name, type, category, reliability_tier, reliability_score, is_free, available
HealthStatus status, version, uptime

All models use Pydantic v2 and accept both camelCase (server JSON) and snake_case field names.

Exceptions

Exception When raised Key attributes
DebrieferAPIError Server returns a 4xx or 5xx response status_code, message, details
DebrieferConnectionError Client cannot reach the server —

Both inherit from DebrieferError.

from debriefer.exceptions import DebrieferAPIError, DebrieferConnectionError

try:
    result = await client.debrief("Jane Doe")
except DebrieferAPIError as e:
    print(f"API error {e.status_code}: {e.message}")
except DebrieferConnectionError:
    print("Server unreachable")

Docs

Full documentation lives in the debriefer monorepo.

License

MIT