behalf 0.1.0__py3-none-any.whl

behalf/__init__.py

@@ -0,0 +1,48 @@
+"""behalf — a small framework for scoped agents.
+
+Give an agent a brief, a fixed set of tools (read, or action-with-confirmation),
+and a pluggable model backend; it works within that behalf and returns a result.
+The core is dependency-free; a backend extra (claude/gemini/aws) adds a runner.
+"""
+
+from .core import (
+    AgentRunner,
+    ConfirmFn,
+    RunOutcome,
+    Task,
+    ToolSpec,
+    default_confirm,
+    run_task,
+)
+
+__all__ = [
+    "AgentRunner", "ConfirmFn", "RunOutcome", "Task", "ToolSpec",
+    "default_confirm", "run_task", "make_runner",
+]
+
+
+def make_runner(backend: str, model: str | None = None):
+    """Resolve a runner by name, importing only that backend's SDK.
+
+    backend: "claude" | "gemini" | "aws". Raises SystemExit with an install hint
+    if the backend's package isn't installed.
+    """
+    if backend == "claude":
+        try:
+            from .runner.sdk import SDKRunner
+        except ImportError as e:
+            raise SystemExit(f"backend 'claude' needs the Claude Agent SDK: pip install behalf[claude] ({e})")
+        return SDKRunner(model) if model else SDKRunner()
+    if backend == "gemini":
+        try:
+            from .runner.adk import ADKRunner
+        except ImportError as e:
+            raise SystemExit(f"backend 'gemini' needs Google ADK: pip install behalf[gemini] ({e})")
+        return ADKRunner(model=model) if model else ADKRunner()
+    if backend == "aws":
+        try:
+            from .runner.strands import StrandsRunner
+        except ImportError as e:
+            raise SystemExit(f"backend 'aws' needs Strands: pip install behalf[aws] ({e})")
+        return StrandsRunner(model=model) if model else StrandsRunner()
+    raise SystemExit(f"unknown backend {backend!r} (choose: claude, gemini, aws)")

behalf/console.py

