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

devagent_physical_engine/agent/structured.py

@@ -0,0 +1,423 @@
+from __future__ import annotations
+
+import json
+from math import isfinite
+from typing import Any, Mapping
+
+from .contracts import CriticDecision, Critique, RecoveryAdvice, RecoveryDecision
+from ..models import ActionContract, Capability, TaskGraph, TaskNode
+
+MAX_TASKS = 64
+MAX_ITEMS = 32
+MAX_TEXT = 512
+MAX_JSON_DEPTH = 8
+MAX_JSON_ITEMS = 256
+MAX_JSON_TEXT = 8192
+
+
+class StructuredOutputError(ValueError):
+    pass
+
+
+class JsonSafetyError(ValueError):
+    pass
+
+
+def json_safe(value: Any, *, path: str = "root", depth: int = 0) -> Any:
+    """Return a JSON-safe copy or reject unsupported/unbounded input."""
+
+    if depth > MAX_JSON_DEPTH:
+        raise JsonSafetyError(f"json_depth_exceeded:{path}")
+    if value is None or isinstance(value, (bool, int)):
+        return value
+    if isinstance(value, float):
+        if not isfinite(value):
+            raise JsonSafetyError(f"non_finite_number:{path}")
+        return value
+    if isinstance(value, str):
+        if len(value) > MAX_JSON_TEXT:
+            raise JsonSafetyError(f"json_text_too_long:{path}")
+        return value
+    if isinstance(value, (list, tuple)):
+        if len(value) > MAX_JSON_ITEMS:
+            raise JsonSafetyError(f"json_array_too_large:{path}")
+        return [
+            json_safe(item, path=f"{path}[{index}]", depth=depth + 1)
+            for index, item in enumerate(value)
+        ]
+    if isinstance(value, Mapping):
+        if len(value) > MAX_JSON_ITEMS:
+            raise JsonSafetyError(f"json_object_too_large:{path}")
+        output: dict[str, Any] = {}
+        for key, item in value.items():
+            if not isinstance(key, str) or not key:
+                raise JsonSafetyError(f"json_key_invalid:{path}")
+            if len(key) > 256:
+                raise JsonSafetyError(f"json_key_too_long:{path}")
+            output[key] = json_safe(
+                item, path=f"{path}.{key}", depth=depth + 1
+            )
+        return output
+    raise JsonSafetyError(f"json_type_unsupported:{path}:{type(value).__name__}")
+
+
+SENSITIVE_KEY_PARTS = (
+    "api_key",
+    "apikey",
+    "authorization",
+    "credential",
+    "password",
+    "private_key",
+    "secret",
+    "token",
+)
+
+
+def redact_sensitive(
+    value: Any,
+    *,
+    path: str = "root",
+    depth: int = 0,
+    seen: set[int] | None = None,
+) -> Any:
+    """Redact common credential-shaped fields before model invocation.
+
+    This is defense in depth, not a substitute for keeping credentials out of
+    the world model and resource metadata entirely. JSON validation happens
+    after redaction so secret-shaped unsupported objects are never serialized.
+    """
+
+    if depth > MAX_JSON_DEPTH:
+        raise JsonSafetyError(f"redaction_depth_exceeded:{path}")
+
+    if seen is None:
+        seen = set()
+
+    if isinstance(value, Mapping):
+        identity = id(value)
+        if identity in seen:
+            raise JsonSafetyError(f"cyclic_context:{path}")
+        seen.add(identity)
+        try:
+            output: dict[Any, Any] = {}
+            for key, child in value.items():
+                if isinstance(key, str):
+                    normalized_key = key.lower().replace("-", "_")
+                    if any(
+                        part in normalized_key for part in SENSITIVE_KEY_PARTS
+                    ):
+                        output[key] = "<redacted>"
+                        continue
+                output[key] = redact_sensitive(
+                    child,
+                    path=f"{path}.{key}",
+                    depth=depth + 1,
+                    seen=seen,
+                )
+            return output
+        finally:
+            seen.remove(identity)
+
+    if isinstance(value, (list, tuple)):
+        identity = id(value)
+        if identity in seen:
+            raise JsonSafetyError(f"cyclic_context:{path}")
+        seen.add(identity)
+        try:
+            return [
+                redact_sensitive(
+                    child,
+                    path=f"{path}[{index}]",
+                    depth=depth + 1,
+                    seen=seen,
+                )
+                for index, child in enumerate(value)
+            ]
+        finally:
+            seen.remove(identity)
+
+    return value
+
+
+def _object(value: Any, name: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping):
+        raise StructuredOutputError(f"{name}_must_be_object")
+    return value
+
+
+def _text(value: Any, name: str, *, required: bool = True) -> str | None:
+    if value is None and not required:
+        return None
+    if not isinstance(value, str):
+        raise StructuredOutputError(f"{name}_must_be_string")
+    normalized = value.strip()
+    if required and not normalized:
+        raise StructuredOutputError(f"{name}_required")
+    if len(normalized) > MAX_TEXT:
+        raise StructuredOutputError(f"{name}_too_long")
+    return normalized
+
+
+def _string_tuple(value: Any, name: str) -> tuple[str, ...]:
+    if value is None:
+        return ()
+    if not isinstance(value, list):
+        raise StructuredOutputError(f"{name}_must_be_array")
+    if len(value) > MAX_ITEMS:
+        raise StructuredOutputError(f"{name}_too_many_items")
+
+    items: list[str] = []
+    for item in value:
+        normalized = _text(item, name)
+        if normalized is None:  # defensive; required=True above
+            raise StructuredOutputError(f"{name}_required")
+        items.append(normalized)
+    if len(items) != len(set(items)):
+        raise StructuredOutputError(f"{name}_contains_duplicates")
+    return tuple(items)
+
+
+def _reject_unknown(
+    obj: Mapping[str, Any], allowed: set[str], name: str
+) -> None:
+    extra = set(obj) - allowed
+    if extra:
+        raise StructuredOutputError(
+            f"{name}_unknown_fields:{','.join(sorted(extra))}"
+        )
+
+
+TASK_GRAPH_SCHEMA = {
+    "type": "object",
+    "additionalProperties": False,
+    "required": ["goal_id", "tasks"],
+    "properties": {
+        "goal_id": {"type": "string", "minLength": 1, "maxLength": MAX_TEXT},
+        "tasks": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": MAX_TASKS,
+            "items": {
+                "type": "object",
+                "additionalProperties": False,
+                "required": ["task_id", "action", "resource_id"],
+                "properties": {
+                    "task_id": {"type": "string", "minLength": 1, "maxLength": MAX_TEXT},
+                    "action": {"enum": [capability.value for capability in Capability]},
+                    "resource_id": {"type": "string", "minLength": 1, "maxLength": MAX_TEXT},
+                    "object_id": {"type": ["string", "null"], "maxLength": MAX_TEXT},
+                    "source": {"type": ["string", "null"], "maxLength": MAX_TEXT},
+                    "destination": {"type": ["string", "null"], "maxLength": MAX_TEXT},
+                    "preconditions": {"type": "array", "maxItems": MAX_ITEMS, "items": {"type": "string", "minLength": 1, "maxLength": MAX_TEXT}, "uniqueItems": True},
+                    "expected_effects": {"type": "array", "maxItems": MAX_ITEMS, "items": {"type": "string", "minLength": 1, "maxLength": MAX_TEXT}, "uniqueItems": True},
+                    "constraints": {"type": "array", "maxItems": MAX_ITEMS, "items": {"type": "string", "minLength": 1, "maxLength": MAX_TEXT}, "uniqueItems": True},
+                    "timeout_ms": {"type": "integer", "minimum": 1, "maximum": 300_000},
+                    "depends_on": {"type": "array", "maxItems": MAX_ITEMS, "items": {"type": "string", "minLength": 1, "maxLength": MAX_TEXT}, "uniqueItems": True},
+                },
+            },
+        },
+    },
+}
+
+
+CRITIQUE_SCHEMA = {
+    "type": "object",
+    "additionalProperties": False,
+    "required": ["decision", "score", "issues"],
+    "properties": {
+        "decision": {"enum": [decision.value for decision in CriticDecision]},
+        "score": {"type": "number", "minimum": 0, "maximum": 1},
+        "issues": {
+            "type": "array",
+            "maxItems": 16,
+            "items": {"type": "string"},
+        },
+    },
+}
+
+RECOVERY_SCHEMA = {
+    "type": "object",
+    "additionalProperties": False,
+    "required": ["decision", "reason"],
+    "properties": {
+        "decision": {"enum": [decision.value for decision in RecoveryDecision]},
+        "reason": {"type": "string"},
+        "retry_after_ms": {
+            "type": ["integer", "null"],
+            "minimum": 0,
+            "maximum": 60_000,
+        },
+    },
+}
+
+
+def parse_task_graph(
+    payload: Mapping[str, Any], *, expected_goal_id: str | None = None
+) -> TaskGraph:
+    obj = _object(payload, "task_graph")
+    _reject_unknown(obj, {"goal_id", "tasks"}, "task_graph")
+
+    goal_id = _text(obj.get("goal_id"), "goal_id")
+    if goal_id is None:  # defensive; required=True above
+        raise StructuredOutputError("goal_id_required")
+    if expected_goal_id is not None and goal_id != expected_goal_id:
+        raise StructuredOutputError("goal_id_mismatch")
+
+    raw_tasks = obj.get("tasks")
+    if not isinstance(raw_tasks, list):
+        raise StructuredOutputError("tasks_must_be_array")
+    if not raw_tasks:
+        raise StructuredOutputError("tasks_required")
+    if len(raw_tasks) > MAX_TASKS:
+        raise StructuredOutputError("too_many_tasks")
+
+    allowed = {
+        "task_id",
+        "action",
+        "resource_id",
+        "object_id",
+        "source",
+        "destination",
+        "preconditions",
+        "expected_effects",
+        "constraints",
+        "timeout_ms",
+        "depends_on",
+    }
+    tasks: list[TaskNode] = []
+
+    for index, raw in enumerate(raw_tasks):
+        item = _object(raw, f"task_{index}")
+        _reject_unknown(item, allowed, f"task_{index}")
+
+        action_text = _text(item.get("action"), f"task_{index}.action")
+        if action_text is None:
+            raise StructuredOutputError(f"task_{index}.action_required")
+        try:
+            action = Capability(action_text)
+        except ValueError as exc:
+            raise StructuredOutputError(
+                f"task_{index}.unsupported_action:{action_text}"
+            ) from exc
+
+        timeout_ms = item.get("timeout_ms", 10_000)
+        if (
+            isinstance(timeout_ms, bool)
+            or not isinstance(timeout_ms, int)
+            or not 1 <= timeout_ms <= 300_000
+        ):
+            raise StructuredOutputError(f"task_{index}.invalid_timeout")
+
+        resource_id = _text(
+            item.get("resource_id"), f"task_{index}.resource_id"
+        )
+        task_id = _text(item.get("task_id"), f"task_{index}.task_id")
+        if resource_id is None or task_id is None:
+            raise StructuredOutputError(f"task_{index}.required_field_missing")
+
+        contract = ActionContract(
+            action=action,
+            resource_id=resource_id,
+            object_id=_text(
+                item.get("object_id"), f"task_{index}.object_id", required=False
+            ),
+            source=_text(
+                item.get("source"), f"task_{index}.source", required=False
+            ),
+            destination=_text(
+                item.get("destination"),
+                f"task_{index}.destination",
+                required=False,
+            ),
+            preconditions=_string_tuple(
+                item.get("preconditions"), f"task_{index}.preconditions"
+            ),
+            expected_effects=_string_tuple(
+                item.get("expected_effects"),
+                f"task_{index}.expected_effects",
+            ),
+            constraints=_string_tuple(
+                item.get("constraints"), f"task_{index}.constraints"
+            ),
+            timeout_ms=timeout_ms,
+        )
+        tasks.append(
+            TaskNode(
+                task_id=task_id,
+                contract=contract,
+                depends_on=_string_tuple(
+                    item.get("depends_on"), f"task_{index}.depends_on"
+                ),
+            )
+        )
+
+    graph = TaskGraph(goal_id=goal_id, tasks=tuple(tasks))
+    errors = graph.validate_structure()
+    if errors:
+        raise StructuredOutputError("invalid_task_graph:" + ";".join(errors))
+    try:
+        graph.topological_order()
+    except ValueError as exc:
+        raise StructuredOutputError(str(exc)) from exc
+    return graph
+
+
+def parse_critique(payload: Mapping[str, Any]) -> Critique:
+    obj = _object(payload, "critique")
+    _reject_unknown(obj, {"decision", "score", "issues"}, "critique")
+
+    decision_text = _text(obj.get("decision"), "decision")
+    try:
+        decision = CriticDecision(decision_text)
+    except ValueError as exc:
+        raise StructuredOutputError("invalid_critic_decision") from exc
+
+    score = obj.get("score")
+    if (
+        isinstance(score, bool)
+        or not isinstance(score, (int, float))
+        or not isfinite(float(score))
+        or not 0 <= float(score) <= 1
+    ):
+        raise StructuredOutputError("invalid_critic_score")
+
+    issues = _string_tuple(obj.get("issues"), "issues")
+    if len(issues) > 16:
+        raise StructuredOutputError("too_many_critic_issues")
+    return Critique(decision, float(score), issues)
+
+
+def parse_recovery(payload: Mapping[str, Any]) -> RecoveryAdvice:
+    obj = _object(payload, "recovery")
+    _reject_unknown(obj, {"decision", "reason", "retry_after_ms"}, "recovery")
+
+    decision_text = _text(obj.get("decision"), "decision")
+    try:
+        decision = RecoveryDecision(decision_text)
+    except ValueError as exc:
+        raise StructuredOutputError("invalid_recovery_decision") from exc
+
+    reason = _text(obj.get("reason"), "reason")
+    if reason is None:
+        raise StructuredOutputError("reason_required")
+
+    retry_after_ms = obj.get("retry_after_ms")
+    if retry_after_ms is not None and (
+        isinstance(retry_after_ms, bool)
+        or not isinstance(retry_after_ms, int)
+        or not 0 <= retry_after_ms <= 60_000
+    ):
+        raise StructuredOutputError("invalid_retry_after_ms")
+    if decision is RecoveryDecision.WAIT and retry_after_ms is None:
+        raise StructuredOutputError("wait_requires_retry_after_ms")
+
+    return RecoveryAdvice(decision, reason, retry_after_ms)
+
+
+def canonical_json(value: Any) -> str:
+    return json.dumps(
+        json_safe(value),
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=False,
+    )

