boundflow 0.1.0__py3-none-any.whl

boundflow/__init__.py

@@ -0,0 +1,88 @@
+"""BoundFlow Python SDK — governance for agentic workflows."""
+
+from .anthropic_client import AnthropicLlmClient
+from .control_plane import (
+    ControlPlaneClient,
+    ApprovalAuditRecord,
+    ApprovalDecision,
+    PolicyActionRecord,
+    WorkflowPolicyAction,
+    AgentPolicyActionRecord,
+    LifecycleState,
+    RequestInfo,
+    Run,
+    RunOutcome,
+    RunStatus,
+    Tenant,
+    TenantGroup,
+    Workflow,
+    WorkflowConfig,
+    WorkflowState,
+    WorkflowSummary,
+)
+from .errors import (
+    AlreadyExistsError,
+    BoundflowError,
+    DeadlineExceededError,
+    FailedPreconditionError,
+    InvalidArgumentError,
+    NotFoundError,
+    PermissionDeniedError,
+    UnauthenticatedError,
+    UnavailableError,
+)
+from .llm import MockLlmClient, MockContext, Turn, turn, submit
+from .trace import (
+    AgentRunTrace,
+    JsonlFileTraceSink,
+    LoggingTraceSink,
+    OperationTrace,
+    OTelTraceSink,
+    Span,
+    TraceSink,
+)
+from .policies import (
+    AgentMetric,
+    AgentRule,
+    Cooldown,
+    Op,
+    Pause,
+    RuntimePolicy,
+    SetMaxCostUsd,
+    SetMaxLlmCalls,
+    SetMaxTokensPerCall,
+    SetModel,
+    SetVersion,
+    ToolCallLimit,
+    WorkflowMetric,
+    WorkflowRule,
+)
+from .worker import (
+    AgentDefinition,
+    ApprovalRequest,
+    AwaitApproval,
+    BoundFlowWorker,
+    Complete,
+    Next,
+    OperationContext,
+    OperationResult,
+    Tool,
+    tool,
+)
+
+__all__ = [
+    "AnthropicLlmClient",
+    "ControlPlaneClient", "LifecycleState", "RunStatus", "RunOutcome", "Run", "RequestInfo",
+    "Tenant", "TenantGroup", "Workflow",
+    "WorkflowConfig", "WorkflowState", "WorkflowSummary", "ApprovalAuditRecord", "ApprovalDecision", "PolicyActionRecord", "WorkflowPolicyAction", "AgentPolicyActionRecord", "MockLlmClient", "MockContext", "Turn",
+    "turn", "submit", "AgentMetric", "AgentRule", "Cooldown", "Op", "Pause",
+    "RuntimePolicy", "SetMaxCostUsd", "SetMaxLlmCalls", "SetMaxTokensPerCall",
+    "SetModel", "SetVersion", "ToolCallLimit", "WorkflowMetric", "WorkflowRule",
+    "AgentDefinition", "ApprovalRequest", "AwaitApproval", "BoundFlowWorker",
+    "Complete", "Next", "OperationContext", "OperationResult", "Tool", "tool",
+    "AgentRunTrace", "OperationTrace", "Span", "TraceSink", "LoggingTraceSink",
+    "JsonlFileTraceSink", "OTelTraceSink",
+    "BoundflowError", "NotFoundError", "AlreadyExistsError", "InvalidArgumentError",
+    "FailedPreconditionError", "PermissionDeniedError", "UnauthenticatedError",
+    "UnavailableError", "DeadlineExceededError",
+]

boundflow/_transport.py

