minima-cli 0.4.9__tar.gz

minima_cli-0.4.9/.claude/settings.local.json

@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(gcloud sql instances describe *)",
+      "Bash(gcloud redis *)",
+      "Bash(gcloud run services describe *)",
+      "Bash(curl -s -H 'Authorization: Bearer GkqgKc3c0eFMK1LwgNhXV60GuXNJYXE1gDulAIyuWOuerymE' https://minima-staging-ftvjoyasma-ez.a.run.app/v1/health)",
+      "Bash(python3 -m json.tool)",
+      "Bash(curl -s -H 'Authorization: Bearer mbt_shankha-dev_cavgtceg2cyxzzkb_Omvp2p4l3bGxhoxzYBDoCYYyzylKM8hmyYzarJuzfduf1NdlDBL5pXgR86IodpGz' https://minima-staging-ftvjoyasma-ez.a.run.app/v1/health)"
+    ]
+  }
+}

minima_cli-0.4.9/.dockerignore

@@ -0,0 +1,36 @@
+# Version control
+.git/
+.github/
+
+# Python artifacts
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+*.egg-info/
+dist/
+build/
+
+# Dev tools
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+
+# Secrets — never in the image
+.env
+.env.*
+
+# Docs and examples (not needed at runtime)
+docs/
+docs-site/
+examples/
+
+# Tests
+tests/
+
+# Misc
+*.md
+!README.md
+uv.lock.bak

minima_cli-0.4.9/.env.example

