monkeybot 2.1.1__tar.gz → 2.2.0__tar.gz

{monkeybot-2.1.1 → monkeybot-2.2.0}/.dockerignore

@@ -7,9 +7,6 @@
 **/.pytest_cache
 **/.mypy_cache
 **/.ruff_cache
-demo_agent/.emonk
-demo_agent/workspace/data/*.db
-demo_agent/workspace/data/*.db-*
 **/.env
 **/*.db-shm
 **/*.db-wal

monkeybot-2.2.0/.github/workflows/live-eval-smoke.yml

@@ -0,0 +1,199 @@
+name: Live eval smoke
+
+# Runs the live eval smoke suite (see docs/live-evals.md) and posts a Markdown
+# scorecard. LLM-judge calls cost money and take minutes, so this does not run on
+# ordinary feature-branch -> develop PRs. Trigger points:
+#   (a) any PR from develop into main (release-promotion gate; --fail-on-regression)
+#   (b) any PR that touches a dependency lockfile (catches silent SDK breakage,
+#       e.g. provider request/response shape changes, that code review won't see)
+#   (c) every push to main (scores the new release; report-only, never fails the build)
+#   (d) manual: Actions tab -> Live eval smoke -> Run workflow
+# The scorecard always lands on the workflow run's Summary page; PR events also get it
+# as a PR comment. The run JSON is uploaded as an artifact — download two of them and
+# compare with `uv run python -m evals.diff <old.json> <new.json>`.
+#
+# Cost/time budget: smoke suite is ~7 scenarios x 2-5 turns x (agent call + judge call).
+# Expect roughly $0.50-2.00 and 5-10 minutes per run depending on model pricing.
+#
+# Secrets required: NVIDIA_API_KEY only (https://build.nvidia.com — free tier). The agent
+# and the judge both run on NVIDIA-hosted models through the same key, pinned to two
+# *different* models below so the judge isn't grading its own output and scoring doesn't
+# silently drift.
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  gate:
+    runs-on: ubuntu-latest
+    outputs:
+      run: ${{ steps.decide.outputs.run }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - id: decide
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          BASE_REF: ${{ github.base_ref }}
+          HEAD_REF: ${{ github.head_ref }}
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          run=false
+          # Push to main and manual dispatch always run; PRs are gated below.
+          if [[ "$EVENT_NAME" != "pull_request" ]]; then
+            run=true
+          else
+            if [[ "$BASE_REF" == "main" && "$HEAD_REF" == "develop" ]]; then
+              run=true
+            fi
+            changed="$(git diff --name-only "$BASE_SHA" "$HEAD_SHA")"
+            for f in uv.lock cli/uv.lock evals/smoke_agent/uv.lock; do
+              if grep -qxF "$f" <<<"$changed"; then
+                run=true
+              fi
+            done
+          fi
+          echo "run=$run" >> "$GITHUB_OUTPUT"
+
+  secrets:
+    needs: gate
+    if: needs.gate.outputs.run == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Require live-eval secrets
+        env:
+          NVIDIA_API_KEY: ${{ secrets.NVIDIA_API_KEY }}
+        run: |
+          if [[ -z "$NVIDIA_API_KEY" ]]; then
+            echo "::error::Live eval smoke requires the NVIDIA_API_KEY repository secret (agent + judge models, https://build.nvidia.com)"
+            exit 1
+          fi
+
+  live-eval:
+    needs: [gate, secrets]
+    if: needs.gate.outputs.run == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Sync root deps (evals/report.py needs deepeval, langfuse)
+        run: uv sync --extra evals
+
+      - name: Sync smoke_agent deps
+        working-directory: evals/smoke_agent
+        run: uv sync
+
+      - name: Boot monkeybot gateway (evals/smoke_agent workspace)
+        working-directory: evals/smoke_agent
+        env:
+          NVIDIA_API_KEY: ${{ secrets.NVIDIA_API_KEY }}
+          # Pin agent model for CI; env beats monkeybot.yaml.
+          MODEL_PROVIDER: nvidia
+          MODEL_NAME: meta/llama-3.3-70b-instruct
+          # smoke_agent monkeybot.yaml sets runtime.port: 8080; the health check and
+          # AGENT_URL below expect 8787, so pin PORT explicitly (env beats yaml).
+          PORT: "8787"
+          SANDBOX_ENABLED: "false" # no Docker socket in this runner
+          # Small context window so context/summarization_trigger.yaml actually crosses the
+          # real summarization threshold; the other smoke scenarios are short enough to fit.
+          MODEL_CONTEXT_WINDOW: "8000"
+        run: |
+          uv run -m monkeybot.gateway.main > /tmp/gateway.log 2>&1 &
+          echo $! > /tmp/gateway.pid
+          for i in $(seq 1 30); do
+            if curl -sf http://127.0.0.1:8787/health > /dev/null; then
+              echo "gateway healthy"
+              exit 0
+            fi
+            sleep 2
+          done
+          echo "gateway did not become healthy" >&2
+          cat /tmp/gateway.log >&2
+          exit 1
+
+      - name: Run smoke suite report
+        env:
+          AGENT_URL: http://127.0.0.1:8787
+          # Judge on a different free NVIDIA-hosted model than the agent (same key).
+          JUDGE_PROVIDER: nvidia
+          JUDGE_MODEL: nvidia/llama-3.3-nemotron-super-49b-v1
+          NVIDIA_API_KEY: ${{ secrets.NVIDIA_API_KEY }}
+          # Scorecard metadata: report the model the gateway actually ran.
+          MODEL_PROVIDER: nvidia
+          MODEL_NAME: meta/llama-3.3-70b-instruct
+          EVENT_NAME: ${{ github.event_name }}
+        run: |
+          # PRs are a gate and must block on regressions; main pushes and manual runs
+          # just score the build and always report. --fail-on-regression always blocks on
+          # this run's own scenario errors/failures. It does NOT require evals/baselines/
+          # smoke.json to exist (that's the separate --require-baseline flag, intentionally
+          # omitted below) — no trusted baseline has been committed yet. Once one has
+          # (`uv run python -m evals.report --suite smoke --update-baseline`, committed),
+          # add --require-baseline here too so a missing/deleted file can't silently skip
+          # the token/cost/latency drift checks.
+          flags=""
+          if [[ "$EVENT_NAME" == "pull_request" ]]; then
+            flags="--fail-on-regression"
+          fi
+          uv run python -m evals.report \
+            --suite smoke \
+            --baseline evals/baselines/smoke.json \
+            $flags \
+            | tee eval-report.md
+
+      - name: Publish report to run summary
+        if: always()
+        run: |
+          if [[ -f eval-report.md ]]; then
+            cat eval-report.md >> "$GITHUB_STEP_SUMMARY"
+          else
+            echo '`FAIL` — no report produced; see the job logs.' >> "$GITHUB_STEP_SUMMARY"
+          fi
+
+      - name: Post report as PR comment
+        if: always() && github.event_name == 'pull_request'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require("fs");
+            const body = fs.existsSync("eval-report.md")
+              ? fs.readFileSync("eval-report.md", "utf8")
+              : "## monkeybot Eval Scorecard\n\n`FAIL` — the report step did not complete " +
+                "(gateway boot or the report command itself errored before writing a report). " +
+                "See the workflow run logs for details.";
+            await github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body,
+            });
+
+      - name: Upload run + report artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: live-eval-smoke-${{ github.run_id }}
+          path: |
+            evals/runs/
+            eval-report.md
+          if-no-files-found: ignore
+
+      - name: Stop gateway
+        if: always()
+        working-directory: evals/smoke_agent
+        run: kill "$(cat /tmp/gateway.pid)" 2>/dev/null || true

