muninn-py 0.1.0__tar.gz

muninn_py-0.1.0/.claude/commands/whats-next.md

@@ -0,0 +1,45 @@
+---
+description: Audit the current project state and surface what's next, what's missing, and what's at risk.
+---
+
+Audit this project's current state and tell me three things, in this order:
+
+1. **What's next.** The next 3 actionable items, ranked by leverage. For each, name the file or component it touches and the single thing that would close it.
+2. **What's missing.** Anything tracked as deferred, partial, scaffolded, or TODO that should be revisited. Cross-reference these against the ROADMAP and any `🟡` markers.
+3. **What's at risk.** Items likely to silently rot — stale docs that contradict the code, untested code paths, ADRs the codebase has drifted from, dependencies overdue for a bump, exit criteria not yet verified by a test.
+
+## How to gather the picture
+
+Read, in order:
+
+- `docs/steering/ROADMAP.md` if present, otherwise `docs/ROADMAP.md`.
+- The most recent `## [Unreleased]` block of `CHANGELOG.md`.
+- The last 5 commits — `git log --oneline -5`.
+- Anything in `TaskList` that's still `pending` or `in_progress`.
+- `git status --short` for uncommitted work.
+
+If this is a multi-repo session (e.g., both the server `muninn` and the SDK `muninn-py` are checked out), audit whichever working tree the current shell is in. Note the other one only if its state is directly load-bearing for an item.
+
+## How to report
+
+Keep the whole reply under ~250 words. Format:
+
+```
+## What's next
+1. <action> — <file or component> — <closing condition>
+2. ...
+3. ...
+
+## What's missing
+- <item> — <why it matters / what would close it>
+- ...
+
+## What's at risk
+- <item> — <how it might rot>
+- ...
+
+## Recommended next move
+<one sentence — usually pointing at the top "What's next" item>
+```
+
+Don't dispatch agents. Don't run the test suite. Don't write or modify files. This is an audit, not work. If you can't tell the state of something from the docs + git log alone, say so explicitly.

muninn_py-0.1.0/.claude/hooks/whats-next.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# Stop hook — emits a one-line "next up" nudge after every Claude response.
+#
+# Reads ROADMAP.md (project conventions: docs/steering/ROADMAP.md or docs/ROADMAP.md),
+# counts phase markers, and surfaces the next un-done phase. Silent when no roadmap
+# is present so this hook is harmless in other repos that share the same global config.
+#
+# Designed to run in well under a second; no network, no Claude, just shell + grep.
+
+set -euo pipefail
+
+# Resolve repo root from $CLAUDE_PROJECT_DIR (set by Claude Code), or fall back to pwd.
+ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+
+# Locate a roadmap file. First match wins.
+ROADMAP=""
+for candidate in \
+    "$ROOT/docs/steering/ROADMAP.md" \
+    "$ROOT/docs/ROADMAP.md" \
+    "$ROOT/ROADMAP.md"
+do
+    if [ -f "$candidate" ]; then
+        ROADMAP="$candidate"
+        break
+    fi
+done
+
+# No roadmap — exit silently so the hook is invisible in unrelated repos.
+[ -z "$ROADMAP" ] && exit 0
+
+# Count phases by completion marker.
+# A phase is "done" when its heading carries ✅ (complete), 🟢 (mostly complete),
+# or _(Merged…)_ (rolled into another phase).
+DONE_PATTERN='^## Phase .*(✅|🟢|_\(Merged)'
+DONE=$(grep -cE "$DONE_PATTERN" "$ROADMAP" 2>/dev/null || true)
+TOTAL=$(grep -cE '^## Phase ' "$ROADMAP" 2>/dev/null || true)
+
+# Default counts to 0 if grep returned nothing.
+DONE="${DONE:-0}"
+TOTAL="${TOTAL:-0}"
+
+# First "## Phase ..." line that isn't marked done. Strip the prefix + trailing
+# section emoji/marker for a compact display.
+NEXT_PHASE=$(
+    grep -E '^## Phase ' "$ROADMAP" 2>/dev/null \
+        | grep -vE '✅|🟢|_\(Merged' \
+        | head -n 1 \
+        | sed -E 's/^## Phase //; s/ —.*$//; s/ \(.*$//; s/ 🟡.*$//'
+)
+
+# Open work — anything with a 🟡 (scaffolded / in-progress) marker, useful as a
+# soft heads-up.
+OPEN=$(grep -cE '^- 🟡' "$ROADMAP" 2>/dev/null || true)
+OPEN="${OPEN:-0}"
+
+if [ -z "$NEXT_PHASE" ] && [ "$TOTAL" -gt 0 ] && [ "$DONE" -eq "$TOTAL" ]; then
+    printf '→ Roadmap fully ✅ (%s/%s). Try /whats-next for follow-ups or post-Phase ideas.\n' \
+        "$DONE" "$TOTAL"
+elif [ -n "$NEXT_PHASE" ]; then
+    if [ "$OPEN" -gt 0 ]; then
+        printf '→ Next: Phase %s · %s/%s done · %s open item(s) tagged 🟡 · /whats-next for detail.\n' \
+            "$NEXT_PHASE" "$DONE" "$TOTAL" "$OPEN"
+    else
+        printf '→ Next: Phase %s · %s/%s done · /whats-next for detail.\n' \
+            "$NEXT_PHASE" "$DONE" "$TOTAL"
+    fi
+fi
+
+exit 0

