cubeloop 0.14.0__tar.gz

cubeloop-0.14.0/.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

cubeloop-0.14.0/.github/workflows/SECRETS.md

@@ -0,0 +1,13 @@
+# Required GitHub Actions secrets
+
+Before merging this PR, configure these repository secrets at
+`Settings → Secrets and variables → Actions`:
+
+| Secret           | Required for                  | Source                                                              |
+|------------------|-------------------------------|---------------------------------------------------------------------|
+| `CF_API_TOKEN`   | Cloudflare Pages deploy       | Cloudflare dashboard → My Profile → API Tokens → "Cloudflare Pages: Edit" |
+| `CF_ACCOUNT_ID`  | Cloudflare Pages deploy       | Cloudflare dashboard → Workers & Pages → account ID                  |
+| `POSTHOG_KEY`    | Build-time injection of PostHog client key | PostHog dashboard → Project settings → Project API key |
+| `POSTHOG_HOST`   | (optional) PostHog endpoint   | Defaults to `https://us.i.posthog.com` if not set                    |
+
+Also create a Cloudflare Pages project named `cubepi` in "Direct upload" mode before the first deploy.

cubeloop-0.14.0/.github/workflows/ci.yml

@@ -0,0 +1,97 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    continue-on-error: ${{ matrix.python-version == '3.14' }}
+
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: postgres
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+      mysql:
+        image: mysql:8.0
+        env:
+          MYSQL_ROOT_PASSWORD: root
+          MYSQL_DATABASE: mysql
+        ports:
+          - 3306:3306
+        options: >-
+          --health-cmd "mysqladmin ping -h 127.0.0.1 -uroot -proot"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 20
+
+    env:
+      CUBELOOP_TEST_PG_DSN: postgresql://postgres:postgres@localhost:5432/postgres
+      CUBELOOP_TEST_MYSQL_DSN: mysql://root:root@localhost:3306/mysql
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Run tests
+        run: uv run pytest tests/ -v --cov=cubeloop --cov-report=term-missing --cov-report=xml
+
+      - name: Upload coverage to Codecov
+        if: matrix.python-version == '3.13'
+        uses: codecov/codecov-action@v7
+        with:
+          files: coverage.xml
+          token: ${{ secrets.CODECOV_TOKEN }}
+          fail_ci_if_error: false
+
+      - name: Check import
+        run: uv run python -c "import cubeloop; print(cubeloop.__all__)"
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Ruff check
+        run: uv run ruff check cubeloop/ tests/
+
+      - name: Ruff format check
+        run: uv run ruff format --check cubeloop/ tests/
+
+      - name: Mypy
+        run: uv run mypy cubeloop

cubeloop-0.14.0/.github/workflows/docs.yml

@@ -0,0 +1,87 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'website/**'
+      - 'cubeloop/**'
+      - 'pyproject.toml'
+      - 'README.md'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    paths:
+      - 'website/**'
+      - 'cubeloop/**'
+      - 'pyproject.toml'
+      - 'README.md'
+      - '.github/workflows/docs.yml'
+
+permissions:
+  contents: read
+  deployments: write
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-and-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: pnpm/action-setup@v6
+        with: { version: 10 }
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: 'pnpm'
+          cache-dependency-path: website/pnpm-lock.yaml
+      - uses: astral-sh/setup-uv@v7
+        with: { python-version: '3.11' }
+      - name: Install Python deps
+        run: uv sync --frozen --extra docs
+      - name: Install website deps
+        working-directory: website
+        run: pnpm install --frozen-lockfile
+      - name: Guard against hand-edited API mdx
+        run: |
+          if find website/docs/api -type f -name 'cubeloop-*.mdx' 2>/dev/null | grep .; then
+            echo "::error::Generated API MDX files were committed. Delete them." && exit 1
+          fi
+      - name: Build (runs griffe via prebuild)
+        working-directory: website
+        env:
+          POSTHOG_KEY: ${{ secrets.POSTHOG_KEY }}
+          POSTHOG_HOST: ${{ secrets.POSTHOG_HOST }}
+        run: pnpm build
+      - name: Run vitest suite
+        working-directory: website
+        run: pnpm test
+      - name: Upload artefact
+        if: github.ref == 'refs/heads/main'
+        uses: actions/upload-artifact@v7
+        with:
+          name: website-build
+          path: website/build/
+          if-no-files-found: error
+
+  deploy-cloudflare:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: build-and-check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/download-artifact@v8
+        with:
+          name: website-build
+          path: website/build/
+      - name: Deploy to Cloudflare Pages
+        uses: cloudflare/pages-action@v1
+        with:
+          apiToken: ${{ secrets.CF_API_TOKEN }}
+          accountId: ${{ secrets.CF_ACCOUNT_ID }}
+          projectName: cubepi
+          directory: website/build
+          gitHubToken: ${{ secrets.GITHUB_TOKEN }}
+          branch: main