{monkeybot-2.1.1 → monkeybot-2.2.0}/.github/workflows/prepare-release.yml

@@ -7,7 +7,7 @@ on:
         description: "Which package to release"
         required: true
         type: choice
-        options: [core, cli]
+        options: [core, browser, cli, all]
       bump:
         description: "Version bump"
         required: true

{monkeybot-2.1.1 → monkeybot-2.2.0}/.github/workflows/publish-release.yml

@@ -9,6 +9,7 @@ name: Publish release
 #                  Workflow publish-release.yml / Environment pypi
 #   monkeybot-cli: Owner human-plus-machine / Repo monkeybot /
 #                  Workflow publish-release.yml / Environment pypi-cli
+#   monkeybot-browser-mcp: same workflow / Environment pypi-browser
 #
 # GitHub: create Environments named exactly `pypi` and `pypi-cli`.
 on:
@@ -17,6 +18,8 @@ on:
     paths:
       - "pyproject.toml"
       - "cli/pyproject.toml"
+      - "integrations/browser-mcp/pyproject.toml"
+      - "docker/sandbox.Dockerfile"
       - "CHANGELOG.md"
 
 permissions:
@@ -68,14 +71,15 @@ jobs:
           skip-existing: true
 
   pypi-cli:
-    needs: [publish, pypi-core]
+    needs: [publish, pypi-core, pypi-browser]
     # Run when cli is in the release set. If core wasn't released this run,
     # pypi-core is skipped — treat that as success so cli can still publish.
     if: |
       always() &&
       needs.publish.result == 'success' &&
       contains(format(',{0},', needs.publish.outputs.packages), ',cli,') &&
