r3fresh

API Reference

ALM Class

The main entry point for the r3fresh ALM SDK. Manages event collection, policy enforcement, run tracking, and version management.

__init__(...)

Initialize an ALM instance.

  • agent_id (str, required) – Unique agent identifier
  • env (str, default="development") – Environment name
  • mode (str, default="stdout") – "stdout" or "http"
  • endpoint (str, optional) – Base URL for HTTP mode; SDK POSTs to /v1/events
  • api_key (str, optional) – Sent as Authorization: Bearer <api_key>
  • agent_version (str, optional) – Agent version string
  • policy_version (str, optional) – Policy version string
  • allowed_tools (Set[str], optional) – Whitelist of allowed tools
  • denied_tools (Set[str], optional) – Blacklist of denied tools
  • default_allow (bool, default=True) – Allow tools by default
  • max_tool_calls_per_run (int, optional) – Maximum tool calls per run

run(purpose: Optional[str] = None) → Run

Create a run context manager. Returns a Run instance that tracks all events within the run.

tool(tool_name: Optional[str] = None)

Decorator factory for wrapping tool functions with automatic instrumentation and policy enforcement.

task(task_type: Optional[str] = None, description: Optional[str] = None) → TaskContext

Create a task context manager for tracking task execution.

handoff(to_agent_id: str, reason: Optional[str] = None, context: Optional[Dict] = None)

Emit a handoff event for agent-to-agent transitions.

flush()

Flush queued events to the configured sink (stdout or HTTP).

Testing

Run the test suite:

pytest

Run the example:

python examples/toy_agent.py