devagent-physical-engine 0.10.0__py3-none-any.whl

devagent_physical_engine/provider_adapters/gemini.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from ..agent.contracts import ModelRequest, ModelResponse
+from ..agent.runtime import ProviderError, ProviderProtocolError, ProviderUnavailable
+from .common import (
+    DiagnosticsStore,
+    ProviderCallDiagnostics,
+    classify_provider_exception,
+    model_matches,
+    parse_json_object,
+    provider_schema,
+    request_input,
+    require_api_key,
+    safe_token_count,
+)
+
+
+class GeminiProvider:
+    provider_name = "gemini"
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        max_output_tokens: int = 4096,
+        client_factory: Callable[..., Any] | None = None,
+    ) -> None:
+        if not 256 <= max_output_tokens <= 65536:
+            raise ValueError("max_output_tokens_out_of_range")
+        self._api_key = api_key
+        self._max_output_tokens = max_output_tokens
+        self._client_factory = client_factory
+        self._diagnostics = DiagnosticsStore()
+
+    def diagnostics(self, request_id: str) -> ProviderCallDiagnostics | None:
+        return self._diagnostics.get(request_id)
+
+    def _client(self, timeout_s: float) -> Any:
+        key = require_api_key(self._api_key, "GEMINI_API_KEY", "GOOGLE_API_KEY")
+        timeout_ms = max(100, int(timeout_s * 1000))
+        if self._client_factory is not None:
+            return self._client_factory(api_key=key, timeout_ms=timeout_ms)
+        try:
+            from google import genai
+            from google.genai import types
+        except ImportError as exc:
+            raise ProviderUnavailable("sdk_not_installed:google-genai") from exc
+        return genai.Client(
+            api_key=key,
+            http_options=types.HttpOptions(
+                timeout=timeout_ms,
+                retry_options=types.HttpRetryOptions(attempts=1),
+            ),
+        )
+
+    def generate(self, request: ModelRequest, *, model: str) -> ModelResponse:
+        client = None
+        try:
+            client = self._client(request.timeout_s)
+            interaction = client.interactions.create(
+                model=model,
+                system_instruction=request.system_instruction,
+                input=request_input(request),
+                response_format={
+                    "type": "text",
+                    "mime_type": "application/json",
+                    "schema": provider_schema(request.output_schema),
+                },
+                generation_config={"max_output_tokens": self._max_output_tokens},
+                store=False,
+            )
+        except Exception as exc:
+            if isinstance(exc, ProviderError):
+                raise
+            raise classify_provider_exception(exc) from exc
+        finally:
+            if client is not None and self._client_factory is None:
+                close = getattr(client, "close", None)
+                if callable(close):
+                    close()
+
+        request_id = str(getattr(interaction, "id", "") or "")
+        if not request_id:
+            raise ProviderProtocolError("provider_request_id_missing")
+        resolved_model = str(getattr(interaction, "model", "") or "")
+        if not model_matches(model, resolved_model):
+            raise ProviderProtocolError("response_model_identity_mismatch")
+        payload = parse_json_object(getattr(interaction, "output_text", None))
+
+        usage = getattr(interaction, "usage", None) or getattr(
+            interaction, "usage_metadata", None
+        )
+        input_tokens = safe_token_count(
+            getattr(usage, "input_tokens", None) if usage is not None else None
+        )
+        if input_tokens is None and usage is not None:
+            input_tokens = safe_token_count(getattr(usage, "prompt_token_count", None))
+        output_tokens = safe_token_count(
+            getattr(usage, "output_tokens", None) if usage is not None else None
+        )
+        if output_tokens is None and usage is not None:
+            output_tokens = safe_token_count(
+                getattr(usage, "candidates_token_count", None)
+            )
+        total_tokens = safe_token_count(
+            getattr(usage, "total_tokens", None) if usage is not None else None
+        )
+        if total_tokens is None and usage is not None:
+            total_tokens = safe_token_count(getattr(usage, "total_token_count", None))
+        if total_tokens is None and input_tokens is not None and output_tokens is not None:
+            total_tokens = input_tokens + output_tokens
+
+        self._diagnostics.record(
+            ProviderCallDiagnostics(
+                request_id=request_id,
+                provider=self.provider_name,
+                requested_model=model,
+                resolved_model=resolved_model or model,
+                input_tokens=input_tokens,
+                output_tokens=output_tokens,
+                total_tokens=total_tokens,
+            )
+        )
+        return ModelResponse(self.provider_name, model, payload, request_id=request_id)