-      (needs.pypi-core.result == 'success' || needs.pypi-core.result == 'skipped')
+      (needs.pypi-core.result == 'success' || needs.pypi-core.result == 'skipped') &&
+      (needs.pypi-browser.result == 'success' || needs.pypi-browser.result == 'skipped')
     runs-on: ubuntu-latest
     environment:
       name: pypi-cli
@@ -96,3 +100,50 @@ jobs:
         with:
           packages-dir: dist/cli
           skip-existing: true
+
+  pypi-browser:
+    needs: publish
+    if: contains(format(',{0},', needs.publish.outputs.packages), ',browser,')
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi-browser
+      url: https://pypi.org/p/monkeybot-browser-mcp
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build browser MCP
+        run: uv build --out-dir dist/browser integrations/browser-mcp
+      - name: Publish browser MCP to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/browser
+          skip-existing: true
+
+  sandbox-image:
+    needs: publish
+    if: contains(format(',{0},', needs.publish.outputs.packages), ',core,')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - id: version
+        run: echo "value=$(python -c \"import re; print(re.search(r'^version = \\\"([^\\\"]+)', open('pyproject.toml').read(), re.M).group(1))\")" >> "$GITHUB_OUTPUT"
+      - uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: docker/sandbox.Dockerfile
+          push: true
+          tags: ghcr.io/human-plus-machine/monkeybot-sandbox:${{ steps.version.outputs.value }}

{monkeybot-2.1.1 → monkeybot-2.2.0}/.gitignore

@@ -9,9 +9,6 @@ internal/
 # Local scaffolded harness config (defaults ship in monkeybot-cli scaffold_defaults/)
 /monkeybot_config/
 
-# Demo agent live config (materialized from monkeybot_config_example/ by demo_agent/run.sh)
-demo_agent/monkeybot_config/
-
 # Live eval run artifacts (only evals/baselines/ is versioned)
 /evals/runs/
 
@@ -40,6 +37,7 @@ data/
 htmlcov/
 .mypy_cache/
 .ruff_cache/
+.deepeval/
 
 # macOS
 .DS_Store

{monkeybot-2.1.1 → monkeybot-2.2.0}/BACKLOG.md

@@ -13,7 +13,7 @@
 - **Memory accuracy verification** — script exists (`scripts/verify_memory.py`) but needs a real eval strategy, not a one-off script.
 
 ### 3. Scheduler