@@ -0,0 +1,176 @@
+# --- Mubit memory backend ---
+# Auth is pass-through: callers present their own Mubit key as Authorization: Bearer.
+# MUBIT_API_KEY here is only the local/dev default (single-key mode); hosted Minima
+# never stores caller keys.
+# Leave MUBIT_ENDPOINT unset for the hosted default (https://api.mubit.ai). Uncomment and
+# point it at a LOCAL Mubit runtime ONLY for server development — a stray localhost value
+# copied into ./.env would silently degrade the `minima` CLI's memory to offline.
+# MUBIT_ENDPOINT=http://127.0.0.1:3000
+MUBIT_API_KEY=
+# http is the proven transport for the local runtime: recall uses mode=direct_bypass,
+# which the runtime's gRPC QueryMode enum does not accept (auto may pick gRPC and fail).
+# NOTE: recall (mode=direct_bypass) requires the org's instance to have
+# enable_direct_search=true (default false on hosted Mubit instances).
+MUBIT_TRANSPORT=http
+MUBIT_TIMEOUT_MS=30000
+
+# --- Memory read path ---
+# Recall includes a server-side embedding round-trip; latency is embedder-bound
+# (~100-300ms on a GPU embedder, ~1.5s on a local CPU one). Bounds recommendation latency.
+MINIMA_MEMORY_RECALL_TIMEOUT_MS=2500
+MINIMA_MEMORY_RECALL_LIMIT=25
+# agent_routed works on all Mubit instances including hosted api.mubit.ai.
+# direct_bypass is lower-latency but requires enable_direct_search=true on the instance
+# (default false on hosted Mubit; safe to use with a local Mubit runtime).
+MINIMA_RECALL_MODE=agent_routed
+MINIMA_LANE_PREFIX=minima
+MINIMA_SEED_LANE=minima:default
+# Server-side recall precision (all have legacy escape hatches: empty string = off).
+# Entry types covering both intake paths (seeds=fact, feedback=observation).
+MINIMA_RECALL_ENTRY_TYPES=fact,observation
+# relevance | freshness | balanced — balanced lets recency influence WHICH neighbors
+# arrive; per-neighbor age weighting is the client-side half-life decay below.
+MINIMA_RECALL_RANK_BY=balanced
+# Hard recency window in days (0 = no window).
+MINIMA_RECALL_MAX_AGE_DAYS=0
+# Mubit search budget tier: low | mid | high.
+MINIMA_RECALL_BUDGET=mid
+# Log per-evidence score breakdowns (diagnostic; keep off in prod).
+MINIMA_RECALL_EXPLAIN=false
+
+# --- Recommender tuning ---
+MINIMA_TAU_MIN=0.55
+MINIMA_TAU_MAX=0.92
+MINIMA_BETA_PSEUDOCOUNT=2.5
+MINIMA_ESCALATION_W_MIN=1.5
+MINIMA_ESCALATION_N_MIN=3
+MINIMA_ESCALATION_C_MIN=0.45
+MINIMA_ESCALATION_TIE_DELTA=0.05
+# legacy = four independent triggers; uncertainty = posterior-interval gate replaces
+# thin_evidence+low_confidence (conflict stays a hard override). Shadow before switching.
+MINIMA_ESCALATION_MODE=legacy
+MINIMA_ESCALATION_INTERVAL_WIDTH=0.25
+MINIMA_DEFAULT_INPUT_TOKENS=1500
+MINIMA_DEFAULT_OUTPUT_TOKENS=500
+MINIMA_REFLECT_EVERY_N=25
+# Rank candidates by what they REALLY cost, not a flat token estimate that ignores
+# reasoning/thinking tokens. With >=MIN_N observations per candidate the engine re-scales the
+# model's observed output behaviour to this request's input size (size-exact + reasoning-aware);
+# with cost-but-no-token history it uses the robust median realized $/call; otherwise it falls
+# back to the token estimate. One basis is chosen for the whole candidate set (no apples-to-oranges).
+MINIMA_USE_OBSERVED_COST=true
+MINIMA_OBSERVED_COST_MIN_N=3
+# Evidence age decay: a recalled outcome's weight halves every half-life (records
+# without a timestamp keep the legacy binary stale penalty). Floor bounds old evidence.
+MINIMA_EVIDENCE_HALF_LIFE_DAYS=30.0
+MINIMA_EVIDENCE_DECAY_FLOOR=0.1
+# Seeded outcomes count at SEED_WEIGHT, crowded out linearly once a model has
+# CROWDOUT_N live outcomes in the recalled set. 1.0/0 = legacy (seeds at full weight).
+MINIMA_SEED_WEIGHT=0.5
+MINIMA_SEED_CROWDOUT_N=5
+# Latency annotation/enforcement (Constraints.max_latency_ms): robust observed
+# percentile, only for candidates with >= MIN_N latency observations.
+MINIMA_LATENCY_PERCENTILE=0.75
+MINIMA_LATENCY_MIN_N=3
+# Default-output-token multipliers by classified difficulty (JSON dict), applied to
+# MINIMA_DEFAULT_OUTPUT_TOKENS when the caller omits expected_output_tokens.
+# Affects the "estimate" cost basis only.
+MINIMA_DIFFICULTY_OUTPUT_MULTIPLIERS={"trivial": 0.5, "easy": 0.75, "medium": 1.0, "hard": 1.5, "expert": 2.0}
+
+# --- Cheap-LLM reasoner (recommend-only); set provider=anthropic|gemini + the matching key ---
+# Requires the provider extra: `uv sync --extra reasoner-anthropic` and/or `--extra reasoner-gemini`.
+MINIMA_REASONER_PROVIDER=none
+MINIMA_REASONER_MODEL=
+MINIMA_REASONER_TIMEOUT_MS=15000
+# Output cap. Gemini 3.x reasons before emitting JSON; <4096 can truncate the response.
+MINIMA_REASONER_MAX_TOKENS=4096
+MINIMA_REASONER_BLEND=0.5
+# Adaptive blend: weight the LLM's estimate by how thin the deterministic evidence is
+# (cold candidates lean on the LLM; well-evidenced ones barely move). false = fixed blend.
+MINIMA_REASONER_BLEND_ADAPTIVE=true
+MINIMA_REASONER_BLEND_MAX=0.8
+MINIMA_REASONER_CLASSIFY=true
+ANTHROPIC_API_KEY=
+GEMINI_API_KEY=
+
+# --- Selection-bias correction (inverse propensity weighting) ---
+MINIMA_IPW_ENABLED=true
+MINIMA_IPW_CLIP_LOW=0.1
+MINIMA_IPW_CLIP_HIGH=10.0
+
+# --- Learning maturity (Phase 3) ---
+# Cluster granularity for the per-(cluster, model) upsert key. coarse = task_type:difficulty;
+# fine appends a salient-keyword signature so distinct topics accumulate separately.
+MINIMA_CLUSTER_GRANULARITY=coarse
+MINIMA_CLUSTER_SIGNATURE_TOKENS=4
+# Promote a verified-in-production strong success to a durable Lesson (feeds reflect()).
+MINIMA_LESSON_ON_VERIFIED_PROD=true
+MINIMA_LESSON_MIN_QUALITY=0.8
+# Optimistic bonus for under-explored candidates (0.0 = off; pure exploitation).
+MINIMA_EXPLORATION_BONUS=0.0
+
+# --- Catalog ---
+MINIMA_CATALOG_REFRESH_SECONDS=21600
+MINIMA_CATALOG_STALE_AFTER_SECONDS=86400
+MINIMA_LITELLM_PRICES_URL=https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json
+MINIMA_OPENROUTER_MODELS_URL=https://openrouter.ai/api/v1/models
+OPENROUTER_API_KEY=
+
+# --- Service ---
+MINIMA_HOST=0.0.0.0
+# NOTE: a local Mubit embedding server commonly runs on :8080; pick another port for Minima.
+MINIMA_PORT=8088
+MINIMA_LOG_LEVEL=info
+# memory | sqlite | cloudsql — controls DecisionLog, Propensity, and RecStore + DurableRefs
+# unless MINIMA_RECSTORE_BACKEND overrides the operational stores.
+#   memory   — in-process; lost on restart. Fine for local dev.
+#   sqlite   — SQLite on MINIMA_SQLITE_PATH. NOTE: /tmp is ephemeral on Cloud Run.
+#   cloudsql — PostgreSQL via Cloud SQL Auth Proxy (requires MINIMA_DATABASE_URL).
+MINIMA_RECOMMENDATION_STORE=memory
+# 7 days: feedback often arrives late (batch evals, prod verification). After expiry the
+# late-feedback path still accepts outcomes (without neighbor attribution).
+MINIMA_RECOMMENDATION_TTL_SECONDS=604800
+MINIMA_SQLITE_PATH=minima_state.db
+MINIMA_LATE_FEEDBACK_ENABLED=true
+
+# --- Persistent store backends (Cloud SQL + Redis) ---
+# PostgreSQL DSN — required when MINIMA_RECOMMENDATION_STORE=cloudsql.
+# Cloud Run (Auth Proxy socket): postgresql://app_user:PASSWORD@/minima?host=/cloudsql/PROJECT:REGION:INSTANCE
+# Local (TCP):                   postgresql://app_user:PASSWORD@localhost:5432/minima
+MINIMA_DATABASE_URL=
+# Redis URL — required when MINIMA_RECSTORE_BACKEND=redis (Cloud Memorystore private IP).
+MINIMA_REDIS_URL=redis://localhost:6379/0
+# Override backend for RecStore + DurableRefs independently of MINIMA_RECOMMENDATION_STORE.
+#   redis    — Redis/Memorystore (TTL-native, low-latency); requires MINIMA_REDIS_URL
+#   cloudsql — PostgreSQL (same DB as DecisionLog/Propensity)
+#   empty    — inherit from MINIMA_RECOMMENDATION_STORE (default)
+MINIMA_RECSTORE_BACKEND=
+
+# --- Decision logging & off-policy evaluation ---
+# Every recommendation is logged (candidate set, propensity vector, tau, cost baselines)
+# and reconciled at feedback. Powers GET /v1/savings, GET /v1/calibration, feedback
+# coverage, and the minima-calibration-report script.
+MINIMA_DECISION_LOG_RETENTION_DAYS=90
+# Comma-separated org ids opted into epsilon-stochastic selection (sampling within the
+# tau-eligible set). Empty = deterministic argmin everywhere (default).
+MINIMA_EPSILON_SELECTION_ORGS=
+MINIMA_EPSILON=0.03
+MINIMA_EPSILON_SOFTMAX_TEMPERATURE=0.1
+
+# --- Calibration monitoring ---
+MINIMA_CALIBRATION_WINDOW_DAYS=30
+MINIMA_CALIBRATION_SHRINKAGE_K=20.0
+MINIMA_CALIBRATION_BINS=10
+# CUSUM drift detection, sized for binary residuals (smaller values flag healthy streams).
+MINIMA_CUSUM_K=0.25
+MINIMA_CUSUM_H=2.0
+
+# --- Durable-record fast path ---
+# off | shadow (fetch + log what ANN missed, don't merge) | on (merge into evidence).
+MINIMA_DURABLE_FASTPATH=off
+MINIMA_DURABLE_FASTPATH_MAX_REFS=8
+
+# --- Tenancy ---
+# Auth is pass-through (the caller's Mubit key IS the credential; org id is derived from
+# it). This org id only partitions single-key/dev state (recstore/propensity/decisions).
+MINIMA_DEFAULT_ORG_ID=default

