agentdeploy 0.1.1__py3-none-any.whl

agentdeploy/core/deploy.py

@@ -0,0 +1,96 @@
+"""
+deploy() — the fluent builder that returns the right DeployTarget.
+
+Usage:
+    deploy(app).to_kubernetes(...).build()
+    deploy(app).to_docker_compose(...).build()
+    deploy(app).to_lambda(...).build()
+    deploy(app).to_cloud_run(...).build()
+"""
+
+from __future__ import annotations
+
+from agentdeploy.core.app import AgentApp
+from agentdeploy.targets.cloud_run import CloudRunTarget
+from agentdeploy.targets.docker_compose import DockerComposeTarget
+from agentdeploy.targets.kubernetes import KubernetesTarget
+from agentdeploy.targets.lambda_target import LambdaTarget
+
+
+class DeployBuilder:
+    """
+    Fluent entry point returned by deploy(app).
+    Choose a target then chain configuration methods.
+    """
+
+    def __init__(self, app: AgentApp) -> None:
+        self._app = app
+
+    def to_kubernetes(
+        self,
+        *,
+        namespace: str = "default",
+        image: str = "",
+        registry: str = "",
+    ) -> KubernetesTarget:
+        return KubernetesTarget(
+            app=self._app,
+            namespace=namespace,
+            image=image or f"{self._app.name}:{self._app.version}",
+            registry=registry,
+        )
+
+    def to_docker_compose(
+        self,
+        *,
+        output_dir: str = ".",
+        network: str = "agent-net",
+    ) -> DockerComposeTarget:
+        return DockerComposeTarget(
+            app=self._app,
+            output_dir=output_dir,
+            network=network,
+        )
+
+    def to_lambda(
+        self,
+        *,
+        region: str = "us-east-1",
+        function_name: str = "",
+        role_arn: str = "",
+    ) -> LambdaTarget:
+        return LambdaTarget(
+            app=self._app,
+            region=region,
+            function_name=function_name or self._app.name,
+            role_arn=role_arn,
+        )
+
+    def to_cloud_run(
+        self,
+        *,
+        project: str,
+        region: str = "us-central1",
+        service_name: str = "",
+    ) -> CloudRunTarget:
+        return CloudRunTarget(
+            app=self._app,
+            project=project,
+            region=region,
+            service_name=service_name or self._app.name,
+        )
+
+
+def deploy(app: AgentApp) -> DeployBuilder:
+    """
+    Start a deployment pipeline for an AgentApp.
+
+    Returns a DeployBuilder — call .to_kubernetes(), .to_docker_compose(),
+    .to_lambda(), or .to_cloud_run() to select your target.
+    """
+    if app._agent is None:
+        raise ValueError(
+            f"AgentApp '{app.name}' has no wrapped agent. "
+            "Call app.wrap(your_agent) before deploying."
+        )
+    return DeployBuilder(app)

agentdeploy/core/hitl.py