-- Wire a `Scheduler` into the FastAPI lifespan as an optional background task when `config.yaml` has `scheduler.jobs` (reference: `legacy/src/monkeybot/core/scheduler.py`).
+- Wire a `Scheduler` into the FastAPI lifespan as an optional background task when `config.yaml` has `scheduler.jobs`.
 - Needs significant design work for cloud runtimes: Lambda/Cloud Functions have no persistent process, GKE/ECS can use sidecar or CronJob, etc. Think through heartbeat / self-scheduling before implementing.
 
 ### 4. Sandbox Workspace Protection
@@ -30,8 +30,8 @@
 - Worker pool: standalone `python -m monkeybot.subagents.worker` consumes queued runs with atomic `claim()` (recommended for production — its own event loop, scales independently of the gateway). `MONKEYBOT_WORKER_POOL=1` runs the same loop in-process on the gateway and is development-only (competes with the SSE event loop).
 
 ### 7. CLI-managed optional service dependencies
-- `monkeybot chat` / `run` only spawn the gateway process; they don't start the Docker-backed optional services some `monkeybot.yaml` configs require: OpenSandbox (`sandbox.enabled`), Firestore emulator (`paths.db_url: firestore://...`), or the observability stack (Phoenix/Langfuse/OTel collector). `demo_agent/run.sh` currently does this orchestration via bash (build/start/health-check/cleanup), which means the CLI alone can't fully run an agent that uses those features.
-- Decide and implement: should the CLI (`doctor`, `run`, `chat`) detect these from config and actually start/stop the containers (matching `run.sh` behavior, retiring the bash script), or just validate/warn with remediation hints while the user manages Docker manually?
+- `monkeybot chat` / `run` only spawn the gateway process; they don't start the Docker-backed optional services some `monkeybot.yaml` configs require: OpenSandbox (`sandbox.enabled`), Firestore emulator (`paths.db_url: firestore://...`), or the observability stack (Phoenix/Langfuse/OTel collector). Those used to be orchestrated by a demo `run.sh`; the CLI alone still can't fully run an agent that uses those features.
+- Decide and implement: should the CLI (`doctor`, `run`, `chat`) detect these from config and actually start/stop the containers, or just validate/warn with remediation hints while the user manages Docker manually?
 - Open sub-questions if going the "CLI starts services" route: where do per-project Docker assets live (`opensandbox.docker.toml`, OTel collector yaml, compose files) — agent-project-owned files referenced from `monkeybot.yaml`, or CLI-shipped generic templates; and is the sandbox worker image (project-specific extra deps) something the CLI should build, or stay manual/documented.
 
 ---
@@ -39,9 +39,9 @@
 ## Do Later
 
 ### Connectors
-- **CLI gateway** — interactive stdin/stdout (reference: `legacy/src/monkeybot/gateway/cli.py`).
-- **Webhook gateway** — generic HTTP + HMAC (reference: `legacy/src/monkeybot/gateway/webhook.py`).
-- **`python -m monkeybot` CLI** — `run` / `serve` / `usage` / `schedule` subcommands (reference: `legacy/src/monkeybot/cli.py`).
+- **CLI gateway** — interactive stdin/stdout beyond the existing `monkeybot chat` / `talk` clients.
+- **Webhook gateway** — generic HTTP + HMAC ingress for third-party chat products.
+- **Expanded `python -m monkeybot` surface** — additional operator subcommands (`usage` / `schedule`, etc.) as needed.
 
 ### Cloud Deployments
 - **GCP server** — GCE / GKE deployment option (docs + examples exist; no IaC).
@@ -56,7 +56,7 @@
 - **INDEX.md size cap** *(deferred 2026-05-15)* — `MemoryOrganizer` appends without bound; acceptable for now via `ContextCurator` selection. When indices grow wastefully large, cap with a sliding window (N=200, archive to `INDEX.archive.md`) in `core/memory_organizer.py`.
 
 ### MCP