devagent_physical_engine/ai_cli.py

@@ -0,0 +1,226 @@
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import json
+import os
+
+from .agent import (
+    AgentRuntime,
+    CriticAgent,
+    ModelRouter,
+    PlannerAgent,
+    ProviderPool,
+    RequirementInterpreterAgent,
+    RoutingPolicy,
+    RoutingStrategy,
+)
+from .engineering_agent import SmartEngineeringAgent
+from .provider_adapters import PROVIDER_NAMES, create_provider
+from .provider_qualification import qualify_live_provider
+from .providers import ModelRegistry, ModelSpec, QualificationStatus
+
+
+def _add_live_request_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("text", help="Natural-language engineering request")
+    parser.add_argument("--provider", choices=PROVIDER_NAMES, required=True)
+    parser.add_argument("--model", required=True)
+    parser.add_argument(
+        "--follow-up",
+        action="append",
+        default=[],
+        help="Additional user information; repeat as needed",
+    )
+    parser.add_argument("--timeout", type=float, default=30.0)
+    parser.add_argument("--max-attempts", type=int, default=2)
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="devagent-physical-ai")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    doctor = sub.add_parser(
+        "doctor",
+        help="Check provider SDK and credential availability without a network call",
+    )
+    doctor.add_argument("--provider", choices=PROVIDER_NAMES, required=True)
+
+    qualify = sub.add_parser(
+        "qualify",
+        help="Run live Interpreter+Planner+Critic+Recovery qualification (uses provider API credits)",
+    )
+    qualify.add_argument("--provider", choices=PROVIDER_NAMES, required=True)
+    qualify.add_argument("--model", required=True)
+    qualify.add_argument("--timeout", type=float, default=30.0)
+    qualify.add_argument("--max-attempts", type=int, default=2)
+    qualify.add_argument("--max-revisions", type=int, default=2)
+
+    request = sub.add_parser(
+        "request",
+        help="Interpret natural language and deterministically decide whether more information is required",
+    )
+    _add_live_request_args(request)
+
+    engineer = sub.add_parser(
+        "engineer",
+        help="Natural language -> validated request -> AI plan/critic -> deterministic model smoke",
+    )
+    _add_live_request_args(engineer)
+    return parser
+
+
+def _module_available(module: str) -> bool:
+    try:
+        return importlib.util.find_spec(module) is not None
+    except (ImportError, ModuleNotFoundError, ValueError):
+        return False
+
+
+def provider_doctor(provider: str) -> dict:
+    if provider == "openai":
+        module, envs = "openai", ("OPENAI_API_KEY",)
+    elif provider == "anthropic":
+        module, envs = "anthropic", ("ANTHROPIC_API_KEY",)
+    else:
+        module, envs = "google.genai", ("GEMINI_API_KEY", "GOOGLE_API_KEY")
+    sdk = _module_available(module)
+    credential = any(bool(os.getenv(name, "").strip()) for name in envs)
+    return {
+        "provider": provider,
+        "sdk_installed": sdk,
+        "credential_configured": credential,
+        "ready_for_live_qualification": sdk and credential,
+    }
+
+
+def _live_runtime(provider_name: str, model: str, *, timeout: float, max_attempts: int):
+    provider = create_provider(provider_name)
+    registry = ModelRegistry()
+    registry.register(
+        ModelSpec(
+            provider=provider_name,
+            model=model,
+            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,
+        max_attempts=max_attempts,
+        timeout_s=timeout,
+        require_qualified=False,
+    )
+    return provider, runtime, policy
+
+
+def _request(args: argparse.Namespace) -> int:
+    _, runtime, policy = _live_runtime(
+        args.provider,
+        args.model,
+        timeout=args.timeout,
+        max_attempts=args.max_attempts,
+    )
+    interpreted = RequirementInterpreterAgent(runtime).interpret(
+        args.text,
+        policy,
+        follow_ups=args.follow_up,
+    )
+    payload = interpreted.to_dict()
+    payload["provider_mode"] = "simulation_only_ephemeral_route"
+    payload["real_execution_allowed"] = False
+    print(json.dumps(payload, indent=2))
+    if interpreted.validated is not None:
+        return 0
+    if interpreted.rejection_code:
+        return 4
+    return 3
+
+
+def _engineer(args: argparse.Namespace) -> int:
+    _, runtime, policy = _live_runtime(
+        args.provider,
+        args.model,
+        timeout=args.timeout,
+        max_attempts=args.max_attempts,
+    )
+    interpreter = RequirementInterpreterAgent(runtime)
+    result = SmartEngineeringAgent(
+        interpreter,
+        PlannerAgent(runtime),
+        CriticAgent(runtime),
+    ).run(
+        args.text,
+        interpreter_policy=policy,
+        planner_policy=policy,
+        critic_policy=policy,
+        follow_ups=args.follow_up,
+    )
+    payload = result.to_dict()
+    payload["provider_mode"] = "simulation_only_ephemeral_route"
+    payload["real_execution_allowed"] = False
+    print(json.dumps(payload, indent=2))
+    if result.ready_for_twin_simulation:
+        return 0
+    if result.interpretation.validated is None and not result.interpretation.rejection_code:
+        return 3
+    return 4
+
+
+def _natural_language_failure(exc: BaseException) -> int:
+    print(
+        json.dumps(
+            {
+                "passed": False,
+                "failure_code": f"natural_language_request_failed:{type(exc).__name__}",
+                "physical_qualification": False,
+                "real_execution_allowed": False,
+            },
+            indent=2,
+        )
+    )
+    return 5
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    if args.command == "doctor":
+        result = provider_doctor(args.provider)
+        print(json.dumps(result, indent=2))
+        return 0 if result["ready_for_live_qualification"] else 1
+
+    if args.command == "request":
+        try:
+            return _request(args)
+        except Exception as exc:
+            return _natural_language_failure(exc)
+
+    if args.command == "engineer":
+        try:
+            return _engineer(args)
+        except Exception as exc:
+            return _natural_language_failure(exc)
+
+    provider = create_provider(args.provider)
+    report = qualify_live_provider(
+        provider,
+        model=args.model,
+        timeout_s=args.timeout,
+        max_attempts=args.max_attempts,
+        max_revision_rounds=args.max_revisions,
+    )
+    print(json.dumps(report.to_dict(), indent=2))
+    return 0 if report.passed else 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())