devagent_physical_engine/provider_adapters/openai.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from ..agent.contracts import ModelRequest, ModelResponse
+from ..agent.runtime import ProviderError, ProviderProtocolError, ProviderUnavailable
+from .common import (
+    DiagnosticsStore,
+    ProviderCallDiagnostics,
+    classify_provider_exception,
+    model_matches,
+    parse_json_object,
+    provider_schema,
+    request_input,
+    require_api_key,
+    safe_token_count,
+)
+
+
+class OpenAIProvider:
+    provider_name = "openai"
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        max_output_tokens: int = 4096,
+        client_factory: Callable[..., Any] | None = None,
+    ) -> None:
+        if not 256 <= max_output_tokens <= 65536:
+            raise ValueError("max_output_tokens_out_of_range")
+        self._api_key = api_key
+        self._max_output_tokens = max_output_tokens
+        self._client_factory = client_factory
+        self._diagnostics = DiagnosticsStore()
+
+    def diagnostics(self, request_id: str) -> ProviderCallDiagnostics | None:
+        return self._diagnostics.get(request_id)
+
+    def _client(self, timeout_s: float) -> Any:
+        key = require_api_key(self._api_key, "OPENAI_API_KEY")
+        if self._client_factory is not None:
+            return self._client_factory(api_key=key, timeout=timeout_s, max_retries=0)
+        try:
+            from openai import OpenAI
+        except ImportError as exc:
+            raise ProviderUnavailable("sdk_not_installed:openai") from exc
+        return OpenAI(api_key=key, timeout=timeout_s, max_retries=0)
+
+    def generate(self, request: ModelRequest, *, model: str) -> ModelResponse:
+        try:
+            response = self._client(request.timeout_s).responses.create(
+                model=model,
+                instructions=request.system_instruction,
+                input=request_input(request),
+                text={
+                    "format": {
+                        "type": "json_schema",
+                        "name": f"devagent_{request.role.value}",
+                        "strict": True,
+                        "schema": provider_schema(request.output_schema),
+                    }
+                },
+                max_output_tokens=self._max_output_tokens,
+                store=False,
+            )
+        except Exception as exc:
+            if isinstance(exc, ProviderError):
+                raise
+            raise classify_provider_exception(exc) from exc
+
+        request_id = str(getattr(response, "id", "") or "")
+        if not request_id:
+            raise ProviderProtocolError("provider_request_id_missing")
+        resolved_model = str(getattr(response, "model", "") or "")
+        if not model_matches(model, resolved_model):
+            raise ProviderProtocolError("response_model_identity_mismatch")
+        payload = parse_json_object(getattr(response, "output_text", None))
+
+        usage = getattr(response, "usage", None)
+        input_tokens = safe_token_count(getattr(usage, "input_tokens", None))
+        output_tokens = safe_token_count(getattr(usage, "output_tokens", None))
+        total_tokens = safe_token_count(getattr(usage, "total_tokens", None))
+        self._diagnostics.record(
+            ProviderCallDiagnostics(
+                request_id=request_id,
+                provider=self.provider_name,
+                requested_model=model,
+                resolved_model=resolved_model or model,
+                input_tokens=input_tokens,
+                output_tokens=output_tokens,
+                total_tokens=total_tokens,
+            )
+        )
+        return ModelResponse(self.provider_name, model, payload, request_id=request_id)

devagent_physical_engine/provider_qualification.py