@@ -0,0 +1,203 @@
+"""
+HITLGate — Human-in-the-Loop gate primitive.
+
+Agents call gate.checkpoint(state) at decision points.
+If the gate is armed, execution pauses and waits for a human
+decision (approve / reject / modify) before continuing.
+
+Delivery channels:
+  - Webhook (any HTTP endpoint)
+  - Slack (via incoming webhook URL)
+  - Console (for local dev — prints and waits for stdin)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import logging
+import time
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class HITLDecision(StrEnum):
+    APPROVE = "approve"
+    REJECT = "reject"
+    MODIFY = "modify"
+
+
+@dataclass
+class HITLConfig:
+    webhook: str = ""
+    slack_channel: str = ""
+    timeout_seconds: int = 3600
+
+
+@dataclass
+class CheckpointResult:
+    decision: HITLDecision
+    modified_state: Any = None
+    reviewer: str = ""
+    reason: str = ""
+    reviewed_at: float = field(default_factory=time.time)
+
+
+class HITLGate:
+    """
+    Add human oversight to any agent at a checkpoint.
+
+    Usage:
+        gate = HITLGate(webhook="https://yourapp.com/approve")
+
+        # Inside your agent or orchestrator:
+        result = await gate.checkpoint(
+            state=current_state,
+            description="Agent is about to call the payments API",
+        )
+        if result.decision == HITLDecision.REJECT:
+            return "Cancelled by reviewer"
+        state = result.modified_state or current_state
+    """
+
+    def __init__(
+        self,
+        *,
+        webhook: str = "",
+        slack_webhook: str = "",
+        timeout_seconds: int = 3600,
+        auto_approve_after: int | None = None,
+        console_fallback: bool = True,
+    ) -> None:
+        self.webhook = webhook
+        self.slack_webhook = slack_webhook
+        self.timeout_seconds = timeout_seconds
+        self.auto_approve_after = auto_approve_after
+        self.console_fallback = console_fallback
+        self._pending: dict[str, asyncio.Future] = {}
+
+    async def checkpoint(
+        self,
+        state: Any,
+        *,
+        description: str = "",
+        run_id: str = "",
+    ) -> CheckpointResult:
+        """
+        Pause execution and wait for a human decision.
+
+        Returns a CheckpointResult with the decision and
+        optionally a modified state from the reviewer.
+        """
+        checkpoint_id = run_id or f"cp-{int(time.time() * 1000)}"
+        payload = {
+            "checkpoint_id": checkpoint_id,
+            "description": description,
+            "state": state if isinstance(state, (str, int, float, bool)) else str(state),
+        }
+
+        if self.webhook:
+            return await self._wait_for_webhook(checkpoint_id, payload)
+        elif self.slack_webhook:
+            return await self._notify_slack(checkpoint_id, payload)
+        elif self.console_fallback:
+            return await self._console_prompt(payload)
+        else:
+            logger.warning("HITLGate has no delivery channel — auto-approving.")
+            return CheckpointResult(decision=HITLDecision.APPROVE)
+
+    async def resolve(self, checkpoint_id: str, result: CheckpointResult) -> None:
+        """
+        Called by your webhook handler when the reviewer responds.
+        Use this in your FastAPI/Flask route that receives approvals.
+
+        Example:
+            @app.post("/approve/{checkpoint_id}")
+            async def approve(checkpoint_id: str, body: ApproveBody):
+                result = CheckpointResult(decision=HITLDecision.APPROVE, reviewer=body.user)
+                await gate.resolve(checkpoint_id, result)
+        """
+        future = self._pending.get(checkpoint_id)
+        if future and not future.done():
+            future.set_result(result)
+
+    async def _wait_for_webhook(self, checkpoint_id: str, payload: dict) -> CheckpointResult:
+        import httpx
+
+        loop = asyncio.get_event_loop()
+        future: asyncio.Future[CheckpointResult] = loop.create_future()
+        self._pending[checkpoint_id] = future
+
+        try:
+            async with httpx.AsyncClient() as client:
+                await client.post(
+                    self.webhook,
+                    json={**payload, "callback_id": checkpoint_id},
+                    timeout=10,
+                )
+        except Exception as e:
+            logger.error(f"HITLGate webhook delivery failed: {e}")
+
+        try:
+            return await asyncio.wait_for(future, timeout=self.timeout_seconds)
+        except TimeoutError:
+            logger.warning(f"HITLGate checkpoint {checkpoint_id} timed out.")
+            if self.auto_approve_after and self.timeout_seconds >= self.auto_approve_after:
+                return CheckpointResult(
+                    decision=HITLDecision.APPROVE,
+                    reason="auto-approved after timeout",
+                )
+            return CheckpointResult(
+                decision=HITLDecision.REJECT,
+                reason="timed out waiting for human review",
+            )
+        finally:
+            self._pending.pop(checkpoint_id, None)
+
+    async def _notify_slack(self, checkpoint_id: str, payload: dict) -> CheckpointResult:
+        import httpx
+
+        message = {
+            "text": f"*HITL checkpoint* `{checkpoint_id}`\n{payload.get('description', '')}\n"
+            f"State: ```{payload.get('state', '')}```\n"
+            f"Reply with `/approve {checkpoint_id}` or `/reject {checkpoint_id}`"
+        }
+        try:
+            async with httpx.AsyncClient() as client:
+                await client.post(self.slack_webhook, json=message, timeout=10)
+        except Exception as e:
+            logger.error(f"Slack delivery failed: {e}")
+
+        loop = asyncio.get_event_loop()
+        future: asyncio.Future[CheckpointResult] = loop.create_future()
+        self._pending[checkpoint_id] = future
+        try:
+            return await asyncio.wait_for(future, timeout=self.timeout_seconds)
+        except TimeoutError:
+            return CheckpointResult(
+                decision=HITLDecision.REJECT,
+                reason="timed out waiting for Slack response",
+            )
+        finally:
+            self._pending.pop(checkpoint_id, None)
+
+    async def _console_prompt(self, payload: dict) -> CheckpointResult:
+        print(f"\n[HITLGate] Checkpoint: {payload.get('description', '')}")
+        print(f"State: {payload.get('state', '')}")
+        choice = input("Decision [approve/reject/modify]: ").strip().lower()
+        if choice.startswith("a"):
+            return CheckpointResult(decision=HITLDecision.APPROVE, reviewer="console")
+        elif choice.startswith("m"):
+            modified: Any = input("Enter modified state (JSON or string): ").strip()
+            with contextlib.suppress(json.JSONDecodeError):
+                modified = json.loads(modified)
+            return CheckpointResult(
+                decision=HITLDecision.MODIFY,
+                modified_state=modified,
+                reviewer="console",
+            )
+        return CheckpointResult(decision=HITLDecision.REJECT, reviewer="console")

agentdeploy/core/observability.py

@@ -0,0 +1,160 @@
+"""
+Telemetry — wraps OpenTelemetry tracing for agent runs.
+
+Automatically instruments:
+  - Per-run spans with agent name, framework, input/output tokens
+  - Cost estimation per provider
+  - Failure traces with exception capture
+
+Usage:
+    telemetry = Telemetry(service_name="my-agent")
+
+    async with telemetry.trace("invoke", input=user_input) as span:
+        result = await my_agent.invoke(user_input)
+        span.set_tokens(prompt=512, completion=128, model="gpt-4o")
+    # Span is ended automatically, cost is calculated and logged
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from typing import Any
+
+try:
+    from opentelemetry import trace
+    from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
+    from opentelemetry.sdk.trace import TracerProvider
+    from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+    OTEL_AVAILABLE = True
+except ImportError:
+    OTEL_AVAILABLE = False
+
+
+COST_PER_1K_TOKENS: dict[str, dict[str, float]] = {
+    "gpt-4o": {"prompt": 0.005, "completion": 0.015},
+    "gpt-4o-mini": {"prompt": 0.00015, "completion": 0.0006},
+    "claude-sonnet-4-6": {"prompt": 0.003, "completion": 0.015},
+    "claude-opus-4-6": {"prompt": 0.015, "completion": 0.075},
+    "gemini-1.5-pro": {"prompt": 0.0035, "completion": 0.0105},
+}
+
+
+@dataclass
+class OtelConfig:
+    endpoint: str = "http://localhost:4317"
+    service_name: str = "agentdeploy"
+
+
+class AgentSpan:
+    """Thin wrapper around an OTel span with agent-specific helpers."""
+
+    def __init__(self, span: Any, start_time: float) -> None:
+        self._span = span
+        self._start_time = start_time
+        self._prompt_tokens = 0
+        self._completion_tokens = 0
+        self._model = ""
+
+    def set_tokens(
+        self,
+        *,
+        prompt: int = 0,
+        completion: int = 0,
+        model: str = "",
+    ) -> None:
+        self._prompt_tokens = prompt
+        self._completion_tokens = completion
+        self._model = model
+        if self._span and OTEL_AVAILABLE:
+            self._span.set_attribute("llm.prompt_tokens", prompt)
+            self._span.set_attribute("llm.completion_tokens", completion)
+            self._span.set_attribute("llm.model", model)
+            cost = self._estimate_cost(prompt, completion, model)
+            if cost is not None:
+                self._span.set_attribute("llm.cost_usd", round(cost, 6))
+
+    def set_attribute(self, key: str, value: Any) -> None:
+        if self._span and OTEL_AVAILABLE:
+            self._span.set_attribute(key, value)
+
+    def record_exception(self, exc: Exception) -> None:
+        if self._span and OTEL_AVAILABLE:
+            self._span.record_exception(exc)
+
+    @property
+    def elapsed_ms(self) -> float:
+        return (time.perf_counter() - self._start_time) * 1000
+
+    def _estimate_cost(self, prompt: int, completion: int, model: str) -> float | None:
+        rates = COST_PER_1K_TOKENS.get(model)
+        if not rates:
+            return None
+        return (prompt / 1000 * rates["prompt"]) + (completion / 1000 * rates["completion"])
+
+
+class Telemetry:
+    """
+    Agent telemetry wrapper. Initialise once per service, then
+    use as an async context manager around agent invocations.
+    """
+
+    def __init__(
+        self,
+        service_name: str,
+        *,
+        otel_endpoint: str = "",
+        enabled: bool = True,
+    ) -> None:
+        self.service_name = service_name
+        self.enabled = enabled and OTEL_AVAILABLE
+        self._tracer = None
+
+        if self.enabled and otel_endpoint:
+            provider = TracerProvider()
+            exporter = OTLPSpanExporter(endpoint=otel_endpoint, insecure=True)
+            provider.add_span_processor(BatchSpanProcessor(exporter))
+            trace.set_tracer_provider(provider)
+            self._tracer = trace.get_tracer(service_name)
+
+    @asynccontextmanager
+    async def trace(
+        self,
+        operation: str,
+        *,
+        input: Any = None,
+        agent_name: str = "",
+        framework: str = "",
+    ) -> AsyncGenerator[AgentSpan, None]:
+        """
+        Async context manager that wraps an agent operation in a span.
+
+        async with telemetry.trace("invoke", input=user_msg) as span:
+            result = await agent.run(user_msg)
+            span.set_tokens(prompt=100, completion=50, model="claude-sonnet-4-6")
+        """
+        start = time.perf_counter()
+
+        if self.enabled and self._tracer:
+            with self._tracer.start_as_current_span(
+                f"{self.service_name}.{operation}"
+            ) as otel_span:
+                if agent_name:
+                    otel_span.set_attribute("agent.name", agent_name)
+                if framework:
+                    otel_span.set_attribute("agent.framework", framework)
+                agent_span = AgentSpan(otel_span, start)
+                try:
+                    yield agent_span
+                except Exception as e:
+                    agent_span.record_exception(e)
+                    raise
+        else:
+            agent_span = AgentSpan(None, start)
+            try:
+                yield agent_span
+            except Exception:
+                raise

