resource-agent-system 0.5.7__py3-none-any.whl

generator/agent_generator.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Iterable
+
+import yaml
+from jinja2 import Environment, FileSystemLoader
+
+from generator.hashutil import file_sha256
+from generator.header import (
+    contract_source_ref,
+    dockerfile_header,
+    generated_marker_payload,
+    markdown_generated_banner,
+    python_file_header,
+)
+from generator.model import AgentSpec, load_agent_spec, spec_to_plain_dict
+from generator.paths import find_repo_root
+from generator.validate import validate_agent
+
+PACKAGE_ROOT = Path(__file__).resolve().parent
+ROOT = find_repo_root(Path(__file__))
+TEMPLATES = PACKAGE_ROOT / "templates"
+OUTPUT_ROOT = ROOT / "agents" / "generated"
+
+
+def render_template(env: Environment, template_name: str, dest: Path, context: dict) -> None:
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    rendered = env.get_template(template_name).render(**context)
+    dest.write_text(rendered, encoding="utf-8")
+
+
+def generate_agent(spec_path: Path, *, output_root: Path | None = None) -> Path:
+    errors = validate_agent(spec_path)
+    if errors:
+        raise ValueError("\n".join(errors))
+
+    spec: AgentSpec = load_agent_spec(spec_path)
+    contract_hash = file_sha256(spec_path)
+    source_ref = contract_source_ref(spec_path, ROOT)
+    base_output = output_root or OUTPUT_ROOT
+    output_dir = base_output / spec.output_dir_name
+    env = Environment(loader=FileSystemLoader(TEMPLATES), trim_blocks=True, lstrip_blocks=True)
+
+    context = {
+        "spec": spec,
+        "source_ref": source_ref,
+        "contract_hash": contract_hash,
+        "python_header": python_file_header(source_ref, contract_hash),
+        "dockerfile_header": dockerfile_header(source_ref, contract_hash),
+        "markdown_header": markdown_generated_banner(source_ref, contract_hash),
+        "agent_card": spec_to_plain_dict(spec, contract_hash, source_ref=source_ref),
+        "capability_names": [cap.name for cap in spec.capabilities],
+    }
+
+    files = {
+        "__init__.py.j2": output_dir / "__init__.py",
+        "main.py.j2": output_dir / "main.py",
+        "routes.py.j2": output_dir / "routes.py",
+        "agent_card.py.j2": output_dir / "agent_card.py",
+        "Dockerfile.j2": output_dir / "Dockerfile",
+        "README.md.j2": output_dir / "README.md",
+        "test_contract.py.j2": output_dir / "tests" / "test_contract.py",
+    }
+    for template, destination in files.items():
+        render_template(env, template, destination, context)
+
+    marker_path = output_dir / ".generated.yaml"
+    marker_path.write_text(
+        yaml.safe_dump(generated_marker_payload(source_ref, contract_hash), sort_keys=False),
+        encoding="utf-8",
+    )
+
+    return output_dir
+
+
+def expand_paths(patterns: Iterable[str]) -> list[Path]:
+    result: list[Path] = []
+    for pattern in patterns:
+        matches = sorted(Path().glob(pattern))
+        if matches:
+            result.extend(matches)
+        else:
+            path = Path(pattern)
+            if path.exists():
+                result.append(path)
+    return result
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = argv or sys.argv[1:]
+    if not argv:
+        argv = ["contracts/agents/*.yaml"]
+    paths = expand_paths(argv)
+    if not paths:
+        print("No agent specs matched.")
+        return 1
+    for path in paths:
+        output_dir = generate_agent(path)
+        print(f"Generated {output_dir}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

generator/hashutil.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+
+def file_sha256(path: str | Path) -> str:
+    data = Path(path).read_bytes()
+    return "sha256:" + hashlib.sha256(data).hexdigest()

generator/header.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from generator.paths import project_root
+
+AUTO_GENERATED_MARKER = "AUTO-GENERATED FILE. DO NOT EDIT."
+GENERATOR_NAME = "resource-agent-factory"
+
+
+def contract_source_ref(spec_path: Path, root: Path | None = None) -> str:
+    """Return a stable repo-relative contract path for generated headers."""
+    base = (root or project_root()).resolve()
+    resolved = spec_path.expanduser().resolve()
+    try:
+        return resolved.relative_to(base).as_posix()
+    except ValueError:
+        return resolved.as_posix()
+
+
+def python_file_header(source_ref: str, contract_hash: str) -> str:
+    return (
+        f"# {AUTO_GENERATED_MARKER}\n"
+        f"# Source: {source_ref}\n"
+        f"# Contract hash: {contract_hash}\n\n"
+    )
+
+
+def dockerfile_header(source_ref: str, contract_hash: str) -> str:
+    return (
+        f"# {AUTO_GENERATED_MARKER}\n"
+        f"# Source: {source_ref}\n"
+        f"# Contract hash: {contract_hash}\n"
+    )
+
+
+def markdown_generated_banner(source_ref: str, contract_hash: str) -> str:
+    return (
+        f"<!-- {AUTO_GENERATED_MARKER} -->\n"
+        f"<!-- Source: {source_ref} -->\n"
+        f"<!-- Contract hash: {contract_hash} -->\n"
+    )
+
+
+def generated_marker_payload(source_ref: str, contract_hash: str) -> dict[str, str]:
+    return {
+        "auto_generated": "true",
+        "source": source_ref,
+        "contract_hash": contract_hash,
+        "generator": GENERATOR_NAME,
+    }

generator/model.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal
+
+import yaml
+
+CapabilityType = Literal["resource_read", "command"]
+
+
+@dataclass(frozen=True)
+class Capability:
+    name: str
+    type: CapabilityType
+    description: str = ""
+    uri: str | None = None
+    output_schema: str | None = None
+    renderer: str | None = None
+    command: str | None = None
+    input_schema: str | None = None
+    emits: list[str] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class AgentSpec:
+    source_path: Path
+    name: str
+    python_package: str
+    version: str
+    description: str
+    runtime_url_env: str
+    runtime_url_default: str
+    capabilities: list[Capability]
+
+    @property
+    def output_dir_name(self) -> str:
+        return self.python_package
+
+
+def load_agent_spec(path: str | Path) -> AgentSpec:
+    source_path = Path(path)
+    raw = yaml.safe_load(source_path.read_text(encoding="utf-8"))
+    if not isinstance(raw, dict):
+        raise ValueError(f"{source_path} must contain a YAML mapping")
+
+    agent = raw.get("agent") or {}
+    capabilities_raw = raw.get("capabilities") or []
+
+    capabilities: list[Capability] = []
+    for item in capabilities_raw:
+        capabilities.append(
+            Capability(
+                name=item["name"],
+                type=item["type"],
+                description=item.get("description", ""),
+                uri=item.get("uri"),
+                output_schema=item.get("output_schema"),
+                renderer=item.get("renderer"),
+                command=item.get("command"),
+                input_schema=item.get("input_schema"),
+                emits=item.get("emits", []) or [],
+            )
+        )
+
+    return AgentSpec(
+        source_path=source_path,
+        name=agent["name"],
+        python_package=agent.get("python_package") or agent["name"].replace("-", "_"),
+        version=str(agent.get("version", "0.1.0")),
+        description=agent.get("description", ""),
+        runtime_url_env=agent.get("runtime_url_env", "RESOURCE_RUNTIME_URL"),
+        runtime_url_default=agent.get("runtime_url_default", "http://localhost:8000"),
+        capabilities=capabilities,
+    )
+
+
+def spec_to_plain_dict(
+    spec: AgentSpec,
+    contract_hash: str,
+    *,
+    source_ref: str | None = None,
+) -> dict[str, Any]:
+    contract = source_ref or str(spec.source_path)
+    return {
+        "name": spec.name,
+        "version": spec.version,
+        "description": spec.description,
+        "generated_from": {
+            "contract": contract,
+            "contract_hash": contract_hash,
+        },
+        "capabilities": [cap.__dict__ for cap in spec.capabilities],
+    }

generator/paths.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def find_repo_root(start: Path | None = None) -> Path:
+    current = (start or Path(__file__)).resolve()
+    if current.is_file():
+        current = current.parent
+    for path in (current, *current.parents):
+        if (path / "contracts").is_dir() and (path / "schemas").is_dir():
+            return path
+    raise FileNotFoundError("Repository root not found (expected contracts/ and schemas/)")
+
+
+def project_root() -> Path:
+    return find_repo_root()

generator/templates/Dockerfile.j2

@@ -0,0 +1,7 @@
+{% include '_dockerfile_header.j2' %}
+FROM python:3.12-slim
+WORKDIR /app
+COPY . /app
+RUN pip install --no-cache-dir -e .
+EXPOSE 8101
+CMD ["uvicorn", "agents.generated.{{ spec.python_package }}.main:app", "--host", "0.0.0.0", "--port", "8101"]

generator/templates/README.md.j2

@@ -0,0 +1,31 @@
+{% include '_markdown_header.j2' %}
+# {{ spec.name }}
+
+Generated thin resource agent.
+
+- Version: `{{ spec.version }}`
+- Source: `{{ source_ref }}`
+- Contract hash: `{{ contract_hash }}`
+
+## Run
+
+```bash
+uvicorn agents.generated.{{ spec.python_package }}.main:app --reload --port 8101
+```
+
+## Endpoints
+
+```txt
+GET /health
+GET /capabilities
+GET /.well-known/agent.json
+GET /.well-known/agent-card.json
+GET /resources/read?uri=...
+POST /commands
+```
+
+## Capabilities
+
+{% for cap in spec.capabilities %}
+- `{{ cap.name }}` — `{{ cap.type }}`{% if cap.uri %}, URI: `{{ cap.uri }}`{% endif %}{% if cap.command %}, command: `{{ cap.command }}`{% endif %}
+{% endfor %}

generator/templates/__init__.py.j2

@@ -0,0 +1 @@
+{% include '_python_header.j2' %}

generator/templates/_dockerfile_header.j2

@@ -0,0 +1 @@
+{{ dockerfile_header }}

generator/templates/_markdown_header.j2

@@ -0,0 +1 @@
+{{ markdown_header }}

generator/templates/_python_header.j2

@@ -0,0 +1 @@
+{{ python_header }}

generator/templates/agent_card.py.j2

@@ -0,0 +1,2 @@
+{% include '_python_header.j2' %}
+AGENT_CARD = {{ agent_card | tojson(indent=2) }}

generator/templates/main.py.j2

@@ -0,0 +1,13 @@
+{% include '_python_header.j2' %}
+from __future__ import annotations
+
+from fastapi import FastAPI
+
+from .routes import router
+
+app = FastAPI(
+    title="{{ spec.name }}",
+    version="{{ spec.version }}",
+    description="{{ spec.description }}",
+)
+app.include_router(router)

generator/templates/routes.py.j2

@@ -0,0 +1,87 @@
+{% include '_python_header.j2' %}
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from fastapi import APIRouter, HTTPException, Query
+from pydantic import BaseModel, Field
+
+from runtime_client.client import ResourceRuntimeClient
+
+from .agent_card import AGENT_CARD
+
+router = APIRouter()
+
+RUNTIME_URL = os.getenv("{{ spec.runtime_url_env }}", "{{ spec.runtime_url_default }}")
+client = ResourceRuntimeClient(base_url=RUNTIME_URL)
+
+
+class CommandRequest(BaseModel):
+    command: str = Field(..., description="Runtime command name")
+    payload: dict[str, Any] = Field(default_factory=dict)
+
+
+@router.get("/health")
+def health() -> dict[str, Any]:
+    return {
+        "ok": True,
+        "agent": "{{ spec.name }}",
+        "version": "{{ spec.version }}",
+        "runtime_url": RUNTIME_URL,
+    }
+
+
+@router.get("/capabilities")
+def capabilities() -> dict[str, Any]:
+    return {"capabilities": AGENT_CARD["capabilities"]}
+
+
+@router.get("/.well-known/agent.json")
+def well_known_agent_json() -> dict[str, Any]:
+    return AGENT_CARD
+
+
+@router.get("/.well-known/agent-card.json")
+def well_known_agent_card_json() -> dict[str, Any]:
+    return AGENT_CARD
+
+
+@router.get("/resources/read")
+def read_resource(uri: str = Query(...)) -> dict[str, Any]:
+    allowed = [cap.get("uri") for cap in AGENT_CARD["capabilities"] if cap.get("type") == "resource_read"]
+    if not _uri_allowed(uri, allowed):
+        raise HTTPException(status_code=403, detail=f"URI not exposed by this agent: {uri}")
+    return client.read_resource(uri)
+
+
+@router.post("/commands")
+def dispatch_command(request: CommandRequest) -> dict[str, Any]:
+    allowed = [cap.get("command") for cap in AGENT_CARD["capabilities"] if cap.get("type") == "command"]
+    if request.command not in allowed:
+        raise HTTPException(status_code=403, detail=f"Command not exposed by this agent: {request.command}")
+    return client.dispatch_command(request.command, request.payload)
+
+
+{% for cap in spec.capabilities if cap.type == "resource_read" %}
+@router.get("/skills/{{ cap.name }}")
+def skill_{{ cap.name }}({% for segment in cap.uri.split('{')[1:] %}{{ segment.split('}')[0] }}: str{% if not loop.last %}, {% endif %}{% endfor %}) -> dict[str, Any]:
+    uri = "{{ cap.uri }}"{% for segment in cap.uri.split('{')[1:] %}.replace("{{ '{' }}{{ segment.split('}')[0] }}{{ '}' }}", {{ segment.split('}')[0] }}){% endfor %}
+    return client.read_resource(uri)
+{% endfor %}
+
+{% for cap in spec.capabilities if cap.type == "command" %}
+@router.post("/skills/{{ cap.name }}")
+def skill_{{ cap.name }}(payload: dict[str, Any]) -> dict[str, Any]:
+    return client.dispatch_command("{{ cap.command }}", payload)
+{% endfor %}
+
+
+def _uri_allowed(uri: str, templates: list[str | None]) -> bool:
+    for template in templates:
+        if not template:
+            continue
+        prefix = template.split("{")[0]
+        if uri.startswith(prefix):
+            return True
+    return False

generator/templates/test_contract.py.j2

@@ -0,0 +1,15 @@
+{% include '_python_header.j2' %}
+from agents.generated.{{ spec.python_package }}.agent_card import AGENT_CARD
+
+
+def test_agent_card_has_expected_name():
+    assert AGENT_CARD["name"] == "{{ spec.name }}"
+
+
+def test_agent_card_has_capabilities():
+    names = {cap["name"] for cap in AGENT_CARD["capabilities"]}
+    assert names == {{ capability_names | tojson }}
+
+
+def test_agent_card_has_contract_hash():
+    assert AGENT_CARD["generated_from"]["contract_hash"] == "{{ contract_hash }}"

generator/validate.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from generator.model import load_agent_spec
+
+
+def validate_agent(path: Path) -> list[str]:
+    errors: list[str] = []
+    try:
+        spec = load_agent_spec(path)
+    except Exception as exc:  # noqa: BLE001
+        return [f"{path}: cannot load spec: {exc}"]
+
+    names = set()
+    for cap in spec.capabilities:
+        if cap.name in names:
+            errors.append(f"{path}: duplicate capability name {cap.name}")
+        names.add(cap.name)
+
+        if cap.type == "resource_read":
+            if not cap.uri:
+                errors.append(f"{path}: {cap.name} resource_read requires uri")
+            if not cap.output_schema:
+                errors.append(f"{path}: {cap.name} resource_read requires output_schema")
+            if not cap.renderer:
+                errors.append(f"{path}: {cap.name} resource_read requires renderer")
+        elif cap.type == "command":
+            if not cap.command:
+                errors.append(f"{path}: {cap.name} command capability requires command")
+            if not cap.input_schema:
+                errors.append(f"{path}: {cap.name} command capability requires input_schema")
+        else:
+            errors.append(f"{path}: {cap.name} unsupported type {cap.type}")
+
+    return errors
+
+
+def iter_agent_specs(root: Path) -> list[Path]:
+    if root.is_file():
+        return [root]
+    return sorted((root / "agents").glob("*.yaml")) if (root / "agents").exists() else sorted(root.glob("*.yaml"))
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = argv or sys.argv[1:]
+    root = Path(argv[0] if argv else "contracts")
+    paths = iter_agent_specs(root)
+    if not paths:
+        print(f"No agent specs found under {root}")
+        return 1
+
+    all_errors: list[str] = []
+    for path in paths:
+        all_errors.extend(validate_agent(path))
+
+    if all_errors:
+        print("Contract validation failed:")
+        for error in all_errors:
+            print(f"- {error}")
+        return 1
+
+    print(f"Validated {len(paths)} agent spec(s).")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

generator/verify.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+from generator.hashutil import file_sha256
+from generator.header import AUTO_GENERATED_MARKER
+
+HASH_RE = re.compile(r"Contract hash: (sha256:[a-f0-9]{64})")
+SOURCE_RE = re.compile(r"Source: ([^\n]+)")
+
+
+def verify_generated_agent(agent_dir: Path) -> list[str]:
+    errors: list[str] = []
+    main_file = agent_dir / "main.py"
+    if not main_file.exists():
+        return [f"{agent_dir}: missing main.py"]
+    text = main_file.read_text(encoding="utf-8")
+    if AUTO_GENERATED_MARKER not in text:
+        return [f"{agent_dir}: missing auto-generated marker"]
+    source_match = SOURCE_RE.search(text)
+    hash_match = HASH_RE.search(text)
+    if not source_match or not hash_match:
+        return [f"{agent_dir}: missing generated source/hash header"]
+
+    source = Path(source_match.group(1))
+    expected_hash = hash_match.group(1)
+    if source.exists():
+        if file_sha256(source) != expected_hash:
+            errors.append(f"{agent_dir}: contract_hash mismatch; regenerate agent")
+        # else: source present and matches → OK
+    else:
+        # Source contract not present on this machine (e.g. generated on another host,
+        # or the agent dir is part of the committed examples). Do not fail verification
+        # for portability; only presence + hash match matters when the source is here.
+        pass
+
+    return errors
+
+
+
+def verify_generated(root: Path) -> list[str]:
+    agent_dirs = [p for p in root.iterdir() if p.is_dir()] if root.exists() else []
+    errors: list[str] = []
+    if not agent_dirs:
+        return [f"No generated agents found in {root}"]
+    for agent_dir in agent_dirs:
+        errors.extend(verify_generated_agent(agent_dir))
+    return errors
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = argv or sys.argv[1:]
+    root = Path(argv[0] if argv else "agents/generated")
+    agent_dirs = [p for p in root.iterdir() if p.is_dir()] if root.exists() else []
+    if not agent_dirs:
+        print(f"No generated agents found in {root}")
+        return 1
+
+    errors = verify_generated(root)
+
+    if errors:
+        print("Generated verification failed:")
+        for error in errors:
+            print(f"- {error}")
+        return 1
+    print(f"Verified {len(agent_dirs)} generated agent(s).")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

hypervisor/__init__.py

@@ -0,0 +1,13 @@
+"""WronAI Hypervisor — public API surface."""
+
+from ._version import __version__
+from .config import get_config, load_config, get_default_config
+from .core import Hypervisor
+
+__all__ = [
+    "__version__",
+    "get_config",
+    "load_config",
+    "get_default_config",
+    "Hypervisor",
+]

hypervisor/_version.py

@@ -0,0 +1,20 @@
+"""
+Single source of truth for package version at runtime.
+
+Tries PEP 566 / importlib.metadata first (when installed),
+falls back to a development default.
+"""
+
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+try:
+    from importlib.metadata import version, PackageNotFoundError
+
+    try:
+        __version__ = version("hypervisor")
+    except PackageNotFoundError:
+        __version__ = "0.1.0.dev0"
+except Exception:  # pragma: no cover
+    __version__ = "0.1.0.dev0"