minima-cli 0.10.0__tar.gz → 0.12.0__tar.gz

minima_cli-0.12.0/.env.example

@@ -0,0 +1,160 @@
+# --- 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}
+
+
+# --- 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
+
+# --- 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.12.0/.github/workflows/prod.yml

@@ -0,0 +1,191 @@
+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" \
+            --set-secrets="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"
+
+  # ── 3. Publish minima-cli to PyPI ────────────────────────────────────────────
+  # Builds the sdist+wheel at the release tag and uploads to PyPI (the dist bundles the
+  # `minima_client` SDK). --skip-existing makes a manual re-deploy of an already-published
+  # version a no-op instead of an error. Needs no GCP — only the PYPI_API_TOKEN secret.
+  publish-pypi:
+    name: Publish → PyPI
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout @ release tag
+        uses: actions/checkout@v5
+        with:
+          ref: ${{ env.RELEASE_TAG }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade build twine
+          python -m build
+
+      - name: Check metadata
+        run: python -m twine check dist/*
+
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: python -m twine upload --skip-existing dist/*