@@ -0,0 +1,268 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Any, Iterable
+
+from .agent import (
+    AgentRuntime,
+    CriticAgent,
+    ModelRouter,
+    PlannerAgent,
+    PlanningCoordinator,
+    ProviderPool,
+    RecoveryAgent,
+    RequirementInterpreterAgent,
+    RoutingPolicy,
+    RoutingStrategy,
+)
+from .agent.runtime import AgentRuntimeError
+from .execution import ExecutionMode, ExecutionSupervisor
+from .models import WorldState
+from .provider_adapters.common import ProviderCallDiagnostics
+from .providers import ModelRegistry, ModelSpec, QualificationStatus
+from .simulation import DeterministicSimulationBackend
+
+
+@dataclass(frozen=True, slots=True)
+class LiveProviderQualificationReport:
+    provider: str
+    model: str
+    passed: bool
+    request_validated: bool
+    plan_hash: str | None
+    revision_rounds: int | None
+    simulation_completed: bool
+    recovery_decision: str | None
+    agent_calls: int
+    agent_attempts: int
+    input_tokens: int | None
+    output_tokens: int | None
+    total_tokens: int | None
+    failure_code: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def _request_ids(evidence_items: Iterable[Any]) -> tuple[str, ...]:
+    values: list[str] = []
+    for evidence in evidence_items:
+        for attempt in evidence.attempts:
+            if attempt.outcome == "success" and attempt.request_id:
+                values.append(attempt.request_id)
+    return tuple(dict.fromkeys(values))
+
+
+def _attempt_count(evidence_items: Iterable[Any]) -> int:
+    return sum(len(evidence.attempts) for evidence in evidence_items)
+
+
+def _append_exception_evidence(evidence: list[Any], exc: BaseException) -> None:
+    """Preserve bounded AgentEvidence on failure without exposing provider text."""
+    if isinstance(exc, AgentRuntimeError):
+        evidence.append(exc.evidence)
+        return
+    nested = getattr(exc, "__cause__", None)
+    if isinstance(nested, AgentRuntimeError):
+        evidence.append(nested.evidence)
+
+
+def _usage(
+    provider: Any, request_ids: tuple[str, ...]
+) -> tuple[int | None, int | None, int | None]:
+    getter = getattr(provider, "diagnostics", None)
+    if not callable(getter):
+        return None, None, None
+    records: list[ProviderCallDiagnostics] = []
+    for request_id in request_ids:
+        value = getter(request_id)
+        if isinstance(value, ProviderCallDiagnostics):
+            records.append(value)
+    if not records:
+        return None, None, None
+
+    def total(field: str) -> int | None:
+        values = [getattr(item, field) for item in records]
+        if any(value is None for value in values):
+            return None
+        return sum(int(value) for value in values)
+
+    return total("input_tokens"), total("output_tokens"), total("total_tokens")
+
+
+def qualify_live_provider(
+    provider: Any,
+    *,
+    model: str,
+    timeout_s: float = 30.0,
+    max_attempts: int = 2,
+    max_revision_rounds: int = 2,
+) -> LiveProviderQualificationReport:
+    """Run Interpreter -> Planner -> Critic -> verify/simulate -> Recovery.
+
+    The model is deliberately routed as SIMULATION_ONLY for qualification.
+    This never unlocks real execution and never persists qualification state.
+    """
+    provider_name = str(getattr(provider, "provider_name", "") or "").strip().lower()
+    if not provider_name:
+        raise ValueError("provider_name_required")
+    if not model.strip():
+        raise ValueError("model_required")
+
+    registry = ModelRegistry()
+    registry.register(
+        ModelSpec(
+            provider=provider_name,
+            model=model.strip(),
+            status=QualificationStatus.SIMULATION_ONLY,
+            supports_structured_output=True,
+            supports_tools=False,
+            quality_score=0.5,
+            latency_score=0.5,
+            cost_score=0.5,
+            roles=frozenset({"interpreter", "planner", "critic", "recovery"}),
+        )
+    )
+    pool = ProviderPool()
+    pool.register(provider)
+    runtime = AgentRuntime(ModelRouter(registry), pool)
+    policy = RoutingPolicy(
+        strategy=RoutingStrategy.FIXED,
+        fixed_provider=provider_name,
+        fixed_model=model.strip(),
+        max_attempts=max_attempts,
+        timeout_s=timeout_s,
+        require_qualified=False,
+    )
+
+    world = WorldState(facts={"robot_ready", "object_available"})
+    evidence: list[Any] = []
+    request_validated = False
+
+    try:
+        interpreted = RequirementInterpreterAgent(runtime).interpret(
+            "Use the UR5e to load P17 from conveyor_a into cnc_04. Simulate the operation using an engineering test preset.",
+            policy,
+        )
+        evidence.append(interpreted.evidence)
+        if interpreted.validated is None:
+            request_ids = _request_ids(evidence)
+            input_tokens, output_tokens, total_tokens = _usage(provider, request_ids)
+            return LiveProviderQualificationReport(
+                provider=provider_name,
+                model=model,
+                passed=False,
+                request_validated=False,
+                plan_hash=None,
+                revision_rounds=None,
+                simulation_completed=False,
+                recovery_decision=None,
+                agent_calls=len(request_ids),
+                agent_attempts=_attempt_count(evidence),
+                input_tokens=input_tokens,
+                output_tokens=output_tokens,
+                total_tokens=total_tokens,
+                failure_code=(
+                    interpreted.rejection_code or "interpreter_request_not_validated"
+                ),
+            )
+
+        request_validated = True
+        request = interpreted.validated
+        goal = request.goal()
+        robot = request.resource()
+
+        planner = PlannerAgent(runtime)
+        critic = CriticAgent(runtime)
+        coordinator = PlanningCoordinator(
+            planner,
+            critic,
+            max_revision_rounds=max_revision_rounds,
+            min_accept_score=0.70,
+        )
+        recovery = RecoveryAgent(runtime)
+
+        artifact = coordinator.create_verified_plan(
+            goal,
+            [robot],
+            world,
+            policy,
+            policy,
+            engineering_context=request.to_dict(),
+        )
+        evidence.extend(artifact.planner_evidence)
+        evidence.extend(artifact.critic_evidence)
+
+        simulation_world = WorldState(facts=set(world.facts), values=dict(world.values))
+        simulation = ExecutionSupervisor().execute(
+            artifact.graph,
+            [robot],
+            simulation_world,
+            DeterministicSimulationBackend(),
+            ExecutionMode.SIMULATION,
+        )
+        if not simulation.completed:
+            request_ids = _request_ids(evidence)
+            input_tokens, output_tokens, total_tokens = _usage(provider, request_ids)
+            return LiveProviderQualificationReport(
+                provider=provider_name,
+                model=model,
+                passed=False,
+                request_validated=True,
+                plan_hash=artifact.graph_hash,
+                revision_rounds=artifact.revision_rounds,
+                simulation_completed=False,
+                recovery_decision=None,
+                agent_calls=len(request_ids),
+                agent_attempts=_attempt_count(evidence),
+                input_tokens=input_tokens,
+                output_tokens=output_tokens,
+                total_tokens=total_tokens,
+                failure_code="deterministic_simulation_failed",
+            )
+
+        recovered = recovery.advise(
+            task_id="T2",
+            issue_codes=("state_unknown",),
+            world=world,
+            policy=policy,
+        )
+        evidence.append(recovered.evidence)
+        request_ids = _request_ids(evidence)
+        input_tokens, output_tokens, total_tokens = _usage(provider, request_ids)
+        return LiveProviderQualificationReport(
+            provider=provider_name,
+            model=model,
+            passed=True,
+            request_validated=True,
+            plan_hash=artifact.graph_hash,
+            revision_rounds=artifact.revision_rounds,
+            simulation_completed=True,
+            recovery_decision=recovered.advice.decision.value,
+            agent_calls=len(request_ids),
+            agent_attempts=_attempt_count(evidence),
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            total_tokens=total_tokens,
+            failure_code=None,
+        )
+    except Exception as exc:
+        _append_exception_evidence(evidence, exc)
+        request_ids = _request_ids(evidence)
+        input_tokens, output_tokens, total_tokens = _usage(provider, request_ids)
+        return LiveProviderQualificationReport(
+            provider=provider_name,
+            model=model,
+            passed=False,
+            request_validated=request_validated,
+            plan_hash=None,
+            revision_rounds=None,
+            simulation_completed=False,
+            recovery_decision=None,
+            agent_calls=len(request_ids),
+            agent_attempts=_attempt_count(evidence),
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            total_tokens=total_tokens,
+            failure_code=f"qualification_failed:{type(exc).__name__}",
+        )