@@ -0,0 +1,52 @@
+"""Small terminal-output helper: a bit of color and structure for the live
+trace. Colors switch off automatically when stdout isn't a TTY (piped, captured
+in tests) or when NO_COLOR is set, so output stays clean everywhere."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+_ON = sys.stdout.isatty() and os.environ.get("NO_COLOR") is None
+
+
+def _wrap(code: str):
+    if not _ON:
+        return lambda s: str(s)
+    return lambda s: f"\033[{code}m{s}\033[0m"
+
+
+bold = _wrap("1")
+dim = _wrap("2")
+red = _wrap("31")
+green = _wrap("32")
+yellow = _wrap("33")
+cyan = _wrap("36")
+
+
+def header(text: str, index: int | None = None, total: int | None = None) -> None:
+    tag = dim(f"  [{index}/{total}]") if index and total else ""
+    print(f"\n{cyan('▸')} {bold(text)}{tag}", flush=True)
+
+
+def phase(text: str) -> None:
+    print(f"  {dim('·')} {dim(text)}", flush=True)
+
+
+def op(name: str, detail: str = "") -> None:
+    tail = f" {dim(detail)}" if detail else ""
+    print(f"  {green('→')} {bold(name)}{tail}", flush=True)
+
+
+def ok(text: str) -> None:
+    print(f"  {green('✓')} {text}", flush=True)
+
+
+def warn(text: str) -> None:
+    print(f"  {yellow('⚠')} {text}", flush=True)
+
+
+def think(chunk: str) -> None:
+    """Streamed assistant text, dimmed so the operation lines stand out."""
+    sys.stdout.write(dim(chunk))
+    sys.stdout.flush()

behalf/core.py

@@ -0,0 +1,133 @@
+"""A tiny framework for a recurring pattern: give an agent a SCOPED task that
+first gathers intent from the user, freezes it into a reproducible manifest,
+then executes toward one specific outcome with a fixed, typed toolset.
+
+    elicit (adaptive conversation, seeded)  ->  manifest (frozen, reviewable)
+                                            ->  execute (agent + fixed tools)
+
+The core knows nothing about any particular domain. A Task supplies the three
+things that vary: what to ask the user, which tools the agent may use, and what
+a valid result is. Read-only tasks, tasks with an action tool that gates on user
+confirmation, and pipelines of tasks are all just Tasks.
+"""
+
+from __future__ import annotations
+
+import json
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable, Optional, Protocol
+
+
+@dataclass
+class ToolSpec:
+    """A tool the agent can call. `kind` distinguishes read (call freely) from
+    action (mutates something -> may require confirming the exact arguments)."""
+
+    name: str
+    description: str
+    input_schema: dict
+    handler: Callable[[dict], Awaitable[dict]]
+    kind: str = "read"  # "read" | "action"
+    confirm: bool = False  # if action: pause for approval before running
+
+
+# confirm_fn(tool_name, args) -> bool. Supplied by the runtime (CLI prompt, test
+# stub, auto-approve). Only ever called for action tools with confirm=True.
+ConfirmFn = Callable[[str, dict], bool]
+
+
+class Task(ABC):
+    """A scoped capability. Subclasses fill in the three varying pieces."""
+
+    name: str = "task"
+
+    # Whether the frozen setup manifest must be approved before execution.
+    # (Action tools have their OWN per-call confirmation regardless.)
+    requires_setup_approval: bool = False
+
+    def setup_system_prompt(self) -> str:
+        """Seeds elicitation: what the agent already knows (schemas, fixed
+        metadata) and what it must learn from the user."""
+        return "Gather what you need from the user, then finalize a setup manifest."
+
+    @abstractmethod
+    def manifest_schema(self) -> dict:
+        """The schema the elicitation must produce and freeze."""
+
+    def build_tools(self, manifest: dict) -> list[ToolSpec]:
+        """Fixed toolset for the default single-run execute(). Iterating tasks
+        override execute() and build tools per item, leaving this as []."""
+        return []
+
+    @abstractmethod
+    def execute_system_prompt(self, manifest: dict) -> str:
+        """Instruction for the execution agent."""
+
+    async def execute(self, runner: "AgentRunner", manifest: dict, confirm_fn: "ConfirmFn") -> Any:
+        """Run the task. Default: a single agent run over the built tools."""
+        tools = self.build_tools(manifest)
+        return await runner.run_agent(
+            system_prompt=self.execute_system_prompt(manifest),
+            user_prompt=manifest.get("goal", "Complete the task."),
+            tools=tools,
+            confirm_fn=confirm_fn,
+        )
+
+    def validate_result(self, result: Any) -> None:
+        """Raise if the produced result is unacceptable. Override per task."""
+        return None
+
+
+class AgentRunner(Protocol):
+    """How the framework talks to a model. Real ones wrap an SDK; tests inject a
+    fake. This seam is what lets the whole flow be tested without a key."""
+
+    async def converse(self, task: "Task") -> dict:
+        """Run the seeded setup conversation; return the manifest."""
+        ...
+
+    async def run_agent(
+        self, system_prompt: str, user_prompt: str, tools: list[ToolSpec], confirm_fn: "ConfirmFn"
+    ) -> Any:
+        """One agent run with a fixed toolset; action tools gate on confirm_fn."""
+        ...
+
+
+@dataclass
+class RunOutcome:
+    manifest: dict
+    result: Any
+    approved: bool = True
+
+
+def default_confirm(tool_name: str, args: dict) -> bool:
+    """CLI confirmation: show the exact call and ask. Safe default for actions."""
+    print(f"\n[confirm] about to run action '{tool_name}' with:")
+    print(json.dumps(args, indent=2))
+    return input("proceed? [y/N] ").strip().lower() in ("y", "yes")
+
+
+async def run_task(
+    task: Task,
+    runner: AgentRunner,
+    manifest: Optional[dict] = None,
+    confirm_fn: ConfirmFn = default_confirm,
+    approve_fn: Optional[Callable[[dict], bool]] = None,
+) -> RunOutcome:
+    """The one entrypoint every task flows through. manifest given -> skip the
+    conversation (reproducible/batch); None -> converse to produce it. Then
+    optional setup approval, then execute; action tools gate on confirm_fn."""
+    if manifest is None:
+        manifest = await runner.converse(task)
+
+    approved = True
+    if task.requires_setup_approval:
+        approver = approve_fn or (lambda m: default_confirm("finalize-setup", m))
+        approved = approver(manifest)
+        if not approved:
+            return RunOutcome(manifest=manifest, result=None, approved=False)
+
+    result = await task.execute(runner, manifest, confirm_fn)
+    task.validate_result(result)
+    return RunOutcome(manifest=manifest, result=result, approved=approved)

behalf/runner/__init__.py

@@ -0,0 +1,26 @@
+"""Model backends. Each submodule imports its own SDK at module load, so nothing
+here is imported until you ask for a specific runner — installing one backend's
+extra doesn't drag in the others.
+
+`from behalf.runner import SDKRunner` resolves lazily; importing the submodule
+directly (`behalf.runner.sdk`) is equivalent.
+"""
+
+_RUNNERS = {
+    "SDKRunner": ".sdk",       # Claude, via claude-agent-sdk
+    "ADKRunner": ".adk",       # Gemini, via google-adk
+    "StrandsRunner": ".strands",  # AWS Bedrock, via strands-agents
+}
+
+
+def __getattr__(name):
+    module = _RUNNERS.get(name)
+    if module is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    from importlib import import_module
+
+    return getattr(import_module(module, __name__), name)
+
+
+def __dir__():
+    return sorted(_RUNNERS)

behalf/runner/adk.py

@@ -0,0 +1,176 @@
+"""A Gemini backend via Google's Agent Development Kit (ADK), as an alternative
+AgentRunner to SDKRunner.
+
+STATUS: scaffolded, NOT yet run. Google ADK isn't a base dependency and isn't
+installed in the dev image, so this module is untested end to end. The shape
+follows ADK's documented API (Agent + FunctionTool + Runner + session service),
+but the spots marked TODO are where the ADK specifics must be confirmed against
+the installed version before relying on it. Install with `pip install google-adk`.
+
+It exists because the framework already abstracts the model behind AgentRunner,
+so adding Gemini is a contained job: convert our ToolSpecs to ADK function tools
+(carrying the same read/action confirmation gate) and drive ADK's runner. None
+of ProfileTask / tools.py / the container code changes.
+"""
+
+from __future__ import annotations
+
+import inspect
+import json
+from typing import Any
+
+# Top-level imports so a missing ADK fails here, at import, not mid-run. This
+# module is only imported when you explicitly want the Gemini path
+# (`from behalf.runner.adk import ADKRunner`), so it never burdens the
+# Claude/SDK path or `import behalf`.
+from google.adk.agents import Agent
+from google.adk.runners import Runner
+from google.adk.sessions import InMemorySessionService
+from google.adk.tools import FunctionTool
+from google.genai import types
+
+from ..core import AgentRunner, ConfirmFn, Task, ToolSpec
+
+_PY_TYPE = {str: str, int: int, float: float, bool: bool, list: list, dict: dict}
+
+
+def _to_adk_tool(ts: ToolSpec, confirm_fn: ConfirmFn) -> FunctionTool:
+    """Wrap one ToolSpec as an ADK FunctionTool.
+
+    ADK builds a tool's schema from the wrapped function's SIGNATURE (typed
+    params + docstring), whereas our ToolSpec carries an input_schema dict. So we
+    synthesize a function with matching parameters, then let ADK introspect it.
+
+    The wrapper also applies the read/action confirmation gate (same semantics as
+    SDKRunner) and adapts our handler's Anthropic-style {"content":[...]} return
+    into the plain value ADK expects a tool to return.
+    """
+
+    async def _invoke(**kwargs) -> Any:
+        if ts.kind == "action" and ts.confirm and not confirm_fn(ts.name, kwargs):
+            return "cancelled by user"
+        result = await ts.handler(kwargs)
+        # our handlers return {"content": [{"type": "text", "text": "..."}]}
+        try:
+            text = result["content"][0]["text"]
+        except (KeyError, IndexError, TypeError):
+            return result
+        try:
+            return json.loads(text)  # most of our tools emit JSON
+        except (ValueError, TypeError):
+            return text
+
+    # give ADK a real signature + docstring to introspect
+    params = [
+        inspect.Parameter(
+            name, inspect.Parameter.KEYWORD_ONLY, annotation=_PY_TYPE.get(typ, str)
+        )
+        for name, typ in ts.input_schema.items()
+    ]
+    _invoke.__name__ = ts.name
+    _invoke.__doc__ = ts.description
+    _invoke.__signature__ = inspect.Signature(
+        params
+    )  # TODO: confirm ADK reads __signature__ (vs real params)
+    _invoke.__annotations__ = {
+        n: _PY_TYPE.get(t, str) for n, t in ts.input_schema.items()
+    }
+    return FunctionTool(
+        _invoke
+    )  # TODO: confirm FunctionTool(func) is the current constructor
+
+
+class ADKRunner(AgentRunner):
+    """AgentRunner backed by Google ADK / Gemini. Same interface as SDKRunner."""
+
+    def __init__(
+        self,
+        model: str = "gemini-2.5-flash",
+        app_name: str = "behalf",
+        verbose: bool = True,
+    ):
+        self.model = model
+        self.app_name = app_name
+        self.verbose = verbose
+
+    async def _run_once(
+        self, instruction: str, user_prompt: str, adk_tools: list
+    ) -> list[str]:
+        agent = Agent(
+            name="behalf", model=self.model, instruction=instruction, tools=adk_tools
+        )
+        session_service = InMemorySessionService()
+        # TODO: confirm create_session is sync vs async in the installed ADK
+        session = session_service.create_session(
+            app_name=self.app_name, user_id="local", session_id="s1"
+        )
+        runner = Runner(
+            agent=agent, app_name=self.app_name, session_service=session_service
+        )
+
+        msg = types.Content(role="user", parts=[types.Part(text=user_prompt)])
+        texts: list[str] = []
+        # TODO: confirm run_async signature + how final text is surfaced on events
+        async for event in runner.run_async(
+            user_id="local", session_id=session.id, new_message=msg
+        ):
+            if self.verbose:
+                print(event)
+            content = getattr(event, "content", None)
+            if content and getattr(content, "parts", None):
+                for part in content.parts:
+                    if getattr(part, "text", None):
+                        texts.append(part.text)
+        return texts
+
+    async def run_agent(
+        self,
+        system_prompt: str,
+        user_prompt: str,
+        tools: list[ToolSpec],
+        confirm_fn: ConfirmFn,
+    ) -> Any:
+        adk_tools = [_to_adk_tool(t, confirm_fn) for t in tools]
+        await self._run_once(system_prompt, user_prompt, adk_tools)
+        # results are collected via the tools' side effects (e.g. record_artifact
+        # writing into ProfileTask's sink), same as SDKRunner.
+        return None
+
+    async def converse(self, task: Task) -> dict:
+        """Interactive setup: give the agent a finalize tool and loop until it's
+        called. Mirrors SDKRunner.converse. TODO: verify ADK multi-turn session
+        reuse (re-running the runner with the same session_id to continue)."""
+        captured: dict = {}
+
+        async def finalize_setup(manifest: dict) -> str:
+            """Finalize the setup manifest (matching the task's schema) and end setup."""
+            captured["manifest"] = manifest
+            return "setup finalized"
+
+        finalize = FunctionTool(finalize_setup)
+        agent = Agent(
+            name="setup",
+            model=self.model,
+            instruction=task.setup_system_prompt(),
+            tools=[finalize],
+        )
+        session_service = InMemorySessionService()
+        session = session_service.create_session(
+            app_name=self.app_name, user_id="local", session_id="setup"
+        )
+        runner = Runner(
+            agent=agent, app_name=self.app_name, session_service=session_service
+        )
+
+        prompt = "Let's set up this task. Ask me what you need."
+        while "manifest" not in captured:
+            msg = types.Content(role="user", parts=[types.Part(text=prompt)])
+            async for event in runner.run_async(
+                user_id="local", session_id=session.id, new_message=msg
+            ):
+                if self.verbose:
+                    print(event)
+            if "manifest" in captured:
+                break
+            prompt = input("\nyou> ")
+        return captured["manifest"]

behalf/runner/sdk.py

@@ -0,0 +1,116 @@
+"""Claude backend: an AgentRunner backed by the Claude Agent SDK.
+
+The SDK provides the agent loop, tool dispatch, and permissions. This module
+adapts our ToolSpecs into SDK tools (adding the action-confirmation gate) and
+runs them two ways:
+
+    run_agent()  one execution pass over a fixed toolset
+    converse()   interactive setup that ends when the model calls finalize_setup
+
+Live use needs ANTHROPIC_API_KEY and the Claude Code CLI on PATH.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from claude_agent_sdk import (
+    ClaudeAgentOptions,
+    ClaudeSDKClient,
+    create_sdk_mcp_server,
+    query,
+    tool,
+)
+
+from ..core import AgentRunner, ConfirmFn, Task, ToolSpec
+
+
+def _say(text: str) -> dict:
+    """An SDK tool result carrying a single text block."""
+    return {"content": [{"type": "text", "text": text}]}
+
+
+def _to_sdk_tool(spec: ToolSpec, confirm_fn: ConfirmFn):
+    """Adapt one ToolSpec into an SDK tool. Action tools ask for confirmation of
+    their exact arguments before the handler runs; read tools run directly."""
+
+    @tool(spec.name, spec.description, spec.input_schema)
+    async def _sdk_tool(args):
+        if spec.kind == "action" and spec.confirm and not confirm_fn(spec.name, args):
+            return _say("cancelled by user")
+        return await spec.handler(args)
+
+    return _sdk_tool
+
+
+class SDKRunner(AgentRunner):
+    def __init__(self, model: str | None = None, verbose: bool = True):
+        self.model = model
+        self.verbose = verbose
+
+    def _echo(self, message: Any) -> None:
+        if self.verbose:
+            print(message)
+
+    def _options(
+        self, server_name: str, server, allowed: list[str], system_prompt: str
+    ) -> ClaudeAgentOptions:
+        # Our tools are read-only or already gated by confirm_fn, so the SDK's
+        # own permission prompts are redundant here.
+        return ClaudeAgentOptions(
+            mcp_servers={server_name: server},
+            allowed_tools=allowed,
+            system_prompt=system_prompt,
+            permission_mode="bypassPermissions",
+            model=self.model,
+            max_turns=40,
+        )
+
+    async def run_agent(
+        self,
+        system_prompt: str,
+        user_prompt: str,
+        tools: list[ToolSpec],
+        confirm_fn: ConfirmFn,
+    ) -> Any:
+        server = create_sdk_mcp_server(
+            name="behalf",
+            version="0.1.0",
+            tools=[_to_sdk_tool(t, confirm_fn) for t in tools],
+        )
+        allowed = [f"mcp__behalf__{t.name}" for t in tools]
+        options = self._options("behalf", server, allowed, system_prompt)
+
+        async for message in query(prompt=user_prompt, options=options):
+            self._echo(message)
+        # Results are collected through the tools' side effects (e.g.
+        # record_artifact writing into the task's sink), not the return value.
+        return None
+
+    async def converse(self, task: Task) -> dict:
+        captured: dict = {}
+
+        @tool(
+            "finalize_setup",
+            "Finalize the setup manifest (matching the task's schema) and end setup.",
+            {"manifest": dict},
+        )
+        async def finalize(args):
+            captured["manifest"] = args.get("manifest", args)
+            return _say("setup finalized")
+
+        server = create_sdk_mcp_server(name="setup", version="0.1.0", tools=[finalize])
+        options = self._options(
+            "setup", server, ["mcp__setup__finalize_setup"], task.setup_system_prompt()
+        )
+
+        # The model asks the user for what it needs and drives the structure; we
+        # relay each of the user's replies until it calls finalize_setup.
+        async with ClaudeSDKClient(options=options) as client:
+            await client.query("Let's set up this task. Ask me what you need.")
+            while "manifest" not in captured:
+                async for message in client.receive_response():
+                    self._echo(message)
+                if "manifest" not in captured:
+                    await client.query(input("\nyou> "))
+        return captured["manifest"]

behalf/runner/strands.py

@@ -0,0 +1,179 @@
+"""An AWS backend via the Strands Agents SDK, running against Amazon Bedrock.
+
+Handy when Bedrock (IAM/AWS credentials) is easier to reach than an Anthropic or
+Google key. Authenticates with your normal AWS credential chain (profile / env /
+role) and a region; the model is a Bedrock model id, which can still be Claude
+(a Bedrock Anthropic inference profile), just reached through Bedrock.
+
+STATUS: scaffolded, NOT yet run here (needs `pip install strands-agents` and AWS
+creds). Shape follows the documented Strands API; spots to confirm against the
+installed version are marked TODO. Strands tools are plain Python functions and
+it exposes tool calls, so our ToolSpec -> function conversion (with the
+read/action confirm gate) maps over directly.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import json
+from typing import Any
+
+from strands import Agent
+from strands.models import (
+    BedrockModel,
+)  # TODO: confirm class name in the installed version
+
+from ..core import AgentRunner, ConfirmFn, Task, ToolSpec
+
+_PY_TYPE = {str: str, int: int, float: float, bool: bool, list: list, dict: dict}
+
+
+def _op_detail(name: str, kwargs: dict) -> str:
+    """A short, domain-agnostic one-liner for the trace: the scalar arguments,
+    space-joined. (A caller that wants prettier per-tool formatting can wrap the
+    runner; the library stays generic.)"""
+    scalars = [str(v) for v in kwargs.values()
+               if isinstance(v, (str, int, float, bool)) and str(v) != ""]
+    detail = " ".join(scalars) if scalars else json.dumps(kwargs, default=str)
+    return detail[:97] + "..." if len(detail) > 100 else detail
+
+
+def _to_strands_tool(ts: ToolSpec, confirm_fn: ConfirmFn, on_call=None):
+    """ToolSpec -> Strands tool. Strands reads the function signature + docstring
+    for the schema, so we synthesize typed params. Our async handler is bridged
+    to sync, the confirm gate is applied for action tools, and the
+    {"content":[...]} return is adapted to a plain value. on_call, if given, is
+    invoked with (name, kwargs) when the tool actually runs — that's where the
+    real-time trace line comes from, since the arguments are complete by then."""
+    from strands import tool
+
+    def _invoke(**kwargs) -> Any:
+        if on_call is not None:
+            on_call(ts.name, kwargs)
+        if ts.kind == "action" and ts.confirm and not confirm_fn(ts.name, kwargs):
+            return "cancelled by user"
+        result = asyncio.run(ts.handler(kwargs))
+        try:
+            text = result["content"][0]["text"]
+        except (KeyError, IndexError, TypeError):
+            return result
+        try:
+            return json.loads(text)
+        except (ValueError, TypeError):
+            return text
+
+    _invoke.__name__ = ts.name
+    _invoke.__doc__ = ts.description
+    _invoke.__signature__ = inspect.Signature(
+        [
+            inspect.Parameter(
+                n, inspect.Parameter.KEYWORD_ONLY, annotation=_PY_TYPE.get(t, str)
+            )
+            for n, t in ts.input_schema.items()
+        ]
+    )
+    _invoke.__annotations__ = {
+        n: _PY_TYPE.get(t, str) for n, t in ts.input_schema.items()
+    }
+    return tool(_invoke)  # TODO: confirm strands.tool(func) call form
+
+
+class StrandsRunner(AgentRunner):
+    """AgentRunner backed by Strands + Bedrock. Same interface as SDKRunner."""
+
+    def __init__(
+        self, model: str | None = None, region: str = "us-east-1", verbose: bool = True
+    ):
+        self.model = model  # None -> Strands' default (an Anthropic model on Bedrock)
+        self.region = region
+        self.verbose = verbose
+
+    def _model(self):
+        if self.model is None:
+            return None
+        return BedrockModel(
+            model_id=self.model, region_name=self.region
+        )  # TODO: confirm kwargs
+
+    def _render(self, event) -> None:
+        """Stream assistant text (dimmed). Tool lines print from the wrapper."""
+        if self.verbose and isinstance(event, dict) and event.get("data"):
+            from .. import console
+
+            console.think(event["data"])
+            self._mid_line = not event["data"].endswith("\n")
+
+    def _trace(self, name: str, kwargs: dict) -> None:
+        if not self.verbose:
+            return
+        from .. import console
+
+        if getattr(self, "_mid_line", False):
+            print()  # close a partial line of streamed text before the op line
+            self._mid_line = False
+        console.op(name, _op_detail(name, kwargs))
+
+    async def run_agent(
+        self,
+        system_prompt: str,
+        user_prompt: str,
+        tools: list[ToolSpec],
+        confirm_fn: ConfirmFn,
+    ) -> Any:
+        self._mid_line = False
+        kwargs = {
+            "system_prompt": system_prompt,
+            "tools": [
+                _to_strands_tool(t, confirm_fn, on_call=self._trace) for t in tools
+            ],
+            # silence Strands' own stdout printer so it doesn't double with ours
+            "callback_handler": None,
+        }
+        model = self._model()
+        if model is not None:
+            kwargs["model"] = model
+        agent = Agent(**kwargs)
+
+        stream = getattr(agent, "stream_async", None)
+        if stream is None:
+            result = await asyncio.to_thread(
+                agent, user_prompt
+            )  # TODO: prefer invoke_async
+            if self.verbose:
+                print(result)
+        else:
+            async for event in stream(user_prompt):
+                self._render(event)
+            if self.verbose and self._mid_line:
+                print()  # newline after trailing streamed text
+        return None  # results collected via tool side effects (record_artifact -> sink)
+
+    async def converse(self, task: Task) -> dict:
+        from strands import tool
+
+        captured: dict = {}
+
+        def finalize_setup(manifest: dict) -> str:
+            """Finalize the setup manifest (matching the task's schema) and end setup."""
+            captured["manifest"] = manifest
+            return "setup finalized"
+
+        kwargs = {
+            "system_prompt": task.setup_system_prompt(),
+            "tools": [tool(finalize_setup)],
+        }
+        model = self._model()
+        if model is not None:
+            kwargs["model"] = model
+        agent = Agent(**kwargs)
+
+        prompt = "Let's set up this task. Ask me what you need."
+        while "manifest" not in captured:
+            out = await asyncio.to_thread(agent, prompt)
+            if self.verbose:
+                print(out)
+            if "manifest" in captured:
+                break
+            prompt = input("\nyou> ")
+        return captured["manifest"]

behalf-0.1.0.dist-info/METADATA

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: behalf
+Version: 0.1.0
+Summary: A small framework for scoped agents: a brief, a typed toolset (read/action), a pluggable model backend.
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Provides-Extra: claude
+Requires-Dist: claude-agent-sdk>=0.2; extra == "claude"
+Provides-Extra: gemini
+Requires-Dist: google-adk>=1.0; extra == "gemini"
+Provides-Extra: aws
+Requires-Dist: strands-agents>=0.1; extra == "aws"
+Requires-Dist: boto3>=1.34; extra == "aws"
+Provides-Extra: all
+Requires-Dist: claude-agent-sdk>=0.2; extra == "all"
+Requires-Dist: google-adk>=1.0; extra == "all"
+Requires-Dist: strands-agents>=0.1; extra == "all"
+Requires-Dist: boto3>=1.34; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# behalf
+
+A small framework for the recurring pattern of a **scoped agent**: hand it a
+brief, a fixed set of tools, and bounded authority, and it does one job.
+
+
+## Abstractions
+
+- **Task** what to elicit from the user, which tools the agent gets, and what a valid result is.
+- **ToolSpec** can be a single tool or action.
+- **runner backend** is the model like the Claude Agent SDK, Google ADK, or Strands on Bedrock.
+
+
+```python
+from behalf import run_task, make_runner
+outcome = await run_task(MyTask(), make_runner("aws"))
+```
+
+
+## Install
+
+```bash
+pip install behalf            # core only (no backend)
+pip install behalf[claude]    # + Claude Agent SDK
+pip install behalf[aws]       # + Strands / Bedrock
+pip install behalf[gemini]    # + Google ADK
+```
+
+## License
+
+HPCIC DevTools is distributed under the terms of the MIT license.
+All new contributions must be made under this license.
+
+See [LICENSE](https://github.com/converged-computing/cloud-select/blob/main/LICENSE),
+[COPYRIGHT](https://github.com/converged-computing/cloud-select/blob/main/COPYRIGHT), and
+[NOTICE](https://github.com/converged-computing/cloud-select/blob/main/NOTICE) for details.
+
+SPDX-License-Identifier: (MIT)
+
+LLNL-CODE- 842614

behalf-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+behalf/__init__.py,sha256=vuUyk4YWtnYXYczwUPFOv3TJZ7pn5080Zo7kj-vShBA,1768
+behalf/console.py,sha256=c77STgrmzq1zrSXFYz3x8OFLSkh_RdayzNl1u-o8D5g,1361
+behalf/core.py,sha256=akrlYi6ekGIh3sE4LnPn1vwaTtBBkHWOkC_2yUpPGYc,5096
+behalf/runner/__init__.py,sha256=ck54cntAUFu_HLoFC8DIWcYrwhL_-fkuVDGoMgQNRKw,832
+behalf/runner/adk.py,sha256=0ofUAGUfOFz3t6Md-klbIbT_bT12GvMeBPSPrJndXIg,6968
+behalf/runner/sdk.py,sha256=E1KmGUXD9tAeDwzFlv9OsPxT8cn232Gf601HEQxQ7Co,4089
+behalf/runner/strands.py,sha256=XNdk4QCy9dRuSwRcVoeUde8J2_0SSXkS3Wat2lbVbR4,6661
+behalf-0.1.0.dist-info/licenses/LICENSE,sha256=AlyLB1m_z0CENCx1ob0PedLTTohtH2VLZhs2kfygrfc,1108
+behalf-0.1.0.dist-info/licenses/NOTICE,sha256=9CR93geVKl_4ZrJORbXN0fzkEM2y4DglWhY1hn9ZwQw,1167
+behalf-0.1.0.dist-info/METADATA,sha256=6Qq0OjqJzDxRyOHCLNpQ7jzp5M99kPQHvMywAexyJKU,2061
+behalf-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+behalf-0.1.0.dist-info/top_level.txt,sha256=8tZaLJc5ZkQscR9dyCnXL9XgXupfr8DtB2Irt_C7QLs,7
+behalf-0.1.0.dist-info/RECORD,,

behalf-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

behalf-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022-2023 LLNS, LLC and other HPCIC DevTools Developers.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

behalf-0.1.0.dist-info/licenses/NOTICE

@@ -0,0 +1,21 @@
+This work was produced under the auspices of the U.S. Department of
+Energy by Lawrence Livermore National Laboratory under Contract
+DE-AC52-07NA27344.
+
+This work was prepared as an account of work sponsored by an agency of
+the United States Government. Neither the United States Government nor
+Lawrence Livermore National Security, LLC, nor any of their employees
+makes any warranty, expressed or implied, or assumes any legal liability
+or responsibility for the accuracy, completeness, or usefulness of any
+information, apparatus, product, or process disclosed, or represents that
+its use would not infringe privately owned rights.
+
+Reference herein to any specific commercial product, process, or service
+by trade name, trademark, manufacturer, or otherwise does not necessarily
+constitute or imply its endorsement, recommendation, or favoring by the
+United States Government or Lawrence Livermore National Security, LLC.
+
+The views and opinions of authors expressed herein do not necessarily
+state or reflect those of the United States Government or Lawrence
+Livermore National Security, LLC, and shall not be used for advertising
+or product endorsement purposes.

behalf-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+behalf