minima_cli-0.4.9/.github/workflows/prod.yml

@@ -0,0 +1,158 @@
+name: Deploy — Production
+
+on:
+  release:
+    types: [published]
+  # Manual re-deploy of any tag (e.g. when a tag predates a workflow fix, or to redeploy).
+  # Dispatch from the default branch so it uses the current workflow definition/runner.
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Git tag to build & deploy (e.g. v0.4.3)"
+        required: true
+        type: string
+
+concurrency:
+  group: deploy-minima-prod
+  cancel-in-progress: false
+
+env:
+  PROJECT:         mubit-prod
+  REGION:          europe-west4
+  REGISTRY:        europe-west4-docker.pkg.dev/mubit-prod/minima
+  SERVICE_NAME:    minima-prod
+  DOCS_SERVICE:    minima-docs-prod
+  RELEASE_TAG:     ${{ github.event.release.tag_name || inputs.tag }}
+  # Cloud SQL Auth Proxy — new dedicated Minima instance (not shared with console-db)
+  CLOUDSQL_INSTANCE: mubit-prod:europe-west4:minima-prod-db
+  # VPC for Cloud Memorystore (Redis) connectivity
+  NETWORK:         mubit-prod-eu-network
+  SUBNET:          mubit-prod-eu-subnet
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+
+  # ── 1. Minima service ───────────────────────────────────────────────────────
+  deploy-service:
+    name: Service → Cloud Run (prod)
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout @ release tag
+        uses: actions/checkout@v5
+        with:
+          ref: ${{ env.RELEASE_TAG }}
+
+      - name: Authenticate to GCP
+        uses: google-github-actions/auth@v2
+        with:
+          project_id: ${{ env.PROJECT }}
+          workload_identity_provider: ${{ secrets.GCP_PROD_WIF_PROVIDER }}
+          service_account: ${{ secrets.GCP_PROD_DEPLOYER_SA }}
+
+      - name: Configure Docker for Artifact Registry
+        run: gcloud auth configure-docker ${{ env.REGION }}-docker.pkg.dev --quiet
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build and push service image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./Dockerfile
+          push: true
+          tags: |
+            ${{ env.REGISTRY }}/minima-service:${{ env.RELEASE_TAG }}
+            ${{ env.REGISTRY }}/minima-service:latest
+          cache-from: type=gha,scope=minima-service-prod
+          cache-to: type=gha,mode=max,scope=minima-service-prod
+
+      - name: Deploy service to Cloud Run (prod)
+        run: |
+          gcloud run deploy ${{ env.SERVICE_NAME }} \
+            --image ${{ env.REGISTRY }}/minima-service:${{ env.RELEASE_TAG }} \
+            --region ${{ env.REGION }} \
+            --platform managed \
+            --port 8080 \
+            --cpu 2 \
+            --memory 2Gi \
+            --min-instances 1 \
+            --max-instances 20 \
+            --allow-unauthenticated \
+            --service-account ${{ secrets.GCP_PROD_DEPLOYER_SA }} \
+            --add-cloudsql-instances=${{ env.CLOUDSQL_INSTANCE }} \
+            --network=${{ env.NETWORK }} \
+            --subnet=${{ env.SUBNET }} \
+            --vpc-egress=private-ranges-only \
+            --set-env-vars="MUBIT_ENDPOINT=https://api.mubit.ai,MUBIT_TRANSPORT=http,MINIMA_RECALL_MODE=agent_routed,MINIMA_LOG_LEVEL=info,MINIMA_RECOMMENDATION_STORE=cloudsql,MINIMA_RECSTORE_BACKEND=redis,MINIMA_REASONER_PROVIDER=gemini,MINIMA_REASONER_MODEL=gemini-3.5-flash" \
+            --set-secrets="GEMINI_API_KEY=minima-prod-gemini-key:latest,ANTHROPIC_API_KEY=minima-prod-anthropic-key:latest,OPENROUTER_API_KEY=minima-prod-openrouter-key:latest,MINIMA_DATABASE_URL=minima-prod-db-url:latest,MINIMA_REDIS_URL=minima-prod-redis-url:latest" \
+            --quiet
+
+      - name: Print service URL
+        run: |
+          URL=$(gcloud run services describe ${{ env.SERVICE_NAME }} \
+            --region ${{ env.REGION }} \
+            --format 'value(status.url)')
+          echo "::notice::Minima service (prod) deployed to: $URL"
+
+  # ── 2. Docs site ────────────────────────────────────────────────────────────
+  deploy-docs:
+    name: Docs → Cloud Run (prod)
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout @ release tag
+        uses: actions/checkout@v5
+        with:
+          ref: ${{ env.RELEASE_TAG }}
+
+      - name: Authenticate to GCP
+        uses: google-github-actions/auth@v2
+        with:
+          project_id: ${{ env.PROJECT }}
+          workload_identity_provider: ${{ secrets.GCP_PROD_WIF_PROVIDER }}
+          service_account: ${{ secrets.GCP_PROD_DEPLOYER_SA }}
+
+      - name: Configure Docker for Artifact Registry
+        run: gcloud auth configure-docker ${{ env.REGION }}-docker.pkg.dev --quiet
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build and push docs image
+        uses: docker/build-push-action@v6
+        with:
+          context: ./docs-site
+          file: ./docs-site/Dockerfile
+          push: true
+          tags: |
+            ${{ env.REGISTRY }}/minima-docs:${{ env.RELEASE_TAG }}
+            ${{ env.REGISTRY }}/minima-docs:latest
+          cache-from: type=gha,scope=minima-docs-prod
+          cache-to: type=gha,mode=max,scope=minima-docs-prod
+
+      - name: Deploy docs to Cloud Run (prod)
+        run: |
+          gcloud run deploy ${{ env.DOCS_SERVICE }} \
+            --image ${{ env.REGISTRY }}/minima-docs:${{ env.RELEASE_TAG }} \
+            --region ${{ env.REGION }} \
+            --platform managed \
+            --port 8080 \
+            --cpu 1 \
+            --memory 256Mi \
+            --min-instances 1 \
+            --max-instances 5 \
+            --allow-unauthenticated \
+            --service-account ${{ secrets.GCP_PROD_DEPLOYER_SA }} \
+            --quiet
+
+      - name: Print docs URL
+        run: |
+          URL=$(gcloud run services describe ${{ env.DOCS_SERVICE }} \
+            --region ${{ env.REGION }} \
+            --format 'value(status.url)')
+          echo "::notice::Minima docs (prod) deployed to: $URL"