devagent_physical_engine/providers.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Protocol
+
+from .models import Goal, Resource, TaskGraph
+
+
+class QualificationStatus(str, Enum):
+    QUALIFIED = "qualified"
+    SIMULATION_ONLY = "simulation_only"
+    NOT_TESTED = "not_tested"
+    BLOCKED = "blocked"
+
+
+@dataclass(frozen=True, slots=True)
+class ModelSpec:
+    """Model capabilities and qualification data used by the routing layer.
+
+    Scores are normalized to ``[0, 1]`` and intentionally provider-independent.
+    A higher score is always better: higher quality, lower latency, or lower cost.
+    """
+
+    provider: str
+    model: str
+    status: QualificationStatus
+    supports_structured_output: bool = True
+    supports_tools: bool = True
+    private: bool = False
+    quality_score: float = 0.5
+    latency_score: float = 0.5
+    cost_score: float = 0.5
+    roles: frozenset[str] = frozenset()
+
+    def __post_init__(self) -> None:
+        provider = self.provider.strip().lower()
+        model = self.model.strip()
+        if not provider or not model:
+            raise ValueError("provider_and_model_required")
+
+        for name, value in (
+            ("quality_score", self.quality_score),
+            ("latency_score", self.latency_score),
+            ("cost_score", self.cost_score),
+        ):
+            if not 0.0 <= value <= 1.0:
+                raise ValueError(f"{name}_out_of_range")
+
+        normalized_roles = frozenset(
+            role.strip().lower() for role in self.roles if role.strip()
+        )
+        object.__setattr__(self, "provider", provider)
+        object.__setattr__(self, "model", model)
+        object.__setattr__(self, "roles", normalized_roles)
+
+    @property
+    def key(self) -> tuple[str, str]:
+        return self.provider, self.model
+
+    def supports_role(self, role: str) -> bool:
+        normalized = role.strip().lower()
+        return not self.roles or normalized in self.roles
+
+
+class PlannerModel(Protocol):
+    def generate_task_graph(
+        self, goal: Goal, resources: list[Resource]
+    ) -> TaskGraph: ...
+
+
+class ModelRegistry:
+    """In-memory qualification registry with deterministic duplicate handling."""
+
+    def __init__(self) -> None:
+        self._models: dict[tuple[str, str], ModelSpec] = {}
+
+    def register(self, spec: ModelSpec, *, replace: bool = False) -> None:
+        if spec.key in self._models and not replace:
+            raise ValueError(f"duplicate_model:{spec.provider}:{spec.model}")
+        self._models[spec.key] = spec
+
+    def get(self, provider: str, model: str) -> ModelSpec:
+        key = (provider.strip().lower(), model.strip())
+        try:
+            return self._models[key]
+        except KeyError as exc:
+            raise KeyError(f"unregistered_model:{key[0]}:{key[1]}") from exc
+
+    def all(self) -> tuple[ModelSpec, ...]:
+        return tuple(self._models.values())
+
+    def real_execution_allowed(self, provider: str, model: str) -> bool:
+        return self.get(provider, model).status is QualificationStatus.QUALIFIED