agentdeploy/targets/__init__.py

@@ -0,0 +1,17 @@
+"""Deployment targets: Kubernetes, Docker Compose, AWS Lambda, Google Cloud Run."""
+
+from agentdeploy.targets.cloud_run import CloudRunResult, CloudRunTarget
+from agentdeploy.targets.docker_compose import DockerComposeResult, DockerComposeTarget
+from agentdeploy.targets.kubernetes import BuildResult, KubernetesTarget
+from agentdeploy.targets.lambda_target import LambdaResult, LambdaTarget
+
+__all__ = [
+    "KubernetesTarget",
+    "BuildResult",
+    "DockerComposeTarget",
+    "DockerComposeResult",
+    "LambdaTarget",
+    "LambdaResult",
+    "CloudRunTarget",
+    "CloudRunResult",
+]

agentdeploy/targets/cloud_run.py

@@ -0,0 +1,128 @@
+"""
+CloudRunTarget — generates a Dockerfile and Cloud Run service YAML
+for GCP serverless deployment.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+from agentdeploy.core.app import AgentApp
+
+
+@dataclass
+class CloudRunTarget:
+    app: AgentApp
+    project: str = ""
+    region: str = "us-central1"
+    service_name: str = ""
+
+    _max_instances: int = field(default=10, init=False)
+    _min_instances: int = field(default=0, init=False)
+    _concurrency: int = field(default=80, init=False)
+    _output_dir: str = field(default="./deploy", init=False)
+
+    def with_scaling(
+        self,
+        *,
+        min_instances: int = 0,
+        max_instances: int = 10,
+        concurrency: int = 80,
+    ) -> CloudRunTarget:
+        self._min_instances = min_instances
+        self._max_instances = max_instances
+        self._concurrency = concurrency
+        return self
+
+    def with_output_dir(self, path: str) -> CloudRunTarget:
+        self._output_dir = path
+        return self
+
+    def build(self) -> CloudRunResult:
+        cfg = self.app.to_config()
+        adapter = self.app._adapter
+        svc = self.service_name or cfg.name
+        image = f"gcr.io/{self.project}/{svc}:{cfg.version}"
+
+        out = Path(self._output_dir) / cfg.name
+        out.mkdir(parents=True, exist_ok=True)
+
+        extras = " ".join(adapter.pip_extras())
+        dockerfile = f"""FROM python:3.11-slim
+WORKDIR /app
+RUN pip install --no-cache-dir fastapi uvicorn {extras}
+COPY . .
+EXPOSE {self.app._port}
+CMD ["python", "server.py"]
+"""
+        (out / "Dockerfile").write_text(dockerfile)
+        server_code = adapter.entrypoint_code(cfg.name, self.app._port)
+        (out / "server.py").write_text(server_code)
+
+        service_yaml = self._service_manifest(cfg, svc, image)
+        svc_path = out / "service.yaml"
+        svc_path.write_text(yaml.dump(service_yaml, default_flow_style=False))
+
+        return CloudRunResult(
+            app_name=cfg.name,
+            output_dir=str(out),
+            image=image,
+            next_steps=[
+                f"gcloud builds submit --tag {image}",
+                f"gcloud run services replace {svc_path} --region {self.region}",
+                f"gcloud run services add-iam-policy-binding {svc} "
+                f"--region {self.region} --member allUsers --role roles/run.invoker",
+            ],
+        )
+
+    def _service_manifest(self, cfg, svc: str, image: str) -> dict:
+        env_vars = [{"name": k, "value": v} for k, v in cfg.env_vars.items()]
+        return {
+            "apiVersion": "serving.knative.dev/v1",
+            "kind": "Service",
+            "metadata": {
+                "name": svc,
+                "annotations": {
+                    "run.googleapis.com/ingress": "all",
+                    "run.googleapis.com/region": self.region,
+                },
+            },
+            "spec": {
+                "template": {
+                    "metadata": {
+                        "annotations": {
+                            "autoscaling.knative.dev/minScale": str(self._min_instances),
+                            "autoscaling.knative.dev/maxScale": str(self._max_instances),
+                        }
+                    },
+                    "spec": {
+                        "containerConcurrency": self._concurrency,
+                        "timeoutSeconds": cfg.timeout_seconds,
+                        "containers": [
+                            {
+                                "image": image,
+                                "ports": [{"containerPort": self.app._port}],
+                                "env": env_vars,
+                                "resources": {
+                                    "limits": {
+                                        "memory": f"{cfg.memory_mb}Mi",
+                                        "cpu": "1000m",
+                                    }
+                                },
+                            }
+                        ],
+                    },
+                }
+            },
+        }
+
+
+@dataclass
+class CloudRunResult:
+    app_name: str
+    output_dir: str
+    image: str
+    next_steps: list[str]