worldfoundry 0.2.0__tar.gz

worldfoundry-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,41 @@
+name: WorldFoundry release
+
+on:
+  push:
+    tags:
+      - 'v*'
+    branches:
+      - 'release/v*'
+
+jobs:
+  verify-and-build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - run: python -m pip install '.[dev]' build twine
+      - run: python -m pytest
+      - run: ruff check src tests examples
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+
+  publish:
+    needs: verify-and-build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

worldfoundry-0.2.0/.gitignore

@@ -0,0 +1,14 @@
+.DS_Store
+.venv/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.wf-data/
+.wf-example/
+work/
+*.jsonl
+

worldfoundry-0.2.0/LICENSE

@@ -0,0 +1,17 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+Copyright 2026 WorldFoundry
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

worldfoundry-0.2.0/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.5
+Name: worldfoundry
+Version: 0.2.0
+Summary: Agent development and training-experience SDK
+Author: WorldFoundry
+License: Apache-2.0
+License-File: LICENSE
+Keywords: agents,evaluation,simulation,training-environments
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# WorldFoundry
+
+**Training infrastructure for AI agents.**
+
+WorldFoundry gives developers programmable environments where agents can practice real-world
+tasks, interact with simulated systems, learn from failures, and improve through repeated
+experiences.
+
+Build agents anywhere. Train and test them in WorldFoundry.
+
+> **Current status:** this repository builds the `worldfoundry` distribution locally. Check the
+> [PyPI project page](https://pypi.org/project/worldfoundry/) for a published release before
+> using registry install commands. The Homebrew formula is planned and is not published.
+
+## What works now
+
+- A Python SDK and `worldfoundry` / `wf` command-line interface.
+- Persistent, stateful episodes in a simulated support desk.
+- Declared action schemas and validation before actions mutate state.
+- Deterministic task grading with per-check results and a numeric score.
+- Complete traces for starts, successful actions, failed actions, and submissions.
+- JSONL trace export.
+- A dependency-free REST API usable with `curl`.
+- Framework-neutral callables ready to wrap as Google ADK function tools.
+- Local SDK resource registration and sequential callable-agent batch runs with JSON reports.
+
+This is trajectory and evaluation infrastructure. It does **not** perform reinforcement learning,
+fine-tuning, reward-model training, or model-weight updates.
+
+The expanded SDK contract and its current limits are in [`docs/sdk-contract.md`](docs/sdk-contract.md).
+The Supabase control-plane schema, private trace storage, and authenticated Edge API are deployed;
+managed Python workers and customer billing are not yet deployed.
+
+The cloud usage ledger records client-reported episodes for operational visibility; it is not a
+billing system. Stripe metering, verified managed-compute usage, and payment webhooks are not
+connected to the SDK. Source is published at [AMallur/WorldFoundry](https://github.com/AMallur/WorldFoundry).
+The GitHub release workflow verifies the package before publishing through PyPI Trusted
+Publishing.
+
+## Install — verified local
+
+From this repository:
+
+```bash
+python3.13 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e .
+worldfoundry --version
+```
+
+With `uv`, without keeping a virtual environment:
+
+```bash
+uvx --python 3.13 --from . worldfoundry --version
+```
+
+The explicit Python version makes the verification environment reproducible; any supported
+Python 3.11–3.13 interpreter can be used.
+
+### Registry installation
+
+Use these commands only when a release is visible on the
+[PyPI project page](https://pypi.org/project/worldfoundry/):
+
+```bash
+pip install worldfoundry
+uvx worldfoundry
+```
+
+Homebrew distribution is planned. This command does not work until a formula is published:
+
+```bash
+# FUTURE: no Homebrew formula has been published
+brew install worldfoundry/tap/worldfoundry
+```
+
+## One-minute CLI experience
+
+Keep state in a project-local folder while experimenting:
+
+```bash
+export WORLDFOUNDRY_HOME="$PWD/.wf-data"
+
+worldfoundry environments list
+worldfoundry episodes start support-desk --task incident-triage --seed 7
+```
+
+Copy the returned episode ID, then act inside the same persistent simulation:
+
+```bash
+EPISODE_ID=ep_replace_me
+
+worldfoundry episodes act "$EPISODE_ID" get_ticket \
+  --params '{"ticket_id":"TCK-100"}'
+worldfoundry episodes act "$EPISODE_ID" set_priority \
+  --params '{"ticket_id":"TCK-100","priority":"critical"}'
+worldfoundry episodes act "$EPISODE_ID" assign \
+  --params '{"ticket_id":"TCK-100","assignee":"on-call"}'
+worldfoundry episodes act "$EPISODE_ID" reply \
+  --params '{"ticket_id":"TCK-100","message":"We acknowledge the outage and have opened an incident."}'
+worldfoundry episodes act "$EPISODE_ID" resolve \
+  --params '{"ticket_id":"TCK-100"}'
+worldfoundry episodes submit "$EPISODE_ID"
+worldfoundry traces export "$EPISODE_ID" --output trace.jsonl
+```
+
+Submission is a terminal gate. A submitted episode becomes `passed` or `failed` and rejects later
+actions. Start a fresh episode for another attempt.
+
+## Python SDK
+
+```python
+from worldfoundry import WorldFoundry
+
+wf = WorldFoundry(".wf-data")
+episode = wf.start("support-desk", task="incident-triage", seed=7)
+
+wf.act(episode.id, "set_priority", ticket_id="TCK-100", priority="critical")
+wf.act(episode.id, "assign", ticket_id="TCK-100", assignee="on-call")
+wf.act(
+    episode.id,
+    "reply",
+    ticket_id="TCK-100",
+    message="We acknowledge the outage and have opened an incident.",
+)
+wf.act(episode.id, "resolve", ticket_id="TCK-100")
+
+result = wf.submit(episode.id)
+print(result.passed, result.score)
+wf.export_trace(episode.id, "trace.jsonl")
+```
+
+A complete runnable version is in [`examples/python_episode.py`](examples/python_episode.py).
+
+## REST API and `curl`
+
+Start the local server:
+
+```bash
+WORLDFOUNDRY_HOME="$PWD/.wf-data" worldfoundry serve --port 8787
+```
+
+In another terminal:
+
+```bash
+curl -s http://127.0.0.1:8787/health
+
+curl -s -X POST http://127.0.0.1:8787/v1/episodes \
+  -H 'content-type: application/json' \
+  -d '{"environment":"support-desk","task":"incident-triage","seed":7}'
+
+EPISODE_ID=ep_replace_me
+
+curl -s -X POST "http://127.0.0.1:8787/v1/episodes/$EPISODE_ID/actions" \
+  -H 'content-type: application/json' \
+  -d '{"action":"set_priority","parameters":{"ticket_id":"TCK-100","priority":"critical"}}'
+
+curl -s -X POST "http://127.0.0.1:8787/v1/episodes/$EPISODE_ID/submit"
+curl -s "http://127.0.0.1:8787/v1/episodes/$EPISODE_ID/trace" > trace.jsonl
+```
+
+See [`examples/curl_episode.sh`](examples/curl_episode.sh) for an end-to-end REST run that extracts
+the episode ID without requiring `jq`.
+
+## Environment contract
+
+Each environment supplies:
+
+1. An initial state generated from a seed.
+2. A task instruction.
+3. Named actions with parameter schemas.
+4. Stateful action handlers that return observations.
+5. Deterministic validators that produce individual checks, a score, and pass/fail.
+
+All interfaces use the same engine and local store. State lives in
+`$WORLDFOUNDRY_HOME/episodes` or `~/.worldfoundry/episodes` by default. Set the environment variable
+or pass `WorldFoundry(path)` / `--home PATH` for isolated runs.
+
+## Google ADK integration path
+
+`worldfoundry.integrations.adk.tools(client, episode_id)` returns two documented Python callables:
+one for environment actions and one for submission. Google ADK can wrap them as function tools
+without making ADK a hard dependency of the core package. See [`docs/adk.md`](docs/adk.md).
+
+## Path to hosted SaaS
+
+The local contract deliberately maps to a hosted service:
+
+| Local MVP | Hosted evolution |
+|---|---|
+| File-backed episode store | Transactional database plus object storage |
+| In-process environment | Isolated worker or sandbox per episode |
+| Local identity | API keys, workspaces, roles, and scoped tokens |
+| Synchronous action | Idempotent action endpoint with call IDs |
+| JSONL file | Queryable traces plus immutable export |
+| One built-in environment | Versioned environment registry and private environments |
+| Deterministic validator | Versioned eval suites, cohorts, and regression dashboards |
+
+Before a public service, add idempotency keys, optimistic concurrency, tenant isolation, quotas,
+signed artifacts, structured logs, worker timeouts, and compatibility tests for environment
+versions. See [`docs/roadmap.md`](docs/roadmap.md) for release gates.
+
+## Develop and test
+
+```bash
+python3.13 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e '.[dev]'
+python -m pytest
+python -m compileall -q src tests examples
+```
+
+The test suite covers a passing SDK episode, failed-action trace recording, CLI persistence and
+export, REST behavior, invalid parameters, and terminal submission semantics.
+
+## License
+
+Apache-2.0. See [`LICENSE`](LICENSE).
+

worldfoundry-0.2.0/README.md

@@ -0,0 +1,219 @@
+# WorldFoundry
+
+**Training infrastructure for AI agents.**
+
+WorldFoundry gives developers programmable environments where agents can practice real-world
+tasks, interact with simulated systems, learn from failures, and improve through repeated
+experiences.
+
+Build agents anywhere. Train and test them in WorldFoundry.
+
+> **Current status:** this repository builds the `worldfoundry` distribution locally. Check the
+> [PyPI project page](https://pypi.org/project/worldfoundry/) for a published release before
+> using registry install commands. The Homebrew formula is planned and is not published.
+
+## What works now
+
+- A Python SDK and `worldfoundry` / `wf` command-line interface.
+- Persistent, stateful episodes in a simulated support desk.
+- Declared action schemas and validation before actions mutate state.
+- Deterministic task grading with per-check results and a numeric score.
+- Complete traces for starts, successful actions, failed actions, and submissions.
+- JSONL trace export.
+- A dependency-free REST API usable with `curl`.
+- Framework-neutral callables ready to wrap as Google ADK function tools.
+- Local SDK resource registration and sequential callable-agent batch runs with JSON reports.
+
+This is trajectory and evaluation infrastructure. It does **not** perform reinforcement learning,
+fine-tuning, reward-model training, or model-weight updates.
+
+The expanded SDK contract and its current limits are in [`docs/sdk-contract.md`](docs/sdk-contract.md).
+The Supabase control-plane schema, private trace storage, and authenticated Edge API are deployed;
+managed Python workers and customer billing are not yet deployed.
+
+The cloud usage ledger records client-reported episodes for operational visibility; it is not a
+billing system. Stripe metering, verified managed-compute usage, and payment webhooks are not
+connected to the SDK. Source is published at [AMallur/WorldFoundry](https://github.com/AMallur/WorldFoundry).
+The GitHub release workflow verifies the package before publishing through PyPI Trusted
+Publishing.
+
+## Install — verified local
+
+From this repository:
+
+```bash
+python3.13 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e .
+worldfoundry --version
+```
+
+With `uv`, without keeping a virtual environment:
+
+```bash
+uvx --python 3.13 --from . worldfoundry --version
+```
+
+The explicit Python version makes the verification environment reproducible; any supported
+Python 3.11–3.13 interpreter can be used.
+
+### Registry installation
+
+Use these commands only when a release is visible on the
+[PyPI project page](https://pypi.org/project/worldfoundry/):
+
+```bash
+pip install worldfoundry
+uvx worldfoundry
+```
+
+Homebrew distribution is planned. This command does not work until a formula is published:
+
+```bash
+# FUTURE: no Homebrew formula has been published
+brew install worldfoundry/tap/worldfoundry
+```
+
+## One-minute CLI experience
+
+Keep state in a project-local folder while experimenting:
+
+```bash
+export WORLDFOUNDRY_HOME="$PWD/.wf-data"
+
+worldfoundry environments list
+worldfoundry episodes start support-desk --task incident-triage --seed 7
+```
+
+Copy the returned episode ID, then act inside the same persistent simulation:
+
+```bash
+EPISODE_ID=ep_replace_me
+
+worldfoundry episodes act "$EPISODE_ID" get_ticket \
+  --params '{"ticket_id":"TCK-100"}'
+worldfoundry episodes act "$EPISODE_ID" set_priority \
+  --params '{"ticket_id":"TCK-100","priority":"critical"}'
+worldfoundry episodes act "$EPISODE_ID" assign \
+  --params '{"ticket_id":"TCK-100","assignee":"on-call"}'
+worldfoundry episodes act "$EPISODE_ID" reply \
+  --params '{"ticket_id":"TCK-100","message":"We acknowledge the outage and have opened an incident."}'
+worldfoundry episodes act "$EPISODE_ID" resolve \
+  --params '{"ticket_id":"TCK-100"}'
+worldfoundry episodes submit "$EPISODE_ID"
+worldfoundry traces export "$EPISODE_ID" --output trace.jsonl
+```
+
+Submission is a terminal gate. A submitted episode becomes `passed` or `failed` and rejects later
+actions. Start a fresh episode for another attempt.
+
+## Python SDK
+
+```python
+from worldfoundry import WorldFoundry
+
+wf = WorldFoundry(".wf-data")
+episode = wf.start("support-desk", task="incident-triage", seed=7)
+
+wf.act(episode.id, "set_priority", ticket_id="TCK-100", priority="critical")
+wf.act(episode.id, "assign", ticket_id="TCK-100", assignee="on-call")
+wf.act(
+    episode.id,
+    "reply",
+    ticket_id="TCK-100",
+    message="We acknowledge the outage and have opened an incident.",
+)
+wf.act(episode.id, "resolve", ticket_id="TCK-100")
+
+result = wf.submit(episode.id)
+print(result.passed, result.score)
+wf.export_trace(episode.id, "trace.jsonl")
+```
+
+A complete runnable version is in [`examples/python_episode.py`](examples/python_episode.py).
+
+## REST API and `curl`
+
+Start the local server:
+
+```bash
+WORLDFOUNDRY_HOME="$PWD/.wf-data" worldfoundry serve --port 8787
+```
+
+In another terminal:
+
+```bash
+curl -s http://127.0.0.1:8787/health
+
+curl -s -X POST http://127.0.0.1:8787/v1/episodes \
+  -H 'content-type: application/json' \
+  -d '{"environment":"support-desk","task":"incident-triage","seed":7}'
+
+EPISODE_ID=ep_replace_me
+
+curl -s -X POST "http://127.0.0.1:8787/v1/episodes/$EPISODE_ID/actions" \
+  -H 'content-type: application/json' \
+  -d '{"action":"set_priority","parameters":{"ticket_id":"TCK-100","priority":"critical"}}'
+
+curl -s -X POST "http://127.0.0.1:8787/v1/episodes/$EPISODE_ID/submit"
+curl -s "http://127.0.0.1:8787/v1/episodes/$EPISODE_ID/trace" > trace.jsonl
+```
+
+See [`examples/curl_episode.sh`](examples/curl_episode.sh) for an end-to-end REST run that extracts
+the episode ID without requiring `jq`.
+
+## Environment contract
+
+Each environment supplies:
+
+1. An initial state generated from a seed.
+2. A task instruction.
+3. Named actions with parameter schemas.
+4. Stateful action handlers that return observations.
+5. Deterministic validators that produce individual checks, a score, and pass/fail.
+
+All interfaces use the same engine and local store. State lives in
+`$WORLDFOUNDRY_HOME/episodes` or `~/.worldfoundry/episodes` by default. Set the environment variable
+or pass `WorldFoundry(path)` / `--home PATH` for isolated runs.
+
+## Google ADK integration path
+
+`worldfoundry.integrations.adk.tools(client, episode_id)` returns two documented Python callables:
+one for environment actions and one for submission. Google ADK can wrap them as function tools
+without making ADK a hard dependency of the core package. See [`docs/adk.md`](docs/adk.md).
+
+## Path to hosted SaaS
+
+The local contract deliberately maps to a hosted service:
+
+| Local MVP | Hosted evolution |
+|---|---|
+| File-backed episode store | Transactional database plus object storage |
+| In-process environment | Isolated worker or sandbox per episode |
+| Local identity | API keys, workspaces, roles, and scoped tokens |
+| Synchronous action | Idempotent action endpoint with call IDs |
+| JSONL file | Queryable traces plus immutable export |
+| One built-in environment | Versioned environment registry and private environments |
+| Deterministic validator | Versioned eval suites, cohorts, and regression dashboards |
+
+Before a public service, add idempotency keys, optimistic concurrency, tenant isolation, quotas,
+signed artifacts, structured logs, worker timeouts, and compatibility tests for environment
+versions. See [`docs/roadmap.md`](docs/roadmap.md) for release gates.
+
+## Develop and test
+
+```bash
+python3.13 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e '.[dev]'
+python -m pytest
+python -m compileall -q src tests examples
+```
+
+The test suite covers a passing SDK episode, failed-action trace recording, CLI persistence and
+export, REST behavior, invalid parameters, and terminal submission semantics.
+
+## License
+
+Apache-2.0. See [`LICENSE`](LICENSE).
+

worldfoundry-0.2.0/docs/adk.md

@@ -0,0 +1,24 @@
+# Google ADK integration
+
+The local package exposes framework-neutral Python functions instead of taking a hard dependency
+on Google ADK:
+
+```python
+from worldfoundry import WorldFoundry
+from worldfoundry.integrations.adk import tools
+
+client = WorldFoundry(".wf-data")
+episode = client.start("support-desk")
+agent_tools = tools(client, episode.id)
+```
+
+In an ADK application, pass `agent_tools` to the agent's `tools` argument. The agent can call
+`worldfoundry_action(action, parameters)` repeatedly and then call `worldfoundry_submit()`.
+
+The application, not the adapter, controls the model, retry policy, budgets, and loop termination.
+Treat a validation result as an evaluation signal; this adapter does not train or update model
+weights.
+
+Before publishing a dedicated `worldfoundry-adk` extra, pin a supported ADK version, add an
+end-to-end example against that version, and test generated function schemas in CI.
+

worldfoundry-0.2.0/docs/roadmap.md

@@ -0,0 +1,50 @@
+# Product and distribution roadmap
+
+## Already implemented in this repository
+
+- Installable local Python project with SDK and two CLI entry points.
+- Persistent stateful episodes and deterministic validators.
+- JSONL traces and exports.
+- Local HTTP API and end-to-end examples.
+- Framework-neutral Google ADK tool adapter.
+- Automated tests.
+
+## Release gates
+
+### PyPI and `uvx`
+
+1. Confirm and reserve the `worldfoundry` distribution name through the package owner's PyPI account.
+2. Add trusted publishing from tagged releases.
+3. Build wheel and source distribution, inspect their contents, and test each in clean Python
+   3.11–3.13 environments.
+4. Publish to TestPyPI, run the documented install flow, then publish to PyPI.
+5. Only after that change the README from future commands to verified public commands.
+
+### Homebrew
+
+1. Create a tap owned by the company.
+2. Generate a formula from the signed PyPI source artifact and its SHA-256 checksum.
+3. Test on current Intel and Apple Silicon macOS runners.
+4. Add release automation and a rollback procedure.
+
+### Hosted SaaS
+
+1. Freeze and version the REST contract.
+2. Add workspaces, API keys, tenant authorization, quotas, metering, and audit logs.
+3. Run each episode in a time- and resource-bounded isolated worker.
+4. Require client-generated idempotency keys on action calls and reject conflicting replays.
+5. Store traces immutably and keep mutable query indexes separate.
+6. Add environment bundles with manifests, versioning, signatures, and compatibility checks.
+7. Add hosted SDK transport while keeping the local transport for tests and offline development.
+
+### Training and evaluation platform
+
+1. Batch episode creation with dataset row identifiers and controlled seeds.
+2. Eval-suite manifests, baselines, regression thresholds, and run comparison.
+3. Human review queues and feedback exports.
+4. Integrations for agent frameworks, CI systems, and experiment trackers.
+
+Actual RL, fine-tuning, reward-model training, and weight updates remain separate systems. A future
+WorldFoundry service may export trajectories and scores to those systems without claiming to be
+the optimizer itself.
+

worldfoundry-0.2.0/docs/sdk-contract.md

@@ -0,0 +1,81 @@
+# WorldFoundry SDK contract and deployment boundary
+
+## Working locally
+
+The `worldfoundry` distribution installs the `worldfoundry` import and CLI. The SDK runs
+on the user's computer and uses a local resource registry plus the existing episode engine.
+
+```python
+from worldfoundry import WorldFoundry
+
+def agent(task, tools):
+    tools.set_priority(ticket_id="TCK-100", priority="critical")
+    tools.assign(ticket_id="TCK-100", assignee="on-call")
+    tools.reply(ticket_id="TCK-100", message="We acknowledge the outage and opened an incident.")
+    tools.resolve(ticket_id="TCK-100")
+    tools.submit()
+
+wf = WorldFoundry.local(".wf-data")
+env = wf.environments.create(template="customer_support", difficulty="beginner")
+registered = wf.agents.register(name="support", handler=agent)
+run = wf.training.create(agent=registered, environment=env, episodes=10, seed=42)
+print(run.summary, run.report_path)
+```
+
+Local resource managers presently include `projects`, `environments`, `agents`, `scenarios`,
+`datasets`, `policies`, and `feedback`. Generic resource managers persist metadata, but only the
+built-in support desk environment, Python callable agents, and sequential batch execution are
+executable. A local agent registration's callable exists only in its Python process; the metadata
+record is persistent, but the handler must be registered again after restart. `max_steps` is
+enforced. `concurrency=1` is currently required. Advanced difficulty and remote endpoint agents
+are rejected explicitly. `report_path` is a local JSON file; no hosted report URL is fabricated.
+
+The lower-level `start`, `act`, `submit`, `export_trace`, REST, and CLI episode APIs remain usable.
+
+## Cloud client boundary
+
+`WorldFoundry(api_key="SUPABASE_USER_ACCESS_TOKEN", base_url="https://<ref>.supabase.co/functions/v1/worldfoundry-api")` constructs an
+authenticated HTTP client. The token is a signed-in user's Supabase access token, not a project
+publishable key or a service-role key. It sends `/v1/projects`, `/v1/environments`, `/v1/agents`,
+`/v1/scenarios`, `/v1/datasets`, `/v1/training-runs`, and `/v1/episodes` requests. The cloud
+client is a transport contract, not a deployed service. A Supabase database alone cannot execute
+arbitrary Python agents or isolated simulation workers; it needs a WorldFoundry API and runner.
+
+The project `bhvffruseefvifjcutzj` has the schema applied and the `worldfoundry-api` Edge Function
+deployed at `https://bhvffruseefvifjcutzj.supabase.co/functions/v1/worldfoundry-api`. The API
+authenticates Supabase user access tokens and performs project-scoped database operations through
+row level security. A publishable key alone is not a user session.
+
+```python
+from worldfoundry.cloud import CloudWorldFoundry
+
+wf = CloudWorldFoundry.sign_in(
+    project_url="https://bhvffruseefvifjcutzj.supabase.co",
+    publishable_key="<the project's publishable key>",
+    email="<your signed-up email>",
+    password="<your password>",
+)
+project = wf.projects.create(name="My agent lab")
+environment = wf.environments.create(
+    project_id=project["id"], name="Support desk", template="support-desk"
+)
+agent = wf.agents.register(
+    project_id=project["id"], name="Support agent", framework="python"
+)
+result = wf.training.run_local(
+    project_id=project["id"], agent=agent, environment=environment,
+    handler=my_agent, episodes=10,
+)
+print(result["summary"])
+```
+
+`run_local` executes the agent and simulations on the user's computer, then records episode scores
+and private JSONL traces in the Supabase project. It does not offer managed remote execution.
+The cloud API creates run records but has no hosted Python worker attached, so bare
+`wf.training.create(...)` leaves a queued run until a runner processes it. The deployed endpoint
+is live; signed-in end-to-end execution still needs a user account and session for verification.
+
+For managed execution, add a durable queue, isolated Python workers, trace artifact storage,
+worker authentication, and report generation. Store provider secrets in a managed secret service;
+never put raw secrets in run traces or resource config.
+