huggr-python

name	huggr-python
description	Define and run huglets in Python with typed contract objects, sync or async callable tools, streaming events, feedback, stats, and standard traces. Use for the huggr-agents Python runtime API, or when deciding between a Python-defined agent and a generated Python wheel from a Rust-defined agent.

Build Huggr agents with Python

Select the surface based on where the agent is defined:

• To define the system prompt, model config, and tools in Python, use the huggr-agents runtime API below.
• To consume an existing Rust-defined agent as a typed Python package, keep its definition in Rust and run huggr build <agent-dir> --surface python --release; follow Package an agent for Python.

Prepare the runtime package

From a Huggr checkout:

cd bindings/python
python3 -m venv .venv
. .venv/bin/activate
pip install maturin mypy pytest
maturin develop --release

Import the package as huggr_agents. It runs the native Rust runtime; the Python layer is a typed JSON boundary, not a second agent implementation.

Define tools and the agent

Annotate every parameter: the advertised JSON Schema is inferred from the type annotations (str/int/float/bool/list[...]/dict/Optional[...] or X | None; defaults become optional), the name from the function, the description from the docstring, and the model's arguments arrive as keyword arguments. Pass schema= to advertise a hand-written schema instead; the callable then receives the raw arguments dict as its single parameter. Both sync and async callables are supported; async callables run through asyncio.run on a blocking worker and cannot reuse objects bound to the caller's event loop. Exceptions become semantic tool errors returned to the model.

import huggr_agents as huggr

@huggr.tool
def lookup_policy(query: str) -> dict:
    """Search policy text by keyword."""
    return {"matches": search_policy_text(query)}

agent = huggr.Agent(
    name="policy-helper",
    system="Use lookup_policy, then return a JSON object with an answer field.",
    models={"default": "balanced"},
    tools=[lookup_policy],
    response_schema={
        "type": "object",
        "properties": {"answer": {"type": "string"}},
        "required": ["answer"],
    },
)

Use grants={"fs_read": {"root": "./docs"}} for vetted library grants. Keep Python callables privilege-minimal: they are trusted host code, so Huggr controls whether the model can invoke them but does not sandbox what their Python bodies do.

Ask, stream, resume, and inspect

answer = agent.ask("Can I expense a train ticket?")
follow_up = agent.ask("What receipt is needed?", trace_id=answer.trace_id)
agent.feedback(answer.trace_id, {"score": 5})
print(agent.traces())
print(agent.stats())

async def stream():
    async for event in agent.run("Can I expense a train ticket?"):
        if isinstance(event, huggr.TextDeltaEvent):
            print(event.text, end="")
        elif isinstance(event, huggr.AnswerReadyEvent):
            answer = event.answer

Agent.ask() and Agent.run() share the signal-aware native event bridge. Ctrl+C aborts a blocking ask, while task cancellation or iterator close aborts a stream. An in-process Python callable already executing on a blocking worker cannot be preempted safely and may finish after cancellation; keep its side effects idempotent or implement application-level cancellation. Runtime teardown does not wait for it. Generated wheels for Rust-defined agents expose module-level ask(...) and run(...) methods with the same parameters and event dataclasses; their successful Answer.response remains the generated Rust response-contract dataclass.

Fixed-shape inputs use the exported TypedDicts: TierConfig, ProviderConfig, ModelCatalogConfig, LimitsConfig, ContextConfig, GrantsConfig, and the individual grant configs. Model selectors are the fixed fast, balanced, powerful, and max tiers. The built-in catalog leaves max unset, so it falls back to powerful. Pass model_overrides={"providers": ..., "models": ...} for an explicit embedding-host catalog. Hugging Face Inference Providers lists provider and model combinations for the built-in hf provider. For another OpenAI-compatible service, give it a separate provider alias with its own base_url API URL and credential configuration.

Structured outputs are recursive dataclasses: Answer, every AgentEvent variant, AgentCard, TraceHead, Feedback, and AgentStats. Branch on answer.ok or answer.status. Turn failures are answers with mandatory metadata; answer.metadata.models lists effective model ids used by completed calls in first-use order. Configuration and infrastructure failures raise exceptions.

Use BlobHandle.from_path(...) and the blobs= ask argument for files. Opaque domain payloads remain JsonValue/JsonObject; validation stays in Rust and Python only casts.

State defaults to ~/.huggr/<name>/, shared with Rust and TypeScript surfaces.

Trace ids accepted from callers contain only ASCII letters, digits, -, and _. Malformed ids raise ValueError; valid ids that are absent from the store raise the surface's ordinary not-found error.

Validate

cd bindings/python
. .venv/bin/activate
pytest
mypy python/huggr_agents

Python-written traces use the standard format. When a manifest-defined agent directory with the same agent name resolves to that home, verify it with the Rust CLI:

huggr verify <matching-agent-dir> <trace-id>
huggr replay <matching-agent-dir> <trace-id> --step

Read Define an agent in Python for the full API. If native import fails, rerun maturin develop --release inside the active venv. If model auth fails, set the variable named by the resolved provider's api_key_env (HF_TOKEN for the built-in catalog). If a callable throws, fix the tool's input validation or implementation; do not turn a semantic error into a process crash.