muninn_py-0.1.0/.claude/settings.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://www.schemastore.org/claude-code-settings.json",
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/whats-next.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

muninn_py-0.1.0/.github/dependabot.yml

@@ -0,0 +1,40 @@
+version: 2
+
+# Dependabot configuration for muninn-py.
+# - Watches pip dependencies declared in pyproject.toml.
+# - Watches the GitHub Actions used by .github/workflows/*.
+# - Weekly cadence; small bumps grouped to reduce noise.
+
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 10
+    groups:
+      runtime:
+        applies-to: version-updates
+        patterns:
+          - "httpx"
+          - "polars"
+          - "pandas"
+          - "pydantic"
+      dev:
+        applies-to: version-updates
+        patterns:
+          - "pytest*"
+          - "respx"
+          - "ruff"
+          - "mypy"
+    labels:
+      - "dependencies"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    labels:
+      - "dependencies"
+      - "github-actions"

muninn_py-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,96 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: test (py${{ matrix.python }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python ${{ matrix.python }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Type-check
+        run: mypy src/muninn
+
+      - name: Tests
+        run: pytest -ra
+
+  benchmark:
+    name: benchmarks (py3.12)
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run benchmarks
+        # --benchmark-only: run only benchmark tests (skip regular tests)
+        # --benchmark-json: save results for artifact upload
+        # When .benchmarks/baseline.json exists (committed), --benchmark-compare
+        # enforces the 25% regression gate. Until a baseline is committed, this
+        # step runs in observation mode and saves the results as an artifact.
+        run: |
+          if [ -f .benchmarks/baseline.json ]; then
+            pytest tests/bench_client.py \
+              --benchmark-only \
+              --benchmark-compare=.benchmarks/baseline.json \
+              --benchmark-fail-max-delta-mean=0.25 \
+              --benchmark-json=benchmark-results.json \
+              -v
+          else
+            pytest tests/bench_client.py \
+              --benchmark-only \
+              --benchmark-json=benchmark-results.json \
+              -v
+            echo "No baseline found. To enable the regression gate, run:"
+            echo "  pytest tests/bench_client.py --benchmark-save=baseline --benchmark-only"
+            echo "then commit .benchmarks/baseline.json"
+          fi
+
+      - name: Upload benchmark results
+        uses: actions/upload-artifact@v7
+        if: always()
+        with:
+          name: benchmark-results-py3.12
+          path: benchmark-results.json
+          retention-days: 30

muninn_py-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,39 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "requirements-docs.txt"
+      - "src/muninn/**"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: requirements-docs.txt
+
+      - name: Install docs dependencies
+        run: pip install -r requirements-docs.txt
+
+      - name: Install muninn-py (for mkdocstrings introspection)
+        run: pip install -e .
+
+      - name: Deploy to GitHub Pages
+        run: mkdocs gh-deploy --force

muninn_py-0.1.0/.github/workflows/integration.yml

@@ -0,0 +1,173 @@
+name: Integration
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: integration-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  integration-tests:
+    name: integration tests (py3.12)
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Check out Muninn server
+        uses: actions/checkout@v6
+        with:
+          repository: lgreene03/muninn
+          path: muninn
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install SDK with test extras
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run integration tests
+        run: pytest -m integration -ra -v
+        env:
+          MUNINN_SERVER_DIR: ${{ github.workspace }}/muninn
+
+  notebook-execution:
+    name: notebook smoke test (py3.12)
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Check out Muninn server
+        uses: actions/checkout@v6
+        with:
+          repository: lgreene03/muninn
+          path: muninn-server
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install SDK with notebook extras
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[notebooks,dev]"
+          pip install nbconvert ipykernel
+
+      - name: Register Jupyter kernel
+        run: python -m ipykernel install --user --name muninn-py
+
+      - name: Build Muninn server image
+        working-directory: muninn-server
+        run: docker build -t muninn:ci .
+
+      - name: Start infrastructure
+        working-directory: muninn-server
+        run: docker compose up -d
+
+      - name: Wait for infrastructure health
+        working-directory: muninn-server
+        run: |
+          echo "Waiting for PostgreSQL..."
+          until docker compose exec -T postgres pg_isready -U muninn; do sleep 2; done
+          echo "Waiting for Redpanda..."
+          until docker compose exec -T redpanda rpk cluster health; do sleep 2; done
+          echo "Waiting for MinIO..."
+          until docker compose exec -T minio mc ready local; do sleep 2; done
+
+      - name: Start Muninn server
+        working-directory: muninn-server
+        run: |
+          docker run -d --name muninn-server \
+            --network "$(docker compose ps -q postgres | xargs docker inspect -f '{{range .NetworkSettings.Networks}}{{.NetworkID}}{{end}}' | head -1)" \
+            -e SPRING_DATASOURCE_URL=jdbc:postgresql://postgres:5432/muninn \
+            -e SPRING_DATASOURCE_USERNAME=muninn \
+            -e SPRING_DATASOURCE_PASSWORD=muninn \
+            -e SPRING_KAFKA_BOOTSTRAP_SERVERS=redpanda:9092 \
+            -e MUNINN_STORAGE_S3_ENDPOINT=http://minio:9000 \
+            -e MUNINN_STORAGE_S3_ACCESS_KEY=minioadmin \
+            -e MUNINN_STORAGE_S3_SECRET_KEY=minioadmin \
+            -e MUNINN_INGESTION_BINANCE_ENABLED=false \
+            -p 8080:8080 \
+            muninn:ci
+
+      - name: Wait for Muninn API
+        run: |
+          echo "Waiting for Muninn API..."
+          for i in $(seq 1 60); do
+            if curl -sf http://localhost:8080/actuator/health > /dev/null 2>&1; then
+              echo "Muninn API is up"
+              break
+            fi
+            if [ $i -eq 60 ]; then
+              echo "Muninn API failed to start"
+              docker logs muninn-server
+              exit 1
+            fi
+            sleep 3
+          done
+
+      - name: Seed synthetic data via smoke script
+        working-directory: muninn-server
+        run: |
+          if [ -f scripts/smoke.sh ]; then
+            bash scripts/smoke.sh || echo "Smoke script exited with $? (non-fatal for notebook test)"
+          else
+            echo "No smoke script found — notebooks may run with empty data"
+          fi
+
+      - name: Execute alpha backtest notebook
+        run: |
+          jupyter nbconvert \
+            --to notebook \
+            --execute \
+            --ExecutePreprocessor.timeout=120 \
+            --ExecutePreprocessor.kernel_name=muninn-py \
+            --output-dir=/tmp/notebook-output \
+            notebooks/alpha_backtest_demo.ipynb || {
+              echo "::warning::alpha_backtest_demo.ipynb failed — server may lack sufficient data"
+              exit 0
+            }
+
+      - name: Execute feature drift monitoring notebook
+        run: |
+          jupyter nbconvert \
+            --to notebook \
+            --execute \
+            --ExecutePreprocessor.timeout=120 \
+            --ExecutePreprocessor.kernel_name=muninn-py \
+            --output-dir=/tmp/notebook-output \
+            notebooks/feature_drift_monitoring.ipynb || {
+              echo "::warning::feature_drift_monitoring.ipynb failed — server may lack sufficient data"
+              exit 0
+            }
+
+      - name: Upload executed notebooks
+        uses: actions/upload-artifact@v7
+        if: always()
+        with:
+          name: executed-notebooks
+          path: /tmp/notebook-output/
+          retention-days: 14
+
+      - name: Cleanup
+        if: always()
+        working-directory: muninn-server
+        run: |
+          docker stop muninn-server || true
+          docker rm muninn-server || true
+          docker compose down -v || true

muninn_py-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,131 @@
+name: Release
+
+# Tagged release flow:
+#   1. Bump the version in pyproject.toml + src/muninn/_version.py + CHANGELOG.
+#   2. Commit, tag (vX.Y.Z), and push the tag.
+#   3. This workflow builds the sdist + wheel and publishes to PyPI via
+#      Trusted Publishing (OIDC) — no API tokens stored as secrets.
+#
+# One-time setup before the first publish:
+#   - Reserve the name `muninn-py` on PyPI (https://pypi.org/manage/account/publishing/).
+#   - Add a "Trusted publisher" pointing at this workflow:
+#       PyPI Project Name : muninn-py
+#       Owner             : lgreene03
+#       Repository name   : muninn-py
+#       Workflow name     : release.yml
+#       Environment name  : pypi
+#   - The pre-release run against TestPyPI uses the `testpypi` environment;
+#     register the equivalent trusted publisher at https://test.pypi.org.
+#
+# Manual dispatch is supported for republishing the latest build to TestPyPI
+# without cutting a new tag.
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Where to upload"
+        required: true
+        default: "testpypi"
+        type: choice
+        options:
+          - testpypi
+          - pypi
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: build distributions
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+
+      - name: Build sdist + wheel
+        run: python -m build
+
+      - name: Check artifact metadata
+        run: twine check dist/*
+
+      - name: Verify version matches tag (tag-triggered runs only)
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          tag_version="${GITHUB_REF_NAME#v}"
+          pkg_version=$(python -c "import tomllib; print(tomllib.loads(open('pyproject.toml','rb').read().decode())['project']['version'])")
+          if [ "$tag_version" != "$pkg_version" ]; then
+            echo "::error::Tag $GITHUB_REF_NAME does not match pyproject.toml version $pkg_version"
+            exit 1
+          fi
+          echo "Tag $GITHUB_REF_NAME matches pyproject.toml version $pkg_version"
+
+      - name: Upload built artifacts
+        uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+          retention-days: 14
+
+  publish-testpypi:
+    name: publish to TestPyPI
+    runs-on: ubuntu-latest
+    needs: build
+    if: |
+      github.event_name == 'workflow_dispatch' && inputs.target == 'testpypi'
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/project/muninn-py/
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        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:
+    name: publish to PyPI
+    runs-on: ubuntu-latest
+    needs: build
+    if: |
+      startsWith(github.ref, 'refs/tags/v')
+      || (github.event_name == 'workflow_dispatch' && inputs.target == 'pypi')
+    environment:
+      name: pypi
+      url: https://pypi.org/project/muninn-py/
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

muninn_py-0.1.0/.gitignore

@@ -0,0 +1,64 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Test / type / lint
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+
+# Jupyter
+.ipynb_checkpoints/
+*.ipynb-checkpoint
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# MkDocs
+site/
+
+# Benchmarks
+.benchmarks/
+
+# Local data
+data/
+*.parquet
+*.feather
+.env
+.env.local