-- **MCP distro linkage** — confirm `monkeybot_config_example/monkeybot.example.yaml` paths (`paths.mcp_config`, `paths.skills_path`) match deployment; smoke-test against real MCP servers beyond the bundled LangChain docs URL.
+- **MCP distro linkage** — confirm scaffolded `monkeybot.yaml` paths (`paths.mcp_config`, `paths.skills_path`) match deployment; smoke-test against real MCP servers beyond the bundled examples.
 
 ### Future platforms *(not scheduled)*
 

{monkeybot-2.1.1 → monkeybot-2.2.0}/CHANGELOG.md

@@ -6,10 +6,50 @@ the project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [core v2.2.0] - 2026-07-13
+
+### Added
+
+- Canonical agent-root layout and a read-only virtual `skills/` root.
+
+### Changed
+
+- Remote sandboxes require an explicit compute-only capability setting.
+
+### Breaking
+
+- Workspace or skills symlinks that resolve outside their respective roots are now rejected. Move their targets inside the agent's `workspace/`, `data/`, or `skills/` layout.
+
+## [browser v0.2.0] - 2026-07-13
+
+### Added
+
+- Browser MCP package release supporting the canonical agent layout.
+
+## [cli v0.3.0] - 2026-07-13
+
+### Added
+
+- Agent scaffolds now include the canonical layout, Dockerfile, and disabled browser MCP configuration.
+
+### Fixed
+
+- `monkeybot chat` no longer adopts a stale gateway on a busy port: it refuses to spawn when the port is already in use (suggesting `/bye`, stopping `monkeybot run`, or `--attach`), and `wait_for_health` rejects a `/health` 200 if the child process has already exited.
+
+## [0.2.1] - 2026-07-13
+
+### Added
+
+- First PyPI release of **monkeybot-cli** (Trusted Publishing) — install with `uv tool install monkeybot-cli`.
+
+
 ## [2.1.1] - 2026-07-13
 
 ### Added
 