@@ -0,0 +1,213 @@
+"""gRPC transport — worker bidi stream + proto⇄domain conversion.
+
+Port of BoundFlow.SDK WorkerClient (the stream loop) and the MapToProto helpers
+in BoundFlowWorker, on top of grpc.aio. The server drives the session with
+Launch/Cancel commands; the worker acks IN_PROGRESS, runs the operation off the
+receive loop, then reports the result and re-arms with ReadyForWork.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import uuid
+from typing import Awaitable, Callable
+
+import grpc
+
+log = logging.getLogger("boundflow.worker")
+from google.protobuf import json_format
+from google.protobuf.struct_pb2 import Struct
+
+from boundflow.v1 import agent_policy_pb2 as ap_pb
+from boundflow.v1 import operation_pb2 as op_pb
+from boundflow.v1 import worker_pb2 as wk_pb
+from boundflow.v1 import worker_pb2_grpc as wk_grpc
+
+# dispatch: given the launched operation proto, produce the result proto.
+Dispatch = Callable[[op_pb.AtomicOperation], Awaitable[op_pb.AtomicOperationResult]]
+
+
+def _strip_scheme(addr: str) -> str:
+    return addr.split("://", 1)[1] if "://" in addr else addr
+
+
+def context_to_dict(op: op_pb.AtomicOperation) -> dict:
+    """AtomicOperation.context (Struct) → plain dict, camelCase top-level keys
+    (matching the .NET JsonFormatter), opaque policy contents preserved."""
+    if not op.HasField("context"):
+        return {}
+    return json_format.MessageToDict(op.context)
+
+
+def dict_to_struct(d: dict) -> Struct:
+    s = Struct()
+    s.update(d or {})
+    return s
+
+
+def new_approval_id() -> str:
+    return str(uuid.uuid4())
+
+
+def metrics_to_proto(snapshot: dict) -> op_pb.AgentInvocationMetrics:
+    m = op_pb.AgentInvocationMetrics(
+        cost_usd=snapshot.get("cost_usd", 0.0),
+        llm_calls=snapshot.get("llm_calls", 0),
+        tokens_used=snapshot.get("tokens_used", 0),
+        ran_at=snapshot.get("ran_at", 0),
+    )
+    for tool, count in (snapshot.get("calls_per_tool") or {}).items():
+        m.calls_per_tool[tool] = count
+    for tool, count in (snapshot.get("tool_failure_counts") or {}).items():
+        m.tool_failure_counts[tool] = count
+    return m
+
+
+_AGENT_METRIC_PB = {
+    "tokens_used": ap_pb.AGENT_METRIC_TOKENS_USED,
+    "cost_usd": ap_pb.AGENT_METRIC_COST_USD,
+    "llm_calls": ap_pb.AGENT_METRIC_LLM_CALLS,
+    "calls_per_tool": ap_pb.AGENT_METRIC_CALLS_PER_TOOL,
+}
+_AGENT_OP_PB = {
+    "less_than": ap_pb.AGENT_OP_LT,
+    "less_than_or_equal": ap_pb.AGENT_OP_LTE,
+    "greater_than": ap_pb.AGENT_OP_GT,
+    "greater_than_or_equal": ap_pb.AGENT_OP_GTE,
+    "equal": ap_pb.AGENT_OP_EQ,
+}
+
+
+def _enum_value(v) -> str:
+    return getattr(v, "value", v)
+
+
+def _runtime_policy_to_proto(p) -> ap_pb.AgentRuntimePolicy:
+    return ap_pb.AgentRuntimePolicy(
+        model=p.model or "",
+        max_llm_calls=p.max_llm_calls,
+        max_cost_usd=p.max_cost_usd,
+        max_tokens_per_call=p.max_tokens_per_call,
+        tool_call_limits=[ap_pb.ToolCallLimit(tool=l.tool, max_calls=l.max_calls) for l in p.tool_call_limits],
+    )
+
+
+def _agent_action_to_proto(action) -> ap_pb.AgentRuleAction:
+    field = action.field
+    if field == "model":
+        return ap_pb.AgentRuleAction(field=ap_pb.AGENT_RULE_ACTION_SET_MODEL, model=action.value)
+    if field == "max_llm_calls":
+        return ap_pb.AgentRuleAction(field=ap_pb.AGENT_RULE_ACTION_SET_MAX_LLM_CALLS, max_llm_calls=action.value)
+    if field == "max_cost_usd":
+        return ap_pb.AgentRuleAction(field=ap_pb.AGENT_RULE_ACTION_SET_MAX_COST_USD, max_cost_usd=action.value)
+    if field == "max_tokens_per_call":
+        return ap_pb.AgentRuleAction(field=ap_pb.AGENT_RULE_ACTION_SET_MAX_TOKENS_PER_CALL, max_tokens_per_call=action.value)
+    return ap_pb.AgentRuleAction()
+
+
+def _agent_rule_to_proto(rule) -> ap_pb.AgentRule:
+    return ap_pb.AgentRule(
+        metric=_AGENT_METRIC_PB.get(_enum_value(rule.metric), ap_pb.AGENT_METRIC_UNSPECIFIED),
+        op=_AGENT_OP_PB.get(_enum_value(rule.op), ap_pb.AGENT_OP_UNSPECIFIED),
+        threshold=rule.threshold,
+        window=rule.window,
+        tool=rule.tool or "",
+        action=_agent_action_to_proto(rule.action),
+    )
+
+
+def agent_policy_action_to_proto(action: dict) -> ap_pb.AgentPolicyAction:
+    """Map the SDK-side agent policy action ({base_policy, effective_policy,
+    fired_rules:[(rule, value)]}) to the typed proto for the operation result."""
+    return ap_pb.AgentPolicyAction(
+        base_policy=_runtime_policy_to_proto(action["base_policy"]),
+        effective_policy=_runtime_policy_to_proto(action["effective_policy"]),
+        fired_rules=[
+            ap_pb.FiredAgentRule(rule=_agent_rule_to_proto(rule), trigger_value=float(value))
+            for (rule, value) in action["fired_rules"]
+        ],
+    )
+
+
+class WorkerSession:
+    """Owns the bidi stream and dispatch loop. One operation in flight at a time."""
+
+    def __init__(self, address: str, api_key: str, capabilities: list[tuple[str, int]] | None = None) -> None:
+        self._target = _strip_scheme(address)
+        self._secure = address.startswith("https://")
+        self._session_id = str(uuid.uuid4())
+        self._write_lock = asyncio.Lock()
+        self._metadata = (("x-api-key", api_key),)
+        self._capabilities = [
+            wk_pb.WorkerCapability(workflow_type=rt, workflow_version=v)
+            for rt, v in (capabilities or [])
+        ]
+
+    async def run(self, dispatch: Dispatch) -> None:
+        if self._secure:
+            channel_ctx = grpc.aio.secure_channel(self._target, grpc.ssl_channel_credentials())
+        else:
+            channel_ctx = grpc.aio.insecure_channel(self._target)
+        async with channel_ctx as channel:
+            stub = wk_grpc.WorkerServiceStub(channel)
+            call = stub.WorkerSession(metadata=self._metadata)
+            await self._write(call, self._ready())
+
+            op_task: asyncio.Task | None = None
+            op_id: str | None = None
+
+            async for command in call:
+                which = command.WhichOneof("payload")
+                if which == "launch":
+                    op = command.launch.operation
+                    op_id = op.id
+                    log.debug("launch: op_id=%s workflow_type=%s name=%s version=%d",
+                              op.id, op.workflow_type, op.name, op.workflow_version)
+                    # Ack IN_PROGRESS before starting; keep the receive loop free.
+                    await self._write(call, self._update(op.id, op_pb.OPERATION_STATUS_IN_PROGRESS))
+                    op_task = asyncio.create_task(self._run_operation(call, op, dispatch))
+                elif which == "cancel":
+                    if op_task is not None and command.cancel.operation_id == op_id:
+                        op_task.cancel()
+                        try:
+                            await op_task
+                        except asyncio.CancelledError:
+                            await self._write(call, self._update(op_id, op_pb.OPERATION_STATUS_CANCELLED))
+                    op_task, op_id = None, None
+                    await self._write(call, self._ready())
+
+    async def _run_operation(self, call, op: op_pb.AtomicOperation, dispatch: Dispatch) -> None:
+        try:
+            result = await dispatch(op)
+        except asyncio.CancelledError:
+            raise  # surfaced to the main loop, which sends CANCELLED
+        except Exception as ex:  # noqa: BLE001 — report a handler failure
+            log.error("operation FAILED: op_id=%s error=%s", op.id, ex, exc_info=True)
+            await self._write(call, self._update(op.id, op_pb.OPERATION_STATUS_FAILED, str(ex)))
+            await self._write(call, self._ready())
+            return
+        await self._write(call, wk_pb.WorkerMessage(
+            session_id=self._session_id,
+            update=wk_pb.OperationUpdate(operation_id=op.id, result=result),
+        ))
+        await self._write(call, self._ready())
+
+    async def _write(self, call, msg: wk_pb.WorkerMessage) -> None:
+        async with self._write_lock:
+            await call.write(msg)
+
+    def _ready(self) -> wk_pb.WorkerMessage:
+        return wk_pb.WorkerMessage(
+            session_id=self._session_id,
+            ready=wk_pb.ReadyForWork(capabilities=self._capabilities),
+        )
+
+    def _update(self, operation_id: str, status, message: str = "") -> wk_pb.WorkerMessage:
+        return wk_pb.WorkerMessage(
+            session_id=self._session_id,
+            update=wk_pb.OperationUpdate(
+                operation_id=operation_id,
+                result=op_pb.AtomicOperationResult(status=status, message=message),
+            ),
+        )

boundflow/anthropic_client.py

@@ -0,0 +1,79 @@
+"""Real Anthropic API client implementing the LlmClient protocol."""
+from __future__ import annotations
+
+import anthropic as _anthropic
+
+from .llm import LlmClient, LlmRequest, LlmResponse, TextBlock, ToolResultBlock, ToolUseBlock, Usage
+
+
+def _encode(blocks: list) -> list:
+    out = []
+    for b in blocks:
+        if isinstance(b, TextBlock):
+            out.append({"type": "text", "text": b.text})
+        elif isinstance(b, ToolUseBlock):
+            out.append({"type": "tool_use", "id": b.id, "name": b.name, "input": b.input})
+        elif isinstance(b, ToolResultBlock):
+            out.append({"type": "tool_result", "tool_use_id": b.tool_use_id,
+                        "content": b.content, "is_error": b.is_error})
+    return out
+
+
+def _decode(blocks) -> list:
+    out = []
+    for b in blocks:
+        if b.type == "text":
+            out.append(TextBlock(b.text))
+        elif b.type == "tool_use":
+            out.append(ToolUseBlock(b.id, b.name, b.input))
+    return out
+
+
+class AnthropicLlmClient:
+    """Wraps anthropic.AsyncAnthropic to implement LlmClient."""
+
+    def __init__(self, api_key: str) -> None:
+        self._client = _anthropic.AsyncAnthropic(api_key=api_key)
+
+    async def complete(self, request: LlmRequest) -> LlmResponse:
+        messages = [
+            {"role": m.role, "content": _encode(m.content) if isinstance(m.content, list) else m.content}
+            for m in request.messages
+        ]
+        tools = [
+            {"name": t.name, "description": t.description, "input_schema": t.input_schema}
+            for t in request.tools
+        ]
+        # Caching the system block also caches the tools (render order is
+        # tools -> system -> messages), so one breakpoint covers the stable prefix.
+        system = request.system
+        if request.cache:
+            system = [{"type": "text", "text": request.system,
+                       "cache_control": {"type": "ephemeral"}}]
+
+        kwargs: dict = dict(
+            model=request.model,
+            max_tokens=request.max_tokens,
+            system=system,
+            messages=messages,
+            tools=tools,
+        )
+        if request.forced_tool:
+            kwargs["tool_choice"] = {"type": "tool", "name": request.forced_tool}
+
+        resp = await self._client.messages.create(**kwargs)
+        stop = resp.stop_reason
+        # Treat max_tokens like end_turn so the orchestrator can re-prompt with submit_result.
+        if stop == "max_tokens":
+            stop = "end_turn"
+        u = resp.usage
+        return LlmResponse(
+            content=_decode(resp.content),
+            stop_reason=stop,
+            usage=Usage(
+                u.input_tokens,
+                u.output_tokens,
+                getattr(u, "cache_creation_input_tokens", 0) or 0,
+                getattr(u, "cache_read_input_tokens", 0) or 0,
+            ),
+        )

boundflow/cli/__init__.py

@@ -0,0 +1,42 @@
+"""boundflow — BoundFlow control plane CLI."""
+
+import typer
+
+from boundflow.cli._client import configure
+from boundflow.cli._output import set_json
+from boundflow.cli.commands import audit, policies, pricing, tenants, workflows
+
+app = typer.Typer(
+    name="boundflow",
+    help="BoundFlow control plane CLI — manage workflows, policies, and audit logs.",
+    no_args_is_help=True,
+)
+
+app.add_typer(tenants.app, name="tenant")
+app.add_typer(workflows.app, name="workflow")
+app.add_typer(policies.app, name="policy")
+app.add_typer(audit.app, name="audit")
+app.add_typer(pricing.app, name="pricing")
+
+
+@app.callback()
+def root(
+    server: str = typer.Option(
+        "", "--server", envvar="BOUNDFLOW_SERVER_ADDRESS",
+        help="gRPC server address (default: http://localhost:50051)",
+    ),
+    api_key: str = typer.Option(
+        "", "--api-key", envvar="BOUNDFLOW_API_KEY",
+        help="BoundFlow API key",
+    ),
+    json_output: bool = typer.Option(
+        False, "--json",
+        help="Output raw JSON (useful for scripting)",
+    ),
+):
+    set_json(json_output)
+    configure(server, api_key)
+
+
+def main() -> None:
+    app()

boundflow/cli/__main__.py

@@ -0,0 +1,5 @@
+"""Enable `python -m boundflow.cli`."""
+
+from boundflow.cli import main
+
+main()

boundflow/cli/_client.py

@@ -0,0 +1,42 @@
+"""Async bridge between sync Typer commands and the async ControlPlaneClient."""
+
+import asyncio
+import os
+
+import typer
+
+from boundflow.control_plane import ControlPlaneClient, DEFAULT_SERVER_ADDRESS
+
+_server: str = DEFAULT_SERVER_ADDRESS
+_api_key: str = ""
+
+
+def configure(server: str, api_key: str) -> None:
+    # Runs in the root callback for every invocation — including `--help` — so it
+    # only resolves config, never fails. The API key is required lazily in cp_call,
+    # when a command actually calls the control plane.
+    global _server, _api_key
+    _server = server or os.environ.get("BOUNDFLOW_SERVER_ADDRESS") or DEFAULT_SERVER_ADDRESS
+    _api_key = api_key or os.environ.get("BOUNDFLOW_API_KEY") or ""
+
+
+def cp_call(fn):
+    """Open a ControlPlaneClient, call fn(client), close, return result.
+
+    Converts any exception into a user-facing error message + Exit(1).
+    """
+    if not _api_key:
+        typer.echo("Error: no API key. Set BOUNDFLOW_API_KEY or pass --api-key.", err=True)
+        raise typer.Exit(1)
+
+    async def _run():
+        async with ControlPlaneClient(_server, api_key=_api_key) as cp:
+            return await fn(cp)
+
+    try:
+        return asyncio.run(_run())
+    except typer.Exit:
+        raise
+    except Exception as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(1)

boundflow/cli/_output.py

@@ -0,0 +1,90 @@
+"""Rich table rendering and --json output helpers."""
+
+import json
+from dataclasses import asdict, is_dataclass
+from datetime import datetime
+from enum import Enum
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+_json_mode: bool = False
+
+
+def set_json(value: bool) -> None:
+    global _json_mode
+    _json_mode = value
+
+
+def _normalize(value):
+    """Recursively convert enum instances to their .value, so table display
+    and JSON output both show plain strings rather than 'EnumClass.member'."""
+    if isinstance(value, Enum):
+        return value.value
+    if isinstance(value, dict):
+        return {k: _normalize(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_normalize(v) for v in value]
+    return value
+
+
+def _to_dict(obj) -> dict:
+    if is_dataclass(obj):
+        raw = asdict(obj)
+    elif isinstance(obj, dict):
+        raw = obj
+    else:
+        raw = vars(obj)
+    return _normalize(raw)
+
+
+def _json_default(o):
+    if isinstance(o, datetime):
+        return o.isoformat()
+    return str(o)
+
+
+def output(data) -> None:
+    """Render a single record (dict/dataclass) or a list of them."""
+    if isinstance(data, list):
+        rows = [_to_dict(r) for r in data]
+        if _json_mode:
+            typer.echo(json.dumps(rows, default=_json_default, indent=2))
+        else:
+            _table(rows)
+    else:
+        rec = _to_dict(data)
+        if _json_mode:
+            typer.echo(json.dumps(rec, default=_json_default, indent=2))
+        else:
+            _record(rec)
+
+
+def _table(rows: list[dict]) -> None:
+    if not rows:
+        console.print("[dim]No results.[/dim]")
+        return
+    t = Table(show_header=True, header_style="bold cyan")
+    for key in rows[0]:
+        t.add_column(str(key))
+    for row in rows:
+        t.add_row(*[str(v) if v is not None else "" for v in row.values()])
+    console.print(t)
+
+
+def _record(rec: dict) -> None:
+    t = Table(show_header=False, box=None, padding=(0, 1))
+    t.add_column("Key", style="bold cyan", no_wrap=True)
+    t.add_column("Value")
+    for k, v in rec.items():
+        t.add_row(str(k), str(v) if v is not None else "")
+    console.print(t)
+
+
+def success(msg: str) -> None:
+    if _json_mode:
+        typer.echo(json.dumps({"status": "ok", "message": msg}))
+    else:
+        console.print(f"[green]{msg}[/green]")

boundflow/cli/commands/audit.py

@@ -0,0 +1,62 @@
+"""boundflow audit — approval and policy audit log commands."""
+
+from dataclasses import asdict
+from typing import Optional
+
+import typer
+
+from boundflow.cli._client import cp_call
+from boundflow.cli._output import output
+
+app = typer.Typer(help="View approval and policy audit records.")
+
+
+def _flatten(record) -> dict:
+    """Flatten a dataclass to a dict, serialising nested structures to strings."""
+    d = asdict(record) if hasattr(record, "__dataclass_fields__") else vars(record)
+    return {k: str(v) if isinstance(v, (list, dict)) else v for k, v in d.items()}
+
+
+@app.command("approvals")
+def approvals(
+    workflow_id: str = typer.Argument(..., help="Workflow ID"),
+    approval_id: Optional[str] = typer.Option(None, "--approval-id", help="Look up a single approval by ID"),
+):
+    """List approval decisions for a workflow (or fetch one by approval ID)."""
+    if approval_id:
+        result = cp_call(lambda cp: cp.get_approval_audit_by_id(approval_id))
+        if result is None:
+            typer.echo(f"No approval found with ID {approval_id}.", err=True)
+            raise typer.Exit(1)
+        output(_flatten(result))
+    else:
+        results = cp_call(lambda cp: cp.get_approval_audit(workflow_id))
+        output([_flatten(r) for r in results])
+
+
+@app.command("workflow")
+def workflow_policy(
+    workflow_id: str = typer.Argument(..., help="Workflow ID"),
+):
+    """List workflow-lifecycle policy firings for a workflow."""
+    results = cp_call(lambda cp: cp.get_workflow_policy_audit(workflow_id))
+    output([_flatten(r) for r in results])
+
+
+@app.command("agent")
+def agent_policy(
+    workflow_id: str = typer.Argument(..., help="Workflow ID"),
+    agent_name: str = typer.Argument(..., help="Agent name"),
+):
+    """List agent-lifecycle policy firings for a specific agent."""
+    results = cp_call(lambda cp: cp.get_agent_policy_audit(workflow_id, agent_name))
+    output([_flatten(r) for r in results])
+
+
+@app.command("log")
+def log(
+    workflow_id: Optional[str] = typer.Argument(None, help="Workflow ID (omit for tenant-wide log)"),
+):
+    """Show the unified audit log (approvals + policy firings, newest first)."""
+    results = cp_call(lambda cp: cp.get_audit_log(workflow_id or ""))
+    output([_flatten(r) for r in results])