minima_cli-0.4.9/.github/workflows/staging.yml

@@ -0,0 +1,148 @@
+name: Deploy — Staging
+
+on:
+  push:
+    branches: [staging]
+  # Manual deploy of any branch/ref to staging (dispatch on the ref you want deployed).
+  workflow_dispatch:
+
+concurrency:
+  group: deploy-minima-staging
+  cancel-in-progress: true
+
+env:
+  PROJECT:         mubit-dev-489910
+  REGION:          europe-west4
+  REGISTRY:        europe-west4-docker.pkg.dev/mubit-dev-489910/minima
+  SERVICE_NAME:    minima-staging
+  DOCS_SERVICE:    minima-docs-staging
+  IMAGE_TAG:       staging-${{ github.sha }}
+  # Cloud SQL Auth Proxy — new dedicated Minima instance (not shared with console-db)
+  CLOUDSQL_INSTANCE: mubit-dev-489910:europe-west4:minima-staging-db
+  # VPC for Cloud Memorystore (Redis) connectivity
+  NETWORK:         mubit-dev-eu-network
+  SUBNET:          mubit-dev-eu-subnet
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+
+  # ── 1. Minima service ───────────────────────────────────────────────────────
+  deploy-service:
+    name: Service → Cloud Run (staging)
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Authenticate to GCP
+        uses: google-github-actions/auth@v2
+        with:
+          project_id: ${{ env.PROJECT }}
+          workload_identity_provider: ${{ secrets.GCP_WIF_PROVIDER }}
+          service_account: ${{ secrets.GCP_DEPLOYER_SA }}
+
+      - name: Configure Docker for Artifact Registry
+        run: gcloud auth configure-docker ${{ env.REGION }}-docker.pkg.dev --quiet
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build and push service image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./Dockerfile
+          push: true
+          tags: |
+            ${{ env.REGISTRY }}/minima-service:${{ env.IMAGE_TAG }}
+            ${{ env.REGISTRY }}/minima-service:staging-latest
+          cache-from: type=gha,scope=minima-service-staging
+          cache-to: type=gha,mode=max,scope=minima-service-staging
+
+      - name: Deploy service to Cloud Run (staging)
+        run: |
+          gcloud run deploy ${{ env.SERVICE_NAME }} \
+            --image ${{ env.REGISTRY }}/minima-service:${{ env.IMAGE_TAG }} \
+            --region ${{ env.REGION }} \
+            --platform managed \
+            --port 8080 \
+            --cpu 1 \
+            --memory 1Gi \
+            --min-instances 1 \
+            --max-instances 10 \
+            --allow-unauthenticated \
+            --service-account ${{ secrets.GCP_DEPLOYER_SA }} \
+            --add-cloudsql-instances=${{ env.CLOUDSQL_INSTANCE }} \
+            --network=${{ env.NETWORK }} \
+            --subnet=${{ env.SUBNET }} \
+            --vpc-egress=private-ranges-only \
+            --set-env-vars="MUBIT_ENDPOINT=https://api.mubit.ai,MUBIT_TRANSPORT=http,MINIMA_RECALL_MODE=agent_routed,MINIMA_LOG_LEVEL=info,MINIMA_RECOMMENDATION_STORE=cloudsql,MINIMA_RECSTORE_BACKEND=redis,MINIMA_REASONER_PROVIDER=gemini,MINIMA_REASONER_MODEL=gemini-3.5-flash" \
+            --set-secrets="GEMINI_API_KEY=minima-staging-gemini-key:latest,ANTHROPIC_API_KEY=minima-staging-anthropic-key:latest,OPENROUTER_API_KEY=minima-staging-openrouter-key:latest,MINIMA_DATABASE_URL=minima-staging-db-url:latest,MINIMA_REDIS_URL=minima-staging-redis-url:latest" \
+            --quiet
+
+      - name: Print service URL
+        run: |
+          URL=$(gcloud run services describe ${{ env.SERVICE_NAME }} \
+            --region ${{ env.REGION }} \
+            --format 'value(status.url)')
+          echo "::notice::Minima service (staging) deployed to: $URL"
+
+  # ── 2. Docs site ────────────────────────────────────────────────────────────
+  deploy-docs:
+    name: Docs → Cloud Run (staging)
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Authenticate to GCP
+        uses: google-github-actions/auth@v2
+        with:
+          project_id: ${{ env.PROJECT }}
+          workload_identity_provider: ${{ secrets.GCP_WIF_PROVIDER }}
+          service_account: ${{ secrets.GCP_DEPLOYER_SA }}
+
+      - name: Configure Docker for Artifact Registry
+        run: gcloud auth configure-docker ${{ env.REGION }}-docker.pkg.dev --quiet
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build and push docs image
+        uses: docker/build-push-action@v6
+        with:
+          context: ./docs-site
+          file: ./docs-site/Dockerfile
+          push: true
+          tags: |
+            ${{ env.REGISTRY }}/minima-docs:${{ env.IMAGE_TAG }}
+            ${{ env.REGISTRY }}/minima-docs:staging-latest
+          cache-from: type=gha,scope=minima-docs-staging
+          cache-to: type=gha,mode=max,scope=minima-docs-staging
+
+      - name: Deploy docs to Cloud Run (staging)
+        run: |
+          gcloud run deploy ${{ env.DOCS_SERVICE }} \
+            --image ${{ env.REGISTRY }}/minima-docs:${{ env.IMAGE_TAG }} \
+            --region ${{ env.REGION }} \
+            --platform managed \
+            --port 8080 \
+            --cpu 1 \
+            --memory 256Mi \
+            --min-instances 0 \
+            --max-instances 3 \
+            --allow-unauthenticated \
+            --service-account ${{ secrets.GCP_DEPLOYER_SA }} \
+            --quiet
+
+      - name: Print docs URL
+        run: |
+          URL=$(gcloud run services describe ${{ env.DOCS_SERVICE }} \
+            --region ${{ env.REGION }} \
+            --format 'value(status.url)')
+          echo "::notice::Minima docs (staging) deployed to: $URL"

