boundflow 0.2.0__tar.gz → 0.4.0__tar.gz

{boundflow-0.2.0 → boundflow-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boundflow
-Version: 0.2.0
+Version: 0.4.0
 Summary: BoundFlow Python SDK — build governed fleets of agents against a self-hostable control plane.
 License-Expression: MIT
 Keywords: agents,llm,orchestration,control-plane,governance
@@ -18,6 +18,8 @@ Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-asyncio; extra == "dev"
 Requires-Dist: langchain-core>=0.3; extra == "dev"
 Requires-Dist: langchain-anthropic>=0.3; extra == "dev"
+Requires-Dist: opentelemetry-sdk; extra == "dev"
+Requires-Dist: opentelemetry-exporter-otlp; extra == "dev"
 Provides-Extra: langchain
 Requires-Dist: langchain-core>=0.3; extra == "langchain"
 Provides-Extra: otel

{boundflow-0.2.0 → boundflow-0.4.0}/boundflow/__init__.py

@@ -5,10 +5,15 @@ from .control_plane import (
     ControlPlaneClient,
     ApprovalAuditRecord,
     ApprovalDecision,
+    InputAuditRecord,
+    InputDecision,
     PolicyActionRecord,
     WorkflowPolicyAction,
     AgentPolicyActionRecord,
+    InvokeMode,
     LifecycleState,
+    PendingApproval,
+    PendingInput,
     RequestInfo,
     Run,
     RunOutcome,
@@ -18,6 +23,7 @@ from .control_plane import (
     Workflow,
     WorkflowConfig,
     WorkflowInfo,
+    WorkflowMetrics,
     WorkflowState,
 )
 from .errors import (
@@ -32,7 +38,7 @@ from .errors import (
     UnauthenticatedError,
     UnavailableError,
 )
-from .llm import MockLlmClient, MockContext, Turn, turn, submit
+from .llm import AgentCallTimeout, MockLlmClient, MockContext, Turn, turn, submit
 from .trace import (
     AgentRunTrace,
     JsonlFileTraceSink,
@@ -62,8 +68,10 @@ from .worker import (
     AgentDefinition,
     ApprovalRequest,
     AwaitApproval,
+    AwaitInput,
     BoundFlowWorker,
     Complete,
+    InputRequest,
     Next,
     OperationContext,
     OperationResult,
@@ -75,11 +83,11 @@ __all__ = [
     "AnthropicLlmClient",
     "ControlPlaneClient", "LifecycleState", "RunStatus", "RunOutcome", "Run", "RequestInfo",
     "Tenant", "TenantGroup", "Workflow",
-    "WorkflowConfig", "WorkflowState", "WorkflowInfo", "ApprovalAuditRecord", "ApprovalDecision", "PolicyActionRecord", "WorkflowPolicyAction", "AgentPolicyActionRecord", "MockLlmClient", "MockContext", "Turn",
+    "WorkflowConfig", "WorkflowState", "WorkflowInfo", "WorkflowMetrics", "PendingApproval", "PendingInput", "InvokeMode", "ApprovalAuditRecord", "ApprovalDecision", "InputAuditRecord", "InputDecision", "PolicyActionRecord", "WorkflowPolicyAction", "AgentPolicyActionRecord", "AgentCallTimeout", "MockLlmClient", "MockContext", "Turn",
     "turn", "submit", "AgentMetric", "AgentRule", "Cooldown", "Op", "Pause",
     "RuntimePolicy", "SetMaxCostUsd", "SetMaxLlmCalls", "SetMaxTokensPerCall",
     "SetModel", "SetVersion", "ToolCallLimit", "WorkflowMetric", "WorkflowRule",
-    "AgentDefinition", "ApprovalRequest", "AwaitApproval", "BoundFlowWorker",
+    "AgentDefinition", "ApprovalRequest", "AwaitApproval", "AwaitInput", "InputRequest", "BoundFlowWorker",
     "Complete", "Next", "OperationContext", "OperationResult", "Tool", "tool",
     "AgentRunTrace", "OperationTrace", "Span", "TraceSink", "LoggingTraceSink",
     "JsonlFileTraceSink", "OTelTraceSink",

{boundflow-0.2.0 → boundflow-0.4.0}/boundflow/_transport.py

@@ -1,9 +1,9 @@
 """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.
+The worker stream loop and proto mapping helpers, 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
@@ -34,7 +34,7 @@ def _strip_scheme(addr: str) -> str:
 
 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."""
+    (proto JSON convention), opaque policy contents preserved."""
     if not op.HasField("context"):
         return {}
     return json_format.MessageToDict(op.context)
@@ -50,11 +50,16 @@ def new_approval_id() -> str:
     return str(uuid.uuid4())
 
 
+def new_input_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),
+        latency_seconds=snapshot.get("latency_seconds", 0.0),
         ran_at=snapshot.get("ran_at", 0),
     )
     for tool, count in (snapshot.get("calls_per_tool") or {}).items():
@@ -89,6 +94,7 @@ def _runtime_policy_to_proto(p) -> ap_pb.AgentRuntimePolicy:
         max_llm_calls=p.max_llm_calls,
         max_cost_usd=p.max_cost_usd,
         max_tokens_per_call=p.max_tokens_per_call,
+        max_call_seconds=p.max_call_seconds,
         tool_call_limits=[ap_pb.ToolCallLimit(tool=l.tool, max_calls=l.max_calls) for l in p.tool_call_limits],
     )
 

{boundflow-0.2.0 → boundflow-0.4.0}/boundflow/cli/_client.py

@@ -5,6 +5,7 @@ import os
 
 import typer
 
+from boundflow.cli._output import error as report_error
 from boundflow.control_plane import ControlPlaneClient, DEFAULT_SERVER_ADDRESS
 
 _server: str = DEFAULT_SERVER_ADDRESS
@@ -26,7 +27,7 @@ def cp_call(fn):
     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)
+        report_error("no API key. Set BOUNDFLOW_API_KEY or pass --api-key.")
         raise typer.Exit(1)
 
     async def _run():
@@ -38,5 +39,5 @@ def cp_call(fn):
     except typer.Exit:
         raise
     except Exception as exc:
-        typer.echo(f"Error: {exc}", err=True)
+        report_error(str(exc))
         raise typer.Exit(1)

{boundflow-0.2.0 → boundflow-0.4.0}/boundflow/cli/_output.py

@@ -18,6 +18,10 @@ def set_json(value: bool) -> None:
     _json_mode = value
 
 
+def is_json() -> bool:
+    return _json_mode
+
+
 def _normalize(value):
     """Recursively convert enum instances to their .value, so table display
     and JSON output both show plain strings rather than 'EnumClass.member'."""
@@ -88,3 +92,13 @@ def success(msg: str) -> None:
         typer.echo(json.dumps({"status": "ok", "message": msg}))
     else:
         console.print(f"[green]{msg}[/green]")
+
+
+def error(msg: str) -> None:
+    """Report a failure. In --json mode this goes to stdout as structured JSON,
+    so scripted/--json callers get a machine-readable error instead of having
+    to parse stderr text."""
+    if _json_mode:
+        typer.echo(json.dumps({"status": "error", "message": msg}))
+    else:
+        typer.echo(f"Error: {msg}", err=True)

{boundflow-0.2.0 → boundflow-0.4.0}/boundflow/cli/commands/policies.py

@@ -7,7 +7,7 @@ from typing import List, Optional
 import typer
 
 from boundflow.cli._client import cp_call
-from boundflow.cli._output import success
+from boundflow.cli._output import error, output, success
 from boundflow.policies import AgentRule, RuntimePolicy, ToolCallLimit, WorkflowRule
 
 app = typer.Typer(help="Manage agent and workflow policies.")
@@ -28,13 +28,13 @@ def _parse_tool_limit(value: str) -> ToolCallLimit:
 
 def _load_json(file: Optional[Path], inline: Optional[str]) -> list:
     if file and inline:
-        typer.echo("Error: provide --file or --rules, not both.", err=True)
+        error("provide --file or --rules, not both.")
         raise typer.Exit(1)
     if file:
         return json.loads(file.read_text(encoding="utf-8-sig"))
     if inline:
         return json.loads(inline)
-    typer.echo("Error: provide --file or --rules.", err=True)
+    error("provide --file or --rules.")
     raise typer.Exit(1)
 
 
@@ -65,6 +65,16 @@ def runtime_set(
     success(f"Runtime policy set on {workflow_id} / {agent_name}.")
 
 
+@app.command("get-runtime")
+def runtime_get(
+    workflow_id: str = typer.Argument(..., help="Workflow ID"),
+    agent_name: str = typer.Argument(..., help="Agent name"),
+):
+    """Show the armed runtime (hard cap) policy for an agent (empty if none is set)."""
+    policy = cp_call(lambda cp: cp.get_agent_runtime_policy(workflow_id, agent_name))
+    output(policy or {})
+
+
 @lifecycle_app.command("set-agent")
 def lifecycle_set_agent(
     workflow_id: str = typer.Argument(..., help="Workflow ID"),
@@ -98,3 +108,22 @@ def lifecycle_set_workflow(
     wf_rules = [WorkflowRule.model_validate(r) for r in raw]
     cp_call(lambda cp: cp.set_workflow_lifecycle_policy(workflow_id, wf_rules))
     success(f"Workflow lifecycle policy set on {workflow_id}.")
+
+
+@lifecycle_app.command("get-agent")
+def lifecycle_get_agent(
+    workflow_id: str = typer.Argument(..., help="Workflow ID"),
+    agent_name: str = typer.Argument(..., help="Agent name"),
+):
+    """Show the armed lifecycle rules for an agent (empty if none is set)."""
+    policy = cp_call(lambda cp: cp.get_agent_lifecycle_policy(workflow_id, agent_name))
+    output(policy or {})
+
+
+@lifecycle_app.command("get-workflow")
+def lifecycle_get_workflow(
+    workflow_id: str = typer.Argument(..., help="Workflow ID"),
+):
+    """Show the armed lifecycle rules for a workflow (empty if none is set)."""
+    rules = cp_call(lambda cp: cp.get_workflow_lifecycle_policy(workflow_id))
+    output([r.model_dump(mode="json") for r in rules])

{boundflow-0.2.0 → boundflow-0.4.0}/boundflow/cli/commands/workflows.py

@@ -1,12 +1,13 @@
 """boundflow workflow — workflow lifecycle commands."""
 
+import json
 from typing import Optional
 
 import typer
 
 from boundflow.cli._client import cp_call
-from boundflow.cli._output import output, success
-from boundflow.control_plane import WorkflowConfig
+from boundflow.cli._output import error, output, success
+from boundflow.control_plane import InvokeMode, WorkflowConfig
 
 app = typer.Typer(help="Manage workflows.")
 
@@ -19,6 +20,12 @@ def create(
     timeout: int = typer.Option(60, "--timeout", help="Invoke timeout in seconds"),
     repeat: int = typer.Option(0, "--repeat", help="Repeat every N seconds (0 = no repeat)"),
     no_triggerable: bool = typer.Option(False, "--no-triggerable", help="Disable manual triggering"),
+    invoke_mode: InvokeMode = typer.Option(
+        InvokeMode.COALESCE, "--invoke-mode",
+        help="How piled-up invokes are handled: coalesce (latest-wins) or queue (run each, FIFO)"),
+    max_queue_depth: int = typer.Option(
+        0, "--max-queue-depth",
+        help="Queue-mode backlog cap; invokes past it are rejected (0 = server default)"),
 ):
     """Create a new workflow."""
     config = WorkflowConfig(
@@ -26,6 +33,8 @@ def create(
         invoke_timeout_seconds=timeout,
         repeat_every_seconds=repeat,
         triggerable=not no_triggerable,
+        invoke_mode=invoke_mode,
+        max_queue_depth=max_queue_depth,
     )
     result = cp_call(lambda cp: cp.create_workflow(workflow_type, tenant_id, config=config))
     output(result)
@@ -59,6 +68,42 @@ def get(
     output(result)
 
 
+@app.command("set-config")
+def set_config(
+    workflow_id: str = typer.Argument(..., help="Workflow ID"),
+    version: int = typer.Option(..., "--version", "-v", help="Workflow version to switch to"),
+    timeout: int = typer.Option(60, "--timeout", help="Invoke timeout in seconds"),
+    repeat: int = typer.Option(0, "--repeat", help="Repeat every N seconds (0 = no repeat)"),
+    no_triggerable: bool = typer.Option(False, "--no-triggerable", help="Disable manual triggering"),
+    invoke_mode: InvokeMode = typer.Option(
+        InvokeMode.COALESCE, "--invoke-mode",
+        help="How piled-up invokes are handled: coalesce (latest-wins) or queue (run each, FIFO)"),
+    max_queue_depth: int = typer.Option(
+        0, "--max-queue-depth",
+        help="Queue-mode backlog cap; invokes past it are rejected (0 = server default)"),
+):
+    """Update a workflow's config settings."""
+    config = WorkflowConfig(
+        version=version,
+        invoke_timeout_seconds=timeout,
+        repeat_every_seconds=repeat,
+        triggerable=not no_triggerable,
+        invoke_mode=invoke_mode,
+        max_queue_depth=max_queue_depth,
+    )
+    result = cp_call(lambda cp: cp.set_workflow_config(workflow_id, config))
+    output(result)
+
+
+@app.command("metrics")
+def metrics(
+    workflow_id: str = typer.Argument(..., help="Workflow ID"),
+):
+    """Cumulative totals (cost, run count, failures, ...) for a workflow's current version."""
+    result = cp_call(lambda cp: cp.get_workflow_metrics(workflow_id))
+    output(result)
+
+
 @app.command("list")
 def list_workflows():
     """List all workflows in the tenant group."""
@@ -116,6 +161,23 @@ def reject(
     success(f"Approval {approval_id} rejected.")
 
 
+@app.command("submit-input")
+def submit_input(
+    workflow_id: str = typer.Argument(..., help="Workflow ID"),
+    input_id: str = typer.Argument(..., help="Input ID (from the input request)"),
+    answer: str = typer.Option(..., "--answer", help="Answer as a JSON object, e.g. '{\"choice\": \"refund\"}'"),
+    actor: str = typer.Option("", "--actor", help="Who supplied the answer (e.g. email or user ID)"),
+):
+    """Answer a pending workflow input gate."""
+    try:
+        parsed = json.loads(answer)
+    except json.JSONDecodeError as e:
+        error(f"--answer must be valid JSON: {e}")
+        raise typer.Exit(1)
+    cp_call(lambda cp: cp.submit_input(workflow_id, input_id, parsed, actor=actor))
+    success(f"Input {input_id} submitted.")
+
+
 @app.command("delete")
 def delete(
     workflow_id: str = typer.Argument(..., help="Workflow ID"),