Skip to content

architecture.md

Latest commit

 

History

History
120 lines (87 loc) · 3.23 KB

architecture.md

File metadata and controls

120 lines (87 loc) · 3.23 KB

🐍 hawk-sdk-python Architecture

Python SDK for the Hawk Daemon API

Python Type

🎯 Overview

Idiomatic Python client for the hawk daemon HTTP API. Provides both sync and async clients, SSE streaming, a tool decorator, agent abstraction, and workflow builder. Uses httpx for HTTP transport and Pydantic for response models.

🧱 Modules

src/hawk/
├── __init__.py          📤 Public exports
├── client.py            🔌 HawkClient (sync) + AsyncHawkClient (async)
├── types.py             📋 Pydantic models (ChatResponse, Session, Stats)
├── errors.py            ❌ HawkAPIError base + subclasses, parse_error()
├── retry.py             🔄 RetryConfig, with_retry_sync(), with_retry()
├── streaming.py         📡 StreamReader, AsyncStreamReader, StreamEvent
├── agent.py             🤖 Agent (conversation history, async support)
├── tools.py             🛠️ @tool() decorator, chat_with_tools()
├── workflow.py          🔧 Workflow builder
├── discovery.py         🔍 Auto-discover running hawk daemon on localhost
├── memory_tools.py      🧠 Memory graph operations (yaad integration)
├── evaluate.py          📊 Evaluation helpers
└── tracing.py           📈 OpenTelemetry tracing support

📤 Client Usage

from hawk import HawkClient, AsyncHawkClient

# 🔌 Sync client
with HawkClient(base_url="http://localhost:4590", api_key="sk-...") as client:
    health   = client.health()
    response = client.chat("list files in src/")
    print(response.response)

# 📡 Async client
async with AsyncHawkClient() as client:
    async for event in client.chat_stream("explain this code"):
        print(event.data, end="", flush=True)

# 📋 Sessions
sessions = client.list_sessions(limit=10)
msgs     = client.get_session_messages(session_id)
client.delete_session(session_id)

🛠️ Tool Decorator

from hawk import tool, HawkClient

@tool()
def read_file(path: str) -> str:
    with open(path) as f:
        return f.read()

with HawkClient() as client:
    response = client.chat_with_tools("read config.json", tools=[read_file])

🤖 Agent (Higher-Level)

from hawk import Agent

agent = Agent(base_url="http://localhost:4590")
resp1 = agent.chat("refactor this function")
resp2 = agent.chat("now add type hints")  # continues same session

❌ Error Handling

from hawk.errors import NotFoundError, RateLimitError

try:
    response = client.chat("...")
except RateLimitError as e:
    time.sleep(e.retry_after or 1)
except NotFoundError:
    ...
Error Class HTTP Status
NotFoundError 404
RateLimitError 429
InternalServerError 500

🔄 Retry & Streaming

Feature Behavior
Auto-retry 429, 500, 502, 503, 504 with exponential backoff + jitter
Retry-After: 0 Valid — don't retry immediately
Dual client Every method on both HawkClient and AsyncHawkClient