minima_cli-0.4.9/.gitignore

@@ -0,0 +1,23 @@
+__pycache__/
+*.py[cod]
+.venv/
+.env
+.env.*
+!.env.example
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+dist/
+build/
+.minima_state/
+.seed_progress.json
+
+
+# Astro docs site
+docs-site/node_modules/
+docs-site/.astro/
+docs-site/dist/
+
+# PLAN
+docs/PLAN/

minima_cli-0.4.9/AGENTS.md

@@ -0,0 +1,90 @@
+# AGENTS.md
+
+Guidance for both human and AI agents working in this repo.
+
+## What this repo is
+
+- **`src/minima/`** — Minima: a recommend-only LLM cost-optimization service (FastAPI,
+  Python 3.11+). It does NOT proxy LLM calls. It tells you which model to run, you run
+  it, judge quality, and feed the outcome back via `POST /v1/feedback` so its Mubit
+  memory sharpens. See `docs/concepts.md` for the algorithm.
+- **`client_sdk/minima_client/`** — bundled sync + async Python client (`AsyncMinimaClient`
+  is what the harness uses). Ships inside the same wheel.
+- **`src/minima_harness/`** — a lean Python port of `@earendil-works/pi`'s agent harness
+  (`pi-ai` + `pi-agent-core`), made Minima-native. See its `LICENSE_PI`.
+
+## The Minima loop (always respect this)
+
+```
+recommend  ->  run the model yourself  ->  judge quality  ->  feedback
+```
+
+Minima never runs the model. Any harness owns model dispatch + quality judging. Feedback
+MUST include realized `input_tokens` / `output_tokens` / `actual_cost_usd` / `latency_ms`
+so the cost basis can climb `estimate -> observed -> rescaled` (the biggest accuracy
+lever). Outcome thresholds: `success >= 0.8`, `partial >= 0.4`, else `failure`.
+
+## Conventions
+
+- `from __future__ import annotations` at the top of every module.
+- Pydantic v2 `BaseModel` for serializable schemas; `@dataclass(slots=True)` for internal
+  types; `StrEnum` for enums; `Protocol` for seams (`Memory`, `Reasoner`, `Provider`).
+- Async-first. Bridge sync SDKs (Mubit) off the event loop via `anyio`/threadpools.
+- `structlog` via `get_logger("minima.<sub>")`.
+- ruff `line-length=100`, mypy `py311`. Never break the hot path: bookkeeping failures are
+  logged-and-swallowed (`except Exception: # noqa: BLE001`).
+- NO comments unless asked. Match existing style.
+
+## Commands
+
+```bash
+uv sync --extra dev                       # install (uv is the package manager)
+uv run ruff check . && uv run ruff format .  # lint + format
+uv run mypy src/minima src/minima_harness     # typecheck
+uv run pytest                              # unit + integration (hermetic, offline)
+uv run pytest -m live                      # needs a running Mubit (make run-mubit)
+uv run pytest tests/harness                # harness-only smoke
+make run                                   # local Minima on :8080 (harness dev target)
+```
+
+Offline tests MUST stay hermetic: the `conftest.py` autouse fixture neutralizes `.env`.
+Use `tests/factories.py:FakeMemory` + `create_app(...)` + `TestClient` for in-process
+tests without Mubit. For the harness, the faux provider
+(`minima_harness.ai.providers.register_faux_provider`) gives hermetic LLM calls.
+
+## minima_harness build roadmap
+
+Phases are independently verifiable; do not skip the verify step.
+
+- **Phase 0 (done)** — scaffold: `ai/` types, registry, tools, usage, stream dispatcher,
+  faux provider; `minima/config.py`; `tasks/` corpus; AGENTS.md; pyproject wiring.
+- **Phase 1 (done)** — ported `pi-ai`: real providers (`anthropic`, `google`,
+  `openai_compat` via raw httpx) registering into the provider registry (lazy, SDK
+  optional); cross-provider compat (`ai/compat.py`). Tests: faux + hermetic SSE/SDK
+  mapping + `-m live`.
+- **Phase 2 (done)** — ported `pi-agent-core`: `Agent` + `agent_loop` async generator,
+  events, tool execution loop (parallel via anyio), beforeToolCall/afterToolCall hooks,
+  steering/follow-up, abort, max_turns guard.
+- **Phase 3 (done)** — Minima integration: `minima/router.py` (recommend->set model,
+  feedback), `minima/mapping.py` (model_id <-> Model), `minima/judge.py`
+  (`QualityJudge` Protocol + `LLMJudge`/`DeterministicJudge`/`ConstJudge`),
+  `minima/runtime.py` (`MinimaAgent`). Hermetic via FakeMemory+ASGI app; live test.
+- **Phase 4 (done)** — `examples/harness_warmup.py` (demo + live modes),
+  `docs/harness.md`, README + examples/README sections.
+- **Phase A (done)** — cost observability: `RoutingResult` carries Minima's full ranked/
+  rationale/warnings payload + `baseline_cost_usd`; `CostMeter`; `before_route`
+  override/veto hook.
+- **Phase B (done)** — code-quality-aware routing: `CodeHealthExtractor` +
+  `ContextExtractor` protocol; `tags`/`difficulty`/`expected_input_tokens` from touched
+  files flow into `recommend()` via `prompt(files=...)`, with a discrimination gate.
+- **Phase C (done)** — token yield: `turns_taken` per prompt → `feedback(iterations=)` →
+  `FeedbackRequest`/`OutcomeRecord` gain a backward-compatible `iterations` field.
+
+## Hard rules
+
+- Do NOT add the `openai` SDK as a dependency — the OpenAI-compatible provider uses raw
+  `httpx` (matches PI's fetch approach; keeps deps lean). Reuse minima's existing
+  optional extras (`anthropic`, `google-genai`) for those providers.
+- Routing must be bypassable (`minima=None`) so the agent runtime works without Minima.
+- Keep PI's wire discriminator values (`type: "toolCall"`, `role`, `stopReason`) so the
+  shapes stay recognizable; snake_case the field names.