+- Evals: `response_regex` and `response_not_contains` deterministic assertions; run files now persist per-turn prompt/response text, and `python -m evals.diff` pinpoints the exact turn behind a regression between two runs.
+- Live eval smoke workflow now also runs on every push to `main` (report-only, scorecard on the run Summary page) and on manual dispatch, in addition to the existing PR gates.
+- Live evals need only `NVIDIA_API_KEY`: the deepeval judge can now run on build.nvidia.com models (`JUDGE_PROVIDER=nvidia`) via NVIDIA's OpenAI-compatible endpoint, and CI pins agent (`meta/llama-3.3-70b-instruct`) and judge (`nvidia/llama-3.3-nemotron-super-49b-v1`) to two different free NVIDIA-hosted models. The workflow also now sets `MODEL_PROVIDER`/`MODEL_NAME` explicitly — previously it booted whatever `demo_agent`'s committed config said (ollama, which doesn't exist in CI).
 - Repo-root `monkeybot_config_example/` — full-option human-readable config templates (`.example` filenames).
 - `monkeybot new` also scaffolds `permissions.yaml`.
 - `monkeybot new` writes an agent-project `pyproject.toml` with a PyPI `monkeybot[<provider>]>=2.1.0,<3` dependency (plain `uv sync` after scaffold).
@@ -18,6 +58,10 @@ the project adheres to [Semantic Versioning](https://semver.org/).
 - README / getting-started / onboarding skill lead with `uv tool install monkeybot-cli` (clone is contributor-only).
 - **monkeybot-cli** declares published core bound `monkeybot[cli]>=2.1.0,<3` (local clones still use `[tool.uv.sources]`).
 
+### Removed
+
+- Evals FastAPI service (`evals/main.py`, in-memory store, WebSocket fan-out, Dockerfile, `docker-compose.evals.yml`) — nothing consumed its HTTP/WS API; `python -m evals.report` is the single execution path. `google-genai` (Gemini judge dep) moved into the root `evals` extra.
+
 ### Changed
 
 - `monkeybot doctor` remediation for missing extras: add `monkeybot[<extra>]` to agent deps + `uv sync` (keeps `uv sync --extra` only when the agent defines project-level optionals).

monkeybot-2.2.0/CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing
+
+Thanks for helping improve monkeybot. Report bugs and doc gaps via [issues](https://github.com/human-plus-machine/monkeybot/issues); PRs for fixes and improvements are welcome.
+
+## Developing the harness
+
+Clone only if you are changing monkeybot itself (end users should use `uv tool install monkeybot-cli` — see the [README](README.md)):
+
+```bash
+git clone https://github.com/human-plus-machine/monkeybot.git
+cd monkeybot && uv sync
+cd cli && uv sync
+uv tool install --editable .
+```
+
+For live eval smoke runs against a local gateway, use [`evals/smoke_agent/`](evals/smoke_agent/) (see [docs/live-evals.md](docs/live-evals.md)).
+
+### Checks
+
+CI runs `mypy` on `src/monkeybot` and pytest (root, `cli/`, `integrations/browser-mcp/`), plus standalone eval self-checks. Before submitting:
+
+```bash
+uv run pytest
+uv run mypy src/monkeybot
+```
+
+`ruff` is useful locally but is not a CI gate today.
+
+> [!NOTE]
+> Do not run the root pytest suite with a scaffolded `monkeybot_config/` + `workspace/` at the repo root — that layout can make a couple of workspace-resolution tests fail. CI uses a clean tree.
+
+## Releasing
+
+`develop` is the working branch; `main` always reflects the latest release.
+
+1. Anyone runs the **Prepare release** workflow (Actions tab → Prepare release → Run workflow), choosing `core`, `browser`, or `cli` and a version bump. It bumps the package's `pyproject.toml`, moves the `CHANGELOG.md` `Unreleased` section into a dated entry on a `release/<package>-v<version>` branch, and opens a PR from that branch into `main` (`develop` itself is untouched until the PR merges, so an abandoned release PR leaves no trace).
+2. An admin reviews and **merges the PR** (branch protection on `main` restricts who can merge). Use a regular merge commit, not squash, so `main`'s history and the release tag line up with what was reviewed.
+3. The **Publish release** workflow runs automatically on that merge: it tags the new version, creates a GitHub Release from the changelog entry, Trusted-Publishes the released package(s) to PyPI (core and browser before CLI when both ship), publishes the sandbox image with a core release, and merges `main` back into `develop` so the two branches don't drift apart.
+
+One-time setup (repo Settings → Branches → add rule for `main`): require a pull request before merging, and restrict who can push to matching branches to Admins. That's the only access control needed — anyone can prepare a release, only admins can promote it to `main`.
+
+**Before relying on this:** `develop` and `main` currently have diverged history (independent commits on each side). Reconcile them once with a manual merge before running the first automated release, or the first release PR may show unrelated changes or conflicts. `CHANGELOG.md` is shared across both packages — `core` and `cli` versions are bumped independently but their release notes live in the same file. The current versions already on `main` (`core` 2.0.0, `cli` 0.1.7) predate this tooling and have no changelog entry, so the first `publish` run intentionally skips tagging them rather than creating a release with empty notes; tagging starts from the next real version bump.

monkeybot-2.2.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: monkeybot
+Version: 2.2.0
+Summary: monkeybot agent harness — FastAPI SSE gateway, owned loop, SQLite, and MCP.
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: aiosqlite>=0.20.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: google-genai>=1.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: python-ulid>=2.0.0
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: uvicorn[standard]>=0.32.0
+Provides-Extra: aws
+Requires-Dist: boto3>=1.34.0; extra == 'aws'
+Provides-Extra: bedrock
+Requires-Dist: anthropic[bedrock]>=0.40.0; extra == 'bedrock'
+Requires-Dist: boto3>=1.34.0; extra == 'bedrock'
+Provides-Extra: claude
+Requires-Dist: anthropic>=0.40.0; extra == 'claude'
+Provides-Extra: cli
+Requires-Dist: typer>=0.12.0; extra == 'cli'
+Requires-Dist: websockets>=14.0; extra == 'cli'
+Provides-Extra: cli-realtime
+Requires-Dist: pyaudio>=0.2.11; extra == 'cli-realtime'
+Requires-Dist: pynput>=1.7.6; extra == 'cli-realtime'
+Requires-Dist: typer>=0.12.0; extra == 'cli-realtime'
+Requires-Dist: websockets>=14.0; extra == 'cli-realtime'
+Provides-Extra: council
+Requires-Dist: google-cloud-storage>=2.18.0; extra == 'council'
+Provides-Extra: evals
+Requires-Dist: deepeval>=3.0.0; extra == 'evals'
+Requires-Dist: google-genai>=1.0.0; extra == 'evals'
+Requires-Dist: langfuse>=3.0.0; extra == 'evals'
+Provides-Extra: firestore
+Requires-Dist: google-cloud-firestore>=2.16.0; extra == 'firestore'
+Provides-Extra: gcs
+Requires-Dist: google-cloud-storage>=2.18.0; extra == 'gcs'
+Provides-Extra: gemini
+Requires-Dist: google-genai>=1.0.0; extra == 'gemini'
+Provides-Extra: huggingface
+Requires-Dist: openai>=1.0; extra == 'huggingface'
+Requires-Dist: tiktoken>=0.7.0; extra == 'huggingface'
+Provides-Extra: nvidia
+Requires-Dist: openai>=1.0; extra == 'nvidia'
+Requires-Dist: tiktoken>=0.7.0; extra == 'nvidia'
+Provides-Extra: observability
+Requires-Dist: opentelemetry-api>=1.28; extra == 'observability'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.28; extra == 'observability'
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.62b1; extra == 'observability'
+Requires-Dist: opentelemetry-sdk>=1.28; extra == 'observability'
+Provides-Extra: ollama
+Requires-Dist: openai>=1.0; extra == 'ollama'
+Requires-Dist: tiktoken>=0.7.0; extra == 'ollama'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == 'openai'
+Requires-Dist: tiktoken>=0.7.0; extra == 'openai'
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.29.0; extra == 'postgres'
+Provides-Extra: realtime
+Requires-Dist: websockets>=14.0; extra == 'realtime'
+Provides-Extra: realtime-gemini
+Requires-Dist: google-genai>=1.0.0; extra == 'realtime-gemini'
+Requires-Dist: websockets>=14.0; extra == 'realtime-gemini'
+Provides-Extra: sandbox
+Requires-Dist: opensandbox>=0.1.7; extra == 'sandbox'
+Provides-Extra: scheduler
+Requires-Dist: croniter>=2.0; extra == 'scheduler'
+Provides-Extra: vertex
+Requires-Dist: google-api-python-client>=2.150.0; extra == 'vertex'
+Requires-Dist: google-auth>=2.35.0; extra == 'vertex'
+Requires-Dist: google-genai>=1.0.0; extra == 'vertex'
+Provides-Extra: vertex-claude
+Requires-Dist: anthropic[vertex]>=0.40.0; extra == 'vertex-claude'
+Provides-Extra: web-search
+Requires-Dist: ddgs>=7.0; extra == 'web-search'
+Description-Content-Type: text/markdown
+
+# monkeybot
+
+<div align="center">
+  <img src="docs/assets/logo.png" alt="monkeybot Logo" width="600" />
+
+  <br />
+
+  *Multi-cloud agent harness — GCP-first docs, portable runtime*
+
+  [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+</div>
+
+monkeybot is an owned agent runtime for tool-using LLMs: a FastAPI SSE gateway, pluggable storage, MCP tools, skills, and memory. Run locally with zero cloud dependencies, or ship the same container image anywhere Docker runs.
+
+Docs and examples are **GCP-first** (Vertex, GCS, Cloud Run); AWS paths ship in the Pattern guides. See [Cloud deployment — Positioning](docs/cloud-deployment-design.md#positioning).
+
+> [!NOTE]
+> Skills under `SKILLS_PATH` execute Python code — only add skills from trusted sources.
+
+## Quick start
+
+Install [uv](https://docs.astral.sh/uv/), then:
+
+```bash
+uv tool install monkeybot-cli
+
+monkeybot new --dest ./my-agent --provider openai --yes
+cd my-agent
+uv sync
+cp .env.example .env   # add provider keys
+monkeybot doctor
+monkeybot chat
+```
+
+Upgrade the CLI with `uv tool upgrade monkeybot-cli`. Full walkthrough: **[Getting Started](docs/getting-started.md)**.
+
+## What you get
+
+- **SSE gateway** — sessions, streaming, health; wire your own UI or use the CLI
+- **Realtime talk** — WebSocket voice/text via `monkeybot talk`
+- **MCP + skills** — stdio/HTTP tools and trusted Python skill bundles
+- **Pluggable storage** — SQLite by default; Postgres, Firestore, GCS, S3
+- **Multi-provider** — Gemini/Vertex, OpenAI, Anthropic, Bedrock, Ollama, and more
+
+## CLI
+
+| Command | Purpose |
+|---|---|
+| `monkeybot new` | Scaffold config, workspace, agent `pyproject.toml`, `.env.example` |
+| `monkeybot validate` | Check `monkeybot.yaml`, paths, and MCP config |
+| `monkeybot doctor` | Verify Python, extras, credentials, and port |
+| `monkeybot run` | Start the SSE gateway in the foreground |
+| `monkeybot chat` | Talk over SSE (spawns the gateway; `--attach` to join one) |
+| `monkeybot talk` | Realtime voice/text over WebSocket (`--text` for typed input) |
+
+```bash
+monkeybot chat            # spawn gateway + REPL
+monkeybot run             # terminal 1: gateway with logs
+monkeybot chat --attach   # terminal 2: attach to it
+```
+
+Provider extras live on the **agent** `pyproject.toml` (`monkeybot[<provider>]`), not the global CLI. See [Getting Started](docs/getting-started.md) and [Features — CLI](docs/features.md#16-cli).
+
+## Agent skill
+
+```bash
+npx skills add human-plus-machine/monkeybot --skill monkeybot
+```
+
+Walks through install, scaffold, config, and first chat. Source: [`cli/skills/monkeybot/`](cli/skills/monkeybot/).
+
+## Documentation
+
+| Guide | Description |
+|---|---|
+| [Getting Started](docs/getting-started.md) | Install, configure, sessions + SSE from the CLI |
+| [Features](docs/features.md) | Architecture, capabilities, CLI, task queue |
+| [SSE gateway and custom UI](docs/sse-gateway-ui.md) | HTTP + SSE endpoints, event types, CORS |
+| [Skills](docs/skills.md) | Skill directory layout and `SKILL.md` discovery |
+| [Model Context Protocol](docs/mcp.md) | MCP config, env interpolation, OAuth2 |
+| [Cloud deployment](docs/cloud-deployment-design.md) | Positioning + Patterns A–D index |
+| [Live evals](docs/live-evals.md) | Smoke suite, local + CI scorecard |
+| [Observability](docs/observability-runbook.md) | OpenTelemetry tracing runbook |
+
+Integrations matrix and roadmap: [CHANGELOG](CHANGELOG.md) · [BACKLOG](BACKLOG.md).
+
+## Contributing
+
+Clone only if you are changing the harness. Setup, checks, and the release workflow are in **[CONTRIBUTING.md](CONTRIBUTING.md)**. Live eval smoke fixture: [`evals/smoke_agent/`](evals/smoke_agent/).
+
+## Support
+
+Search or open an issue in the [GitHub issue tracker](https://github.com/human-plus-machine/monkeybot/issues).
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).