musubi-client 0.2.0__tar.gz

musubi_client-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,76 @@
+name: CI
+
+on:
+  push:
+    branches: [main, sdk-and-mcp-server]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+          # uv.lock is gitignored (this is a published library, not an app),
+          # so key the cache on pyproject.toml instead of the default
+          # **/uv.lock glob — which errors when no lockfile is checked in.
+          cache-dependency-glob: pyproject.toml
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install
+        run: |
+          uv venv --python ${{ matrix.python-version }}
+          uv pip install -e ".[dev]"
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Test
+        # Deselects one pre-existing concurrency-ordering flake in batch-label;
+        # tracked separately. All other tests must pass.
+        run: |
+          uv run pytest \
+            --deselect tests/test_bulk.py::TestBatchLabelFile::test_runs_gt_1_adds_variability_columns
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Build wheel
+        run: |
+          uv venv --python 3.12
+          uv pip install build
+          uv run python -m build --wheel
+
+      - name: Verify wheel contents
+        run: |
+          # Negative check: NO skills/ in the wheel.
+          if unzip -l dist/musubi_client-*.whl | grep -q "^.*skills/"; then
+            echo "ERROR: skills/ leaked into the wheel" >&2
+            exit 1
+          fi
+          # Positive check: data/hosts.json IS bundled.
+          if ! unzip -l dist/musubi_client-*.whl | grep -q "musubi/data/hosts.json"; then
+            echo "ERROR: musubi/data/hosts.json missing from wheel" >&2
+            exit 1
+          fi
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheel
+          path: dist/*.whl

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

@@ -0,0 +1,107 @@
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  publish-to-pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      # Specifying `permissions:` sets every UNLISTED scope to `none`, so we
+      # must grant `contents: read` explicitly — otherwise actions/checkout
+      # gets no repo access and fails with a misleading "Repository not found".
+      contents: read
+      # Required for PyPI trusted publishing (no API token in repo secrets).
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Build wheel + sdist
+        run: |
+          uv venv --python 3.12
+          uv pip install build
+          uv run python -m build
+
+      - name: Sanity-check wheel
+        run: |
+          # Match the CI checks — refuse to publish a wheel that leaked skills
+          # or is missing the bundled hosts.json fallback.
+          if unzip -l dist/musubi_client-*.whl | grep -q "^.*skills/"; then
+            echo "ERROR: skills/ leaked into the wheel" >&2
+            exit 1
+          fi
+          if ! unzip -l dist/musubi_client-*.whl | grep -q "musubi/data/hosts.json"; then
+            echo "ERROR: musubi/data/hosts.json missing from wheel" >&2
+            exit 1
+          fi
+
+      - name: Publish to PyPI (trusted publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  cross-repo-pr:
+    name: Sync install.sh + hosts.json into policy-ai-frontend
+    runs-on: ubuntu-latest
+    needs: publish-to-pypi
+    steps:
+      - name: Checkout musubi-client
+        uses: actions/checkout@v4
+        with:
+          path: musubi-client
+
+      - name: Checkout policy-ai-frontend
+        uses: actions/checkout@v4
+        with:
+          repository: musubi-labs/policy-ai-frontend
+          path: policy-ai-frontend
+          token: ${{ secrets.CROSS_REPO_PR_TOKEN }}
+
+      - name: Sync artifacts
+        run: |
+          set -eu
+          # Skills are NOT synced from here — they live natively in
+          # policy-ai-frontend/src/lib/skills (the frontend is the source of
+          # truth). musubi-client only owns install.sh and hosts.json.
+          # install.sh: copy single file.
+          cp musubi-client/scripts/install.sh policy-ai-frontend/static/install.sh
+          # hosts.json: copy single file.
+          mkdir -p policy-ai-frontend/static/cli
+          cp musubi-client/data/hosts.json policy-ai-frontend/static/cli/hosts.json
+
+      - name: Open PR
+        env:
+          # `gh` ships pre-installed on GitHub-hosted runners. It reads
+          # GH_TOKEN (or GITHUB_TOKEN) from env for auth — no `gh auth login`
+          # call needed in CI. We use a custom token (CROSS_REPO_PR_TOKEN)
+          # rather than the workflow's automatic GITHUB_TOKEN because the
+          # latter scopes to musubi-client only; we need write access to a
+          # different repo (policy-ai-frontend).
+          GH_TOKEN: ${{ secrets.CROSS_REPO_PR_TOKEN }}
+        run: |
+          set -eu
+          # Sanity: confirm `gh` is on PATH on this runner.
+          command -v gh >/dev/null 2>&1 || { echo "gh CLI not found" >&2; exit 1; }
+          cd policy-ai-frontend
+          BRANCH="musubi-client-sync-${GITHUB_REF_NAME}"
+          git config user.email "ci@musubilabs.ai"
+          git config user.name "musubi-client release bot"
+          git checkout -b "$BRANCH"
+          # `git diff --quiet` returns 0 when there are no changes — early exit
+          # so we don't open an empty PR (e.g. tagging a release that didn't
+          # touch skills / install.sh / hosts.json).
+          if git diff --quiet && git diff --cached --quiet; then
+            echo "No artifact changes to sync; skipping PR."
+            exit 0
+          fi
+          git add static/install.sh static/cli/hosts.json
+          git commit -m "Sync musubi-client artifacts (${GITHUB_REF_NAME})"
+          git push -u origin "$BRANCH"
+          gh pr create \
+            --title "Sync musubi-client artifacts (${GITHUB_REF_NAME})" \
+            --body "Auto-generated by musubi-client release ${GITHUB_REF_NAME}. Updates install.sh and hosts.json. (Skills live natively in the frontend's src/lib/skills.) Frontend deploy will serve them." \
+            --base main \
+            --head "$BRANCH"

musubi_client-0.2.0/.gitignore

@@ -0,0 +1,25 @@
+# Build artifacts
+/dist/
+/build/
+*.egg-info/
+__pycache__/
+*.pyc
+
+# Virtualenvs
+/.venv/
+/venv/
+
+# Editor / OS
+.DS_Store
+.idea/
+.vscode/
+
+# Test artifacts
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Codegen scratch
+/musubi-generated/
+uv.lock

musubi_client-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,152 @@
+# Contributing & Maintenance
+
+Development guide for working on the Musubi SDK and MCP server.
+
+## Initial setup
+
+From a checkout of this (`musubi-client`) repo:
+
+```bash
+uv venv .venv
+uv pip install -e ".[dev]" --python .venv/bin/python
+```
+
+`mcp` is a hard dependency (no separate extra); `.[dev]` adds the test/lint
+toolchain.
+
+## Running tests
+
+```bash
+# Unit tests (no API access needed, fast)
+.venv/bin/pytest tests/test_client.py -v
+
+# Integration tests (requires env vars, hits live API, creates/cleans up resources)
+.venv/bin/pytest tests/test_integration.py -v -s
+
+# All tests
+.venv/bin/pytest -v
+```
+
+Integration tests read `MUSUBI_API_KEY` / `MUSUBI_ORG_ID` from the environment
+and are skipped when unset.
+
+## Linting and formatting
+
+```bash
+# Check
+uv run --with ruff ruff check src/ tests/
+
+# Auto-fix and format
+uv run --with ruff ruff check --fix src/ tests/
+uv run --with ruff ruff format src/ tests/
+```
+
+Or via Makefile: `make lint`, `make format`, `make test`, `make install`.
+
+## Regenerating the generated client
+
+Do this when the PolicyAI API changes (new endpoints, changed models). The
+Makefile drives the whole pipeline (fetch/extract spec → fix spec → generate →
+copy into `src/musubi/_generated/`):
+
+```bash
+make generate                  # fetch the spec from a deployed URL
+make generate-from-monorepo    # extract the spec from a local policy-ai checkout
+make test                      # verify nothing broke
+```
+
+`make generate` chains `fetch-spec → fix-spec → generate-client →
+copy-generated`. The `-from-monorepo` variant swaps the first step for
+`extract-spec`, which boots the FastAPI app from an adjacent `policy-ai`
+checkout. See the `Makefile` for the exact commands and overridable variables.
+
+**What the fix script does:** Pydantic v2 generates separate Input/Output
+schema variants with dashes in the name (`FooModel-Input`). The generator
+chokes on these. The fix script renames them and updates titles to be unique.
+It also strips `application/yaml` content types that the generator doesn't
+support.
+
+## Smoke testing against the live API
+
+Quick sanity check that the SDK can talk to the API (reads `MUSUBI_API_KEY` /
+`MUSUBI_ORG_ID` from the environment):
+
+```bash
+.venv/bin/python scripts/smoke_test.py
+```
+
+This tests basic operations (list policies, list models, evaluate content) and
+reports pass/fail for each.
+
+## Testing the MCP server locally
+
+```bash
+.venv/bin/python -c "
+from musubi.mcp_server import mcp
+tools = mcp._tool_manager.list_tools()
+print(f'{len(tools)} tools loaded')
+for t in sorted(tools, key=lambda x: x.name):
+    print(f'  {t.name}')
+"
+```
+
+To test in read-only mode, add `MUSUBI_READ_ONLY=true` to the command.
+
+## Adding a new API endpoint to the SDK
+
+1. Regenerate the base client (see above) — the new endpoint will appear in
+   `_generated/`
+2. Add a method to the appropriate resource class in `src/musubi/resources/`
+   (both sync and async variants)
+3. Add a tool in `mcp_server.py` — use `@mcp.tool` for read-only,
+   `@_tool` for mutations (with `_require_writes` check)
+4. Add unit test(s) in `test_client.py`
+5. Add integration test(s) in `test_integration.py`
+6. Update the README if the new resource changes the public API surface
+
+## Adding a new v2 resource that replaces a v1 resource
+
+1. Add the v2 resource class
+2. Wire it into `MusubiClient` and `AsyncMusubiClient`
+3. Remove the old v1 resource class file
+4. Remove v1 imports and attributes from `client.py`
+5. Update the supersession map in `client.py`'s module docstring
+6. Remove v1 MCP tools and add v2 ones
+7. Update tests
+
+## OpenAPI spec extraction
+
+The SDK includes scripts to extract the OpenAPI spec from the FastAPI app:
+
+- `scripts/extract_openapi.py` — boots the app with `DOCS_VIEW=deployed` to
+  get the customer-facing spec (filtered endpoints, Musubi-Api-Key auth)
+- `scripts/fix_openapi_spec.py` — fixes two issues the generator can't handle:
+  1. Pydantic v2's `-Input`/`-Output` schema name suffixes cause duplicate
+     class names. The script renames them and updates titles.
+  2. `application/yaml` content type on v2 policy endpoints is stripped (the
+     generator only supports JSON).
+
+## Testing strategy
+
+**Unit tests** (`test_client.py`): Mock HTTP with `respx`. Test every resource,
+error handling, auth headers, envelope unwrapping. Fast (~0.1s). Run always.
+
+**Integration tests** (`test_integration.py`): Hit the live API. Create real
+resources, test every SDK method, clean up afterwards. Skipped when env vars
+aren't set. Cover the full CRUD lifecycle for each resource plus the complete
+v2 labeling flow (create policy → create version → create endpoint → label
+content).
+
+The MCP server itself is tested indirectly through the SDK — the tools are
+thin wrappers over SDK methods, so SDK test coverage implies MCP coverage.
+The server's tool registration and mode filtering are verified via the
+`_tool_manager.list_tools()` introspection in the smoke tests.
+
+## Key files to understand
+
+| File | Purpose |
+|------|---------|
+| `src/musubi/client.py` | Client classes + supersession policy doc |
+| `src/musubi/_base.py` | `_request` / `_request_data` (envelope unwrapping) |
+| `src/musubi/mcp_server.py` | All MCP tools, write gate, defaults |
+| `scripts/fix_openapi_spec.py` | OpenAPI spec preprocessing |

musubi_client-0.2.0/DESIGN.md

@@ -0,0 +1,198 @@
+# SDK & MCP Server Design Decisions
+
+This document explains the design choices behind the Musubi Python SDK and MCP
+server. Read this before making changes to understand why things are the way
+they are.
+
+## SDK Architecture
+
+### Hybrid generation approach
+
+The SDK uses `openapi-python-client` to generate a base HTTP client from the
+OpenAPI spec, then wraps it with a hand-written ergonomic layer. The generated
+code lives in `src/musubi/_generated/` and should never be edited manually.
+
+**Why not pure generated?** The generated client has several usability issues:
+- camelCase field names (from the API's JSON convention) instead of Pythonic snake_case
+- Envelope wrapping (`{"data": ..., "messages": [...]}`) not unwrapped
+- Auth requires manual header configuration
+- Uses `attrs` classes instead of plain dicts — unfamiliar to most users
+
+**Why not fully hand-written?** The API has 37 endpoints and 154 schemas. Hand-
+writing HTTP calls for all of them is error-prone and hard to keep in sync.
+
+**The hybrid approach** gives us the best of both: the generated layer handles
+all the HTTP/serialization plumbing, and the wrapper provides a clean public
+API. If the generator breaks or we outgrow it, we can swap it out — the wrapper
+layer stays the same.
+
+### Envelope unwrapping
+
+The PolicyAI API wraps every response in `{"data": ..., "messages": [...]}`.
+The SDK's `_base.py` has `_request_data()` which automatically extracts the
+`data` field. This means SDK users never see the envelope. The `messages` field
+(used for deprecation warnings etc.) is currently discarded — we can surface it
+later via logging if needed.
+
+One exception: `datasets.get_items()` returns `{"items": [...]}` inside the
+envelope, so it does an extra unwrap to return a flat list.
+
+### v2 only (with exceptions)
+
+The SDK only exposes v2 API surfaces. Superseded v1 endpoints are intentionally
+excluded to avoid confusing customers with two ways to do the same thing. The
+full supersession map is documented in `client.py`'s module docstring.
+
+Two v1 resources are kept because they have no v2 equivalent:
+- **Datasets** — test/evaluation dataset management
+- ~~Evaluations~~ — removed; operates on v1 policy UUIDs only
+
+When v2 equivalents ship for these, remove the v1 versions rather than
+maintaining both.
+
+### No Pydantic models in the public API
+
+The SDK returns plain dicts, not typed Pydantic models. This was deliberate:
+- The API uses camelCase and the response shapes vary between endpoints
+- Wrapping every response in a Pydantic model would mean maintaining ~50 model
+  classes that mirror the server's models
+- Dicts are simpler for LLM tool outputs (the primary consumer via MCP)
+- If customers need typed models, they can use the generated client directly
+  from `musubi._generated`
+
+### Sync + async
+
+Both `MusubiClient` (sync) and `AsyncMusubiClient` (async) are provided. They
+share the same resource classes — `SyncResource` and `AsyncResource` in
+`_base.py` have identical method signatures, just sync vs async. This avoids
+forcing customers into async when they don't need it.
+
+## MCP Server Design
+
+### One tool per SDK method
+
+Each SDK method maps to exactly one MCP tool. No multi-action tools with a
+"mode" parameter. This follows MCP best practices — granular tools compose
+better and LLMs make fewer mistakes when each tool does one thing.
+
+### Tool naming: `musubi_{resource}_{action}`
+
+All tools are prefixed with `musubi_` to avoid collisions with other MCP
+servers. The resource name comes next, then the action. This groups related
+tools together in alphabetical listings.
+
+### Write gate (two layers)
+
+**Problem:** LLMs can accidentally mutate production data. MCP doesn't have a
+native permissions system — it relies on the client (Claude Code) to prompt
+before tool calls. But users can configure auto-approve, bypassing that check.
+
+**Solution: two layers of protection.**
+
+1. **Soft gate (default):** All tools are registered, but mutation tools check
+   an in-memory `_writes_enabled` flag. It starts `False`. The LLM must call
+   `musubi_enable_writes` first, which Claude Code prompts the user to approve.
+   This is the confirmation step for normal usage.
+
+2. **Hard read-only (`MUSUBI_READ_ONLY=true`):** Mutation tools are not
+   registered at all — they don't exist in the server's tool schema. This is
+   for production orgs where you want zero risk regardless of client settings.
+   The `_tool()` decorator wrapper checks the flag and returns a no-op
+   decorator for non-read-only tools.
+
+The gate tools (`musubi_enable_writes`, `musubi_disable_writes`) are always
+registered via `@mcp.tool` (not `@_tool`) so they can explain the current
+state even in hard read-only mode.
+
+`musubi_server_info` is always read-only and shows the current mode.
+
+### Label operations are read-only
+
+Labeling (evaluate) calls are POST requests that create records in the API, but
+from the user's perspective they're read operations — "tell me how this content
+would be classified." They don't modify policies, endpoints, or datasets. So
+they're marked `readOnlyHint: True` and work without `musubi_enable_writes`,
+including in hard read-only mode.
+
+### Smart defaults for policy creation
+
+`musubi_create_policy_version` and `musubi_create_policy_draft` accept
+high-level parameters (`labels`, `policy_text`) and fill in sensible defaults:
+- Model: mango (id 104) with `reasoningEffort: "none"`
+- Output fields: `["analysis", "riskScore"]`
+- Prompt template: standard moderation system prompt with `{{ policy_text }}`
+- Content keys: `[{"type": "TEXT", "key": "content"}]`
+
+This means the LLM only needs to provide the two things that actually vary
+between policies (the labels and the policy text). The raw `policy_data` dict
+is still accepted for full control.
+
+`additionalOutputFields` is exposed as a first-class parameter instead of
+being buried inside `policy_data`. This avoids the common mistake of trying
+to use `outputFieldDefinitions` directly (which requires the full field schema
+instead of just preset names).
+
+### Batch labeling and consistency testing
+
+`musubi_batch_label` runs multiple items through a policy in parallel using
+`ThreadPoolExecutor`. Default parallelism is 15. Results are returned in input
+order with the index preserved. Each thread catches all exceptions so one
+failure doesn't crash the batch.
+
+`musubi_consistency_test` runs the same text N times (default 3) and adds a
+summary with label counts and agreement rate. Returns all individual results
+plus the summary — the LLM can analyze the raw results if the summary isn't
+enough.
+
+Both tools share `_run_parallel_labels()` and `_label_one()` to avoid code
+duplication.
+
+### Error handling
+
+API errors are caught and returned as JSON `{"error": "..."}` strings rather
+than raising exceptions. MCP tools must return text — uncaught exceptions would
+crash the server process.
+
+The 409 archive conflict error gets special treatment: when you try to archive
+a policy that's referenced by endpoints, the error includes a `hint` field
+explaining the workaround (repoint or archive the endpoints first, with the
+specific tool names to use).
+
+## File Layout
+
+```
+musubi-client/
+├── pyproject.toml              # Package config, deps, ruff/pytest config
+├── Makefile                    # generate, test, lint, format, clean
+├── README.md                   # Installation and usage reference
+├── GETTING_STARTED.md          # Onboarding guide
+├── DESIGN.md                   # This file
+├── CONTRIBUTING.md             # Development, testing, and maintenance guide
+├── generator-config.yaml       # openapi-python-client config
+├── scripts/
+│   ├── extract_openapi.py      # Extract spec from FastAPI app
+│   ├── fix_openapi_spec.py     # Fix spec issues for generator
+│   └── smoke_test.py           # Quick live API smoke test
+│   # NOTE: no skills/ here — skills live in policy-ai-frontend/src/lib/skills
+│   # (source of truth), served via /cli/skills. `install-skills --from-dir`
+│   # installs from a local folder for testing.
+├── src/musubi/
+│   ├── __init__.py             # Public exports
+│   ├── client.py               # MusubiClient / AsyncMusubiClient + service wiring
+│   ├── _base.py                # SyncResource / AsyncResource (envelope unwrap)
+│   ├── _cli_shared.py          # Leaf CLI helpers (parse_kv_pairs, short_id)
+│   ├── exceptions.py           # Typed exception hierarchy
+│   ├── cli.py                  # Click CLI root
+│   ├── commands/               # CLI subcommands (login, dataset, doctor, ...)
+│   ├── mcp_server.py           # MCP server (35 tools)
+│   ├── mcp_hosts.py            # MCP host catalog + register/unregister
+│   ├── datasets_workflow.py    # Path A / Path B dataset workflows
+│   ├── bulk.py / labeling.py / policy_diff.py / policy_helpers.py / prompts.py
+│   ├── auth/                   # config (creds/deployment), iam, device_flow
+│   ├── _generated/             # Auto-generated PolicyAI client (do not edit)
+│   └── resources/              # Per-service SDK surface
+│       ├── policyai/           # labels, endpoints, policies, models
+│       ├── iam/                # users, organizations
+│       └── datasets/           # dataset (schema-first columnar service)
+└── tests/                      # Unit + integration (live API) tests
+```