worldfoundry 0.2.0__py3-none-any.whl

worldfoundry/__init__.py

@@ -0,0 +1,8 @@
+"""WorldFoundry local training-experience SDK."""
+
+from .client import WorldFoundry
+from .models import ActionSpec, Episode, StepResult, ValidationResult
+
+__all__ = ["ActionSpec", "Episode", "StepResult", "ValidationResult", "WorldFoundry"]
+__version__ = "0.2.0"
+

worldfoundry/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

worldfoundry/cli.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from . import __version__
+from .client import WorldFoundry
+from .environments import EnvironmentError
+from .server import serve
+from .store import EpisodeNotFound
+
+
+def _print(data: Any) -> None:
+    print(json.dumps(data, indent=2))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="worldfoundry", description="Local training environments for AI agents")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    parser.add_argument("--home", help="State directory (default: $WORLDFOUNDRY_HOME or ~/.worldfoundry)")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    environments = commands.add_parser("environments", help="Discover environments")
+    environments.add_subparsers(dest="subcommand", required=True).add_parser("list")
+
+    episodes = commands.add_parser("episodes", help="Run episodes")
+    episode_commands = episodes.add_subparsers(dest="subcommand", required=True)
+    start = episode_commands.add_parser("start")
+    start.add_argument("environment")
+    start.add_argument("--task", default="incident-triage")
+    start.add_argument("--seed", type=int, default=0)
+    episode_commands.add_parser("list")
+    inspect = episode_commands.add_parser("inspect")
+    inspect.add_argument("episode_id")
+    act = episode_commands.add_parser("act")
+    act.add_argument("episode_id")
+    act.add_argument("action")
+    act.add_argument("--params", default="{}", help="JSON object of action parameters")
+    submit = episode_commands.add_parser("submit")
+    submit.add_argument("episode_id")
+
+    traces = commands.add_parser("traces", help="Export episode traces")
+    trace_commands = traces.add_subparsers(dest="subcommand", required=True)
+    export = trace_commands.add_parser("export")
+    export.add_argument("episode_id")
+    export.add_argument("--output", "-o", required=True)
+
+    server = commands.add_parser("serve", help="Run the local REST API")
+    server.add_argument("--host", default="127.0.0.1")
+    server.add_argument("--port", type=int, default=8787)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    if args.command == "serve":
+        serve(args.host, args.port, args.home)
+        return 0
+    client = WorldFoundry(args.home)
+    try:
+        if args.command == "environments":
+            _print({"data": client.environment_catalog()})
+        elif args.command == "episodes" and args.subcommand == "start":
+            _print(client.start(args.environment, args.task, args.seed).to_dict())
+        elif args.command == "episodes" and args.subcommand == "list":
+            _print({"data": [ep.to_dict(include_state=False) for ep in client.list_episodes()]})
+        elif args.command == "episodes" and args.subcommand == "inspect":
+            _print(client.get(args.episode_id).to_dict())
+        elif args.command == "episodes" and args.subcommand == "act":
+            params = json.loads(args.params)
+            if not isinstance(params, dict):
+                raise ValueError("--params must be a JSON object")
+            _print(client.act(args.episode_id, args.action, **params).to_dict())
+        elif args.command == "episodes" and args.subcommand == "submit":
+            _print(client.submit(args.episode_id).to_dict())
+        elif args.command == "traces":
+            path = client.export_trace(args.episode_id, Path(args.output))
+            _print({"episode_id": args.episode_id, "output": str(path), "format": "jsonl"})
+        return 0
+    except json.JSONDecodeError as exc:
+        print(f"error: invalid JSON in --params: {exc}", file=sys.stderr)
+    except (ValueError, EnvironmentError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+    except EpisodeNotFound as exc:
+        print(f"error: episode not found: {exc.args[0]}", file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+

worldfoundry/client.py

@@ -0,0 +1,45 @@
+"""WorldFoundry public SDK client."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from .engine import EpisodeEngine
+from .platform import AgentManager, EnvironmentManager, Registry, ResourceManager, TrainingManager
+
+if TYPE_CHECKING:
+    from .cloud import CloudWorldFoundry
+
+
+class WorldFoundry(EpisodeEngine):
+    def __new__(cls, home: str | Path | None = None, *, api_key: str | None = None,
+                base_url: str | None = None):
+        if api_key or base_url:
+            if not api_key or not base_url or home is not None:
+                raise ValueError("Cloud mode needs both api_key and base_url, without a local home")
+            from .cloud import CloudWorldFoundry
+            return CloudWorldFoundry(base_url=base_url, api_key=api_key)
+        return super().__new__(cls)
+
+    def __init__(self, home: str | Path | None = None, *, api_key: str | None = None,
+                 base_url: str | None = None):
+        super().__init__(home)
+        registry = Registry(self.store.root)
+        self.projects = ResourceManager(registry, "project")
+        self.environments = EnvironmentManager(registry, "environment")
+        self.agents = AgentManager(registry)
+        self.scenarios = ResourceManager(registry, "scenario")
+        self.datasets = ResourceManager(registry, "dataset")
+        self.policies = ResourceManager(registry, "policy")
+        self.feedback = ResourceManager(registry, "feedback")
+        self.training = TrainingManager(self, self.agents, registry)
+
+    @classmethod
+    def local(cls, data_dir: str | Path | None = None) -> WorldFoundry:
+        return cls(data_dir)
+
+    @classmethod
+    def cloud(cls, *, base_url: str, api_key: str) -> CloudWorldFoundry:
+        from .cloud import CloudWorldFoundry
+        return CloudWorldFoundry(base_url=base_url, api_key=api_key)
+

worldfoundry/cloud.py

@@ -0,0 +1,143 @@
+"""Explicit HTTP SDK transport for a separately deployed WorldFoundry API."""
+from __future__ import annotations
+
+import json
+import tempfile
+from pathlib import Path
+from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+from .platform import WorldFoundryError
+
+
+class HTTPTransport:
+    def __init__(self, base_url: str, api_key: str):
+        if not base_url.startswith("https://") and not base_url.startswith("http://127.0.0.1:"):
+            raise ValueError("Cloud API must use HTTPS (or loopback for development)")
+        if not api_key:
+            raise ValueError("api_key is required")
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+
+    def request(self, method: str, path: str, body: dict[str, Any] | None = None) -> dict[str, Any]:
+        payload = json.dumps(body).encode() if body is not None else None
+        req = Request(self.base_url + path, payload, {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }, method=method)
+        try:
+            with urlopen(req, timeout=30) as response:
+                return json.load(response)
+        except HTTPError as exc:
+            raise WorldFoundryError(f"API returned HTTP {exc.code}") from exc
+        except URLError as exc:
+            raise WorldFoundryError(f"API unavailable: {exc.reason}") from exc
+
+
+class CloudResourceManager:
+    def __init__(self, transport: HTTPTransport, path: str):
+        self.transport, self.path = transport, path
+
+    def create(self, **parameters: Any) -> dict[str, Any]:
+        return self.transport.request("POST", f"/v1/{self.path}", parameters)
+
+    def register(self, **parameters: Any) -> dict[str, Any]:
+        return self.create(**parameters)
+
+    def get(self, resource_id: str) -> dict[str, Any]:
+        return self.transport.request("GET", f"/v1/{self.path}/{resource_id}")
+
+    def list(self) -> dict[str, Any]:
+        return self.transport.request("GET", f"/v1/{self.path}")
+
+    def update(self, resource_id: str, **parameters: Any) -> dict[str, Any]:
+        return self.transport.request("PATCH", f"/v1/{self.path}/{resource_id}", parameters)
+
+    def run(self, **parameters: Any) -> dict[str, Any]:
+        return self.create(**parameters)
+
+
+class CloudWorldFoundry:
+    """Client contract; requires an independently deployed, authenticated API."""
+    def __init__(self, *, base_url: str, api_key: str):
+        transport = HTTPTransport(base_url, api_key)
+        self.projects = CloudResourceManager(transport, "projects")
+        self.environments = CloudResourceManager(transport, "environments")
+        self.agents = CloudResourceManager(transport, "agents")
+        self.scenarios = CloudResourceManager(transport, "scenarios")
+        self.datasets = CloudResourceManager(transport, "datasets")
+        self.policies = CloudResourceManager(transport, "policies")
+        self.validators = CloudResourceManager(transport, "validators")
+        self.runs = CloudResourceManager(transport, "training-runs")
+        self.training = CloudTrainingManager(transport)
+        self.episodes = CloudResourceManager(transport, "episodes")
+
+    @classmethod
+    def sign_in(cls, *, project_url: str, publishable_key: str,
+                email: str, password: str) -> CloudWorldFoundry:
+        """Exchange Supabase email/password for a user session; keep it in memory only."""
+        if not project_url.startswith("https://"):
+            raise ValueError("project_url must use HTTPS")
+        endpoint = project_url.rstrip("/") + "/auth/v1/token?grant_type=password"
+        req = Request(endpoint, json.dumps({"email": email, "password": password}).encode(), {
+            "apikey": publishable_key, "Content-Type": "application/json",
+        }, method="POST")
+        try:
+            with urlopen(req, timeout=30) as response:
+                token = json.load(response)["access_token"]
+        except (HTTPError, URLError) as exc:
+            raise WorldFoundryError("Supabase sign-in failed") from exc
+        return cls(base_url=project_url.rstrip("/") + "/functions/v1/worldfoundry-api",
+                   api_key=token)
+
+
+class CloudTrainingManager(CloudResourceManager):
+    def __init__(self, transport: HTTPTransport):
+        super().__init__(transport, "training-runs")
+
+    def run_local(self, *, project_id: str, agent: dict[str, Any],
+                  environment: dict[str, Any], handler: Any, episodes: int = 1,
+                  seed: int = 0, data_dir: str | Path | None = None) -> dict[str, Any]:
+        """Run user code on this computer, then sync scores to Supabase.
+
+        The cloud record is not a managed execution claim. A process exit before sync
+        leaves a running record that can be inspected and recovered by the caller.
+        """
+        from .client import WorldFoundry
+
+        if not 1 <= episodes <= 10000:
+            raise ValueError("episodes must be between 1 and 10000")
+        run = self.create(project_id=project_id, agent_id=agent["id"],
+                          environment_id=environment["id"], episodes=episodes,
+                          execution="client", seed=seed)
+        self.update(run["id"], status="running")
+        with tempfile.TemporaryDirectory(prefix="worldfoundry-") if data_dir is None else _existing_dir(data_dir) as root:
+            local = WorldFoundry.local(root)
+            template = environment.get("config", {}).get("template", "support-desk")
+            env = local.environments.create(template=template)
+            registered = local.agents.register(name=agent["name"], handler=handler)
+            result = local.training.create(agent=registered, environment=env, episodes=episodes, seed=seed)
+            for ordinal, episode_id in enumerate(result.episode_ids):
+                episode = local.get(episode_id)
+                remote_episode = self.transport.request("POST", "/v1/episodes", {
+                    "run_id": run["id"], "ordinal": ordinal, "seed": seed + ordinal,
+                    "status": episode.status, "score": result.scores[ordinal],
+                })
+                self.transport.request("POST", f"/v1/episodes/{remote_episode['id']}/trace",
+                                       {"events": episode.trace})
+        completed = self.update(run["id"], status="completed")
+        return {"run": completed, "summary": result.summary, "report_url": None}
+
+
+class _existing_dir:
+    def __init__(self, path: str | Path):
+        self.path = Path(path)
+
+    def __enter__(self) -> Path:
+        self.path.mkdir(parents=True, exist_ok=True)
+        return self.path
+
+    def __exit__(self, *args: object) -> None:
+        pass
+

worldfoundry/engine.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from .environments import ENVIRONMENTS, EnvironmentError, get_environment
+from .models import Episode, StepResult, ValidationResult
+from .store import LocalStore
+
+
+def _now() -> str:
+    return datetime.now(UTC).isoformat()
+
+
+class EpisodeEngine:
+    """Local WorldFoundry client and episode engine."""
+
+    def __init__(self, home: str | Path | None = None):
+        self.store = LocalStore(home)
+
+    def environment_catalog(self) -> list[dict[str, Any]]:
+        return [
+            {
+                "id": env.id,
+                "name": env.name,
+                "description": env.description,
+                "tasks": list(env.tasks),
+                "actions": [action.to_dict() for action in env.actions()],
+            }
+            for env in ENVIRONMENTS.values()
+        ]
+
+    def start(self, environment: str, task: str = "incident-triage", seed: int = 0) -> Episode:
+        env = get_environment(environment)
+        if task not in env.tasks:
+            raise EnvironmentError(f"Unknown task '{task}' for environment '{environment}'")
+        timestamp = _now()
+        episode = Episode(
+            id=f"ep_{uuid.uuid4().hex[:12]}",
+            environment=environment,
+            task=task,
+            instruction=env.instruction,
+            seed=seed,
+            status="running",
+            state=env.initial_state(seed),
+            created_at=timestamp,
+            updated_at=timestamp,
+        )
+        episode.trace.append(
+            {
+                "event_id": f"evt_{uuid.uuid4().hex}",
+                "sequence": 0,
+                "timestamp": timestamp,
+                "type": "episode.started",
+                "episode_id": episode.id,
+                "environment": environment,
+                "task": task,
+                "seed": seed,
+                "instruction": episode.instruction,
+            }
+        )
+        self.store.save(episode)
+        return episode
+
+    def get(self, episode_id: str) -> Episode:
+        return self.store.load(episode_id)
+
+    def list_episodes(self) -> list[Episode]:
+        return self.store.list()
+
+    def act(self, episode_id: str, action: str, **params: Any) -> StepResult:
+        episode = self.get(episode_id)
+        if episode.status != "running":
+            raise EnvironmentError(f"Episode is {episode.status}; no more actions are allowed")
+        env = get_environment(episode.environment)
+        try:
+            observation = env.perform(episode.state, action, params)
+        except EnvironmentError as exc:
+            episode.updated_at = _now()
+            episode.trace.append(
+                {
+                    "event_id": f"evt_{uuid.uuid4().hex}",
+                    "sequence": len(episode.trace),
+                    "timestamp": episode.updated_at,
+                    "type": "action.failed",
+                    "episode_id": episode.id,
+                    "action": action,
+                    "parameters": params,
+                    "error": str(exc),
+                }
+            )
+            self.store.save(episode)
+            raise
+        episode.updated_at = _now()
+        episode.trace.append(
+            {
+                "event_id": f"evt_{uuid.uuid4().hex}",
+                "sequence": len(episode.trace),
+                "timestamp": episode.updated_at,
+                "type": "action.completed",
+                "episode_id": episode.id,
+                "action": action,
+                "parameters": params,
+                "observation": observation,
+            }
+        )
+        self.store.save(episode)
+        return StepResult(episode.id, action, observation, episode.status, len(episode.trace) - 1)
+
+    def submit(self, episode_id: str) -> ValidationResult:
+        episode = self.get(episode_id)
+        if episode.status != "running":
+            if episode.validation is None:
+                raise EnvironmentError(f"Episode is {episode.status}")
+            return episode.validation
+        result = get_environment(episode.environment).validate(episode.state)
+        episode.validation = result
+        episode.status = "passed" if result.passed else "failed"
+        episode.updated_at = _now()
+        episode.trace.append(
+            {
+                "event_id": f"evt_{uuid.uuid4().hex}",
+                "sequence": len(episode.trace),
+                "timestamp": episode.updated_at,
+                "type": "episode.submitted",
+                "episode_id": episode.id,
+                "status": episode.status,
+                "validation": result.to_dict(),
+            }
+        )
+        self.store.save(episode)
+        return result
+
+    def export_trace(self, episode_id: str, path: str | Path) -> Path:
+        return self.store.export_trace(episode_id, path)
+
+
+# Preserve imports from the first local SDK release.
+WorldFoundry = EpisodeEngine
+

worldfoundry/environments.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any
+
+from .models import ActionSpec, ValidationCheck, ValidationResult
+
+
+class EnvironmentError(ValueError):
+    pass
+
+
+class SupportDeskEnvironment:
+    id = "support-desk"
+    name = "Support Desk"
+    description = "A simulated customer support queue with mutable tickets and audit-safe actions."
+    tasks = ("incident-triage",)
+
+    instruction = (
+        "Triage the Acme Corp production outage in ticket TCK-100. Make it critical, assign "
+        "it to the on-call engineer, send the customer a reply that acknowledges the outage "
+        "and mentions an incident, then resolve the ticket."
+    )
+
+    action_specs = (
+        ActionSpec("list_tickets", "List tickets, optionally filtered by status.", {"status": {"type": "string"}}),
+        ActionSpec(
+            "get_ticket",
+            "Read a ticket.",
+            {"ticket_id": {"type": "string"}},
+            ("ticket_id",),
+        ),
+        ActionSpec(
+            "set_priority",
+            "Change a ticket priority.",
+            {"ticket_id": {"type": "string"}, "priority": {"type": "string", "enum": ["low", "normal", "high", "critical"]}},
+            ("ticket_id", "priority"),
+        ),
+        ActionSpec(
+            "assign",
+            "Assign a ticket to a support user.",
+            {"ticket_id": {"type": "string"}, "assignee": {"type": "string"}},
+            ("ticket_id", "assignee"),
+        ),
+        ActionSpec(
+            "reply",
+            "Send a customer-visible reply.",
+            {"ticket_id": {"type": "string"}, "message": {"type": "string"}},
+            ("ticket_id", "message"),
+        ),
+        ActionSpec(
+            "resolve",
+            "Resolve a ticket after required triage work.",
+            {"ticket_id": {"type": "string"}},
+            ("ticket_id",),
+        ),
+    )
+
+    def initial_state(self, seed: int) -> dict[str, Any]:
+        del seed
+        return {
+            "users": ["agent-lee", "on-call"],
+            "tickets": {
+                "TCK-100": {
+                    "id": "TCK-100",
+                    "customer": "Acme Corp",
+                    "subject": "Production API unavailable",
+                    "body": "All API requests have returned 503 for twelve minutes.",
+                    "priority": "normal",
+                    "status": "open",
+                    "assignee": None,
+                    "replies": [],
+                },
+                "TCK-101": {
+                    "id": "TCK-101",
+                    "customer": "Northstar Labs",
+                    "subject": "How do I rotate an API key?",
+                    "body": "Looking for the key rotation documentation.",
+                    "priority": "low",
+                    "status": "open",
+                    "assignee": None,
+                    "replies": [],
+                },
+            },
+        }
+
+    def actions(self) -> tuple[ActionSpec, ...]:
+        return self.action_specs
+
+    def _validate_params(self, action: str, params: dict[str, Any]) -> ActionSpec:
+        spec = next((item for item in self.action_specs if item.name == action), None)
+        if not spec:
+            raise EnvironmentError(f"Unknown action: {action}")
+        missing = [key for key in spec.required if key not in params]
+        if missing:
+            raise EnvironmentError(f"Missing required parameter(s): {', '.join(missing)}")
+        unknown = set(params) - set(spec.parameters)
+        if unknown:
+            raise EnvironmentError(f"Unknown parameter(s): {', '.join(sorted(unknown))}")
+        for key, value in params.items():
+            schema = spec.parameters[key]
+            if schema.get("type") == "string" and not isinstance(value, str):
+                raise EnvironmentError(f"Parameter '{key}' must be a string")
+            if "enum" in schema and value not in schema["enum"]:
+                raise EnvironmentError(f"Parameter '{key}' must be one of {schema['enum']}")
+        return spec
+
+    def perform(self, state: dict[str, Any], action: str, params: dict[str, Any]) -> dict[str, Any]:
+        self._validate_params(action, params)
+        tickets = state["tickets"]
+        if action == "list_tickets":
+            items = list(tickets.values())
+            if params.get("status"):
+                items = [ticket for ticket in items if ticket["status"] == params["status"]]
+            return {"tickets": deepcopy(items)}
+
+        ticket_id = params["ticket_id"]
+        if ticket_id not in tickets:
+            raise EnvironmentError(f"Ticket not found: {ticket_id}")
+        ticket = tickets[ticket_id]
+
+        if action == "get_ticket":
+            return {"ticket": deepcopy(ticket)}
+        if action == "set_priority":
+            ticket["priority"] = params["priority"]
+            return {"ticket_id": ticket_id, "priority": ticket["priority"]}
+        if action == "assign":
+            if params["assignee"] not in state["users"]:
+                raise EnvironmentError(f"Unknown assignee: {params['assignee']}")
+            ticket["assignee"] = params["assignee"]
+            return {"ticket_id": ticket_id, "assignee": ticket["assignee"]}
+        if action == "reply":
+            message = params["message"].strip()
+            if not message:
+                raise EnvironmentError("Reply message cannot be empty")
+            ticket["replies"].append({"message": message, "visibility": "customer"})
+            return {"ticket_id": ticket_id, "reply_count": len(ticket["replies"])}
+        if action == "resolve":
+            ticket["status"] = "resolved"
+            return {"ticket_id": ticket_id, "status": "resolved"}
+        raise AssertionError("unreachable")
+
+    def validate(self, state: dict[str, Any]) -> ValidationResult:
+        ticket = state["tickets"]["TCK-100"]
+        reply_text = " ".join(reply["message"].lower() for reply in ticket["replies"])
+        checks = (
+            ValidationCheck("critical_priority", ticket["priority"] == "critical", "Ticket priority is critical."),
+            ValidationCheck("on_call_assignment", ticket["assignee"] == "on-call", "Ticket is assigned to on-call."),
+            ValidationCheck("outage_acknowledged", "outage" in reply_text, "Customer reply acknowledges the outage."),
+            ValidationCheck("incident_mentioned", "incident" in reply_text, "Customer reply mentions an incident."),
+            ValidationCheck("ticket_resolved", ticket["status"] == "resolved", "Ticket is resolved."),
+        )
+        passed_count = sum(check.passed for check in checks)
+        return ValidationResult(passed_count == len(checks), passed_count / len(checks), checks)
+
+
+ENVIRONMENTS = {SupportDeskEnvironment.id: SupportDeskEnvironment()}
+
+
+def get_environment(environment_id: str) -> SupportDeskEnvironment:
+    try:
+        return ENVIRONMENTS[environment_id]
+    except KeyError as exc:
+        raise EnvironmentError(f"Unknown environment: {environment_id}") from exc
+

worldfoundry/integrations/__init__.py

@@ -0,0 +1,2 @@
+"""Framework integration helpers."""
+

worldfoundry/integrations/adk.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from ..client import WorldFoundry
+
+
+def tools(client: WorldFoundry, episode_id: str) -> list[Callable[..., dict[str, Any]]]:
+    """Return plain callables that Google ADK can wrap as function tools.
+
+    This module intentionally has no hard ADK dependency. Applications using Google ADK can
+    pass these callables to an Agent's ``tools`` list.
+    """
+
+    def worldfoundry_action(action: str, parameters: dict[str, Any] | None = None) -> dict[str, Any]:
+        """Perform an action in the current WorldFoundry episode."""
+        return client.act(episode_id, action, **(parameters or {})).to_dict()
+
+    def worldfoundry_submit() -> dict[str, Any]:
+        """Submit the current episode for deterministic validation."""
+        return client.submit(episode_id).to_dict()
+
+    return [worldfoundry_action, worldfoundry_submit]
+