devagent_physical_engine/qualification.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .execution import ExecutionMode, ExecutionSupervisor
+from .models import Goal, WorldState
+from .planning import CapabilityPlanner
+from .robots import CATALOG
+from .simulation import DeterministicSimulationBackend
+
+
+@dataclass(frozen=True, slots=True)
+class QualificationCaseResult:
+    robot: str
+    passed: bool
+    executed_tasks: int
+    violations: int
+
+
+@dataclass(frozen=True, slots=True)
+class QualificationSummary:
+    cases: tuple[QualificationCaseResult, ...]
+
+    @property
+    def passed(self) -> bool:
+        return all(case.passed for case in self.cases)
+
+    @property
+    def violations(self) -> int:
+        return sum(case.violations for case in self.cases)
+
+
+def run_cross_vendor_smoke() -> QualificationSummary:
+    planner = CapabilityPlanner()
+    supervisor = ExecutionSupervisor()
+    goal = Goal("G1", "load", "P17", "conveyor_a", "cnc_04")
+    results: list[QualificationCaseResult] = []
+    for robot_name, factory in CATALOG.items():
+        resource = factory()
+        graph = planner.plan(goal, [resource])
+        world = WorldState(facts={"robot_ready", "object_available"})
+        report = supervisor.execute(graph, [resource], world, DeterministicSimulationBackend(), ExecutionMode.SIMULATION)
+        results.append(QualificationCaseResult(robot_name, report.completed, len(report.executed_tasks), len(report.issues)))
+    return QualificationSummary(tuple(results))