cubeloop-0.14.0/.github/workflows/publish.yml

@@ -0,0 +1,63 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+
+      - name: Build packages
+        run: |
+          uv build
+          uv build --package cubepi
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          skip-existing: true
+
+  publish-pypi:
+    needs: publish-testpypi
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

cubeloop-0.14.0/.gitignore

@@ -0,0 +1,43 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+
+# Virtual environments
+.venv/
+
+# Testing / coverage
+.coverage
+.pytest_cache/
+htmlcov/
+
+# IDE
+.idea/
+.vscode/
+.claude/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Docusaurus
+website/.docusaurus/
+website/build/
+website/node_modules/
+website/package-lock.json
+website/docs/api/*.mdx
+!website/docs/api/index.mdx
+
+# Playwright CLI session artifacts
+.playwright-cli/
+
+# Marketing drafts (local only)
+dev/marketing/
+
+
+.worktrees/

cubeloop-0.14.0/.pre-commit-config.yaml

@@ -0,0 +1,23 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff check
+        entry: uv run ruff check cubeloop/ tests/
+        language: system
+        pass_filenames: false
+      - id: ruff-format-check
+        name: ruff format --check
+        entry: uv run ruff format --check cubeloop/ tests/
+        language: system
+        pass_filenames: false
+      - id: mypy
+        name: mypy cubeloop
+        entry: uv run mypy cubeloop
+        language: system
+        pass_filenames: false
+      - id: pytest
+        name: pytest tests
+        entry: uv run pytest tests/
+        language: system
+        pass_filenames: false

cubeloop-0.14.0/.python-version

@@ -0,0 +1 @@
+3.13

cubeloop-0.14.0/AGENTS.md

@@ -0,0 +1,101 @@
+# cubeloop
+
+Pythonic async-native agent framework (an alternative to langgraph). Async-first,
+strongly typed, deliberately few dependencies. 
+
+## Commands (always via `uv`)
+
+```bash
+uv sync --all-extras --dev               # install everything
+uv run pytest tests/                      # run tests (asyncio_mode=auto)
+uv run pytest tests/path/test.py::test -v # single test
+uv run ruff check cubeloop/ tests/
+uv run ruff format --check cubeloop/ tests/ # CI checks formatting, doesn't fix
+uv run mypy cubeloop
+```
+
+CI runs pytest + ruff + mypy. Tests run on Python 3.11–3.14 (3.14 is
+`continue-on-error`); local default is 3.13 (`.python-version`).
+
+## Architecture
+
+`cubeloop/` modules: `providers/` (LLM abstraction — `Provider` protocol returning
+`MessageStream`; anthropic / openai / openai_responses / faux), `agent/`
+(`agent.py` stateful class, `loop.py` stateless core algorithm, `tools.py`
+execution engine), `middleware/`, `checkpointer/` (memory / sqlite / postgres),
+`mcp/`, `tracing/` (OTel, optional), `cli/` (`cubeloop trace`). See the README
+"Architecture" section for the full annotated tree.
+
+## Conventions & gotchas
+
+- **Lean deps**: core deps are anthropic, openai, pydantic only.
+  Everything else (sqlite, postgres, mcp, tracing, trace-cli) is an optional
+  extra in `pyproject.toml`. Don't add a hard dependency without strong reason.
+- **`cubeloop.tracing` is lazily importable** (PEP 562 `__getattr__`): schema
+  constants import without the opentelemetry SDK, so the trace CLI works on a
+  `cubeloop[trace-cli]`-only install. Don't add eager OTel imports to its
+  `__init__.py`.
+- **Tests use `FauxProvider`** for deterministic, no-API-call runs with realistic
+  streaming. Prefer it over mocking providers.
+- **`cubeloop/cli/**` is excluded from codecov** (`codecov.yml` ignore).
+- Packaged data: `cubeloop/providers/catalog/data/*.yaml` ships in the wheel.
+
+## Development workflow
+
+This project follows a deliberate spec → plan → code pipeline. Honor it for any
+non-trivial work.
+
+**1. Set up an isolated worktree first.** When a new requirement comes in, before
+doing any work create a **date-prefixed worktree on a date-prefixed branch**
+(e.g. `.worktrees/YYYY-MM-DD-<topic>` on branch `YYYY-MM-DD-<topic>`). Never work
+directly on `main`. Subagents that write code must also use `isolation:
+"worktree"`.
+
+**2. Spec — collaborate, don't go autonomous.** The spec stage is interactive:
+talk through and confirm requirements with the user before writing the spec.
+While forming it, research prior art — **pi-agent-core, langgraph, claude code** —
+to find best practices, but let our own requirements and design philosophy drive
+the result. Call out notable divergences ("library does X, cubeloop does Y because
+Z") so they can be reviewed. Specs go in `dev/specs/` (dated
+`YYYY-MM-DD-<topic>.md`), plans in `dev/plans/`.
+
+Codex reviews happen in **two distinct phases** — local (step 3) and on the PR
+(step 5).
+
+**3. Local codex review loop — ask before entering it.** Once spec/plan/code are
+ready, **check with the user before starting the local codex review loop.** If
+they say go: run it autonomously without stopping to ask mid-flow — write the spec
+→ codex review; write the plan → codex review; write the code → codex review and
+iterate until codex is OK. Use the `codex:rescue` subagent for these reviews.
+
+**4. Document the feature, then open the PR.** Every completed feature **must**
+ship with its user-facing docs — add or update the relevant page under
+`website/docs/` (e.g. `guides/`, `getting-started/`, `recipes/`) in the same PR.
+A feature without docs is not done. Then open a PR from the worktree branch
+(never commit to `main` directly — it's a protected branch).
+
+**5. PR codex review loop.** Opening the PR triggers an automatic codex review.
+After that it is **not** automatic — drive it manually:
+
+- Poll for feedback every **~2 minutes** (check the PR's review comments).
+- Resolve every piece of feedback, pushing fixes to the branch.
+- Once resolved, **reply `@codex` on the PR to request another review pass.**
+- Repeat poll → fix → `@codex` until codex reports no remaining issues.
+
+Merge only after the PR codex review is clean and CI passes.
+
+## Releasing
+
+When shipping a new release `X.Y`, the docs site needs a frozen snapshot
+under `website/versioned_docs/version-X.Y/` (and the zh-Hans mirror) so
+later edits on `main` don't rewrite history for the released version. The
+order of operations is non-obvious — `pnpm apiref` must run before
+`pnpm docusaurus docs:version X.Y` or the API mdx is missing from the
+snapshot, the `current/` and `version-X.Y/` trees must be byte-identical
+at cut time, the previous latest needs `noIndex: true` and a
+`sitemap.ignorePatterns` entry, and a handful of other traps the 0.5 → 0.7
+cuts surfaced.
+
+See [`dev/runbooks/cut-doc-version.md`](dev/runbooks/cut-doc-version.md) for
+the full checklist, command order, and gotchas. Run that runbook **before**
+tagging the release.