minima-cli 0.4.9__py3-none-any.whl

minima/llm/gemini.py

@@ -0,0 +1,124 @@
+"""Gemini-backed reasoner (best-effort, secondary provider).
+
+Uses google-genai structured output. Any error degrades gracefully to None.
+
+Gemini's ``response_schema`` is a constrained dialect of JSON Schema (a single ``type``
+per field plus a ``nullable`` flag; no ``type: [...]`` unions and no
+``additionalProperties``), so the Anthropic/strict-JSON schemas in ``llm.base`` can't be
+reused verbatim — these Gemini-native equivalents below are what the API accepts.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Sequence
+from typing import Any
+
+from minima.llm.base import (
+    CLASSIFY_SYSTEM,
+    RANK_SYSTEM,
+    CandidateView,
+    ReasonerResult,
+    build_rank_user,
+    parse_classification,
+    parse_ranking,
+)
+from minima.logging import get_logger
+from minima.schemas.common import Difficulty, TaskType
+
+log = get_logger("minima.llm.gemini")
+
+DEFAULT_MODEL = "gemini-2.5-flash"
+
+_GEMINI_RANKING_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "recommended": {"type": "string"},
+        "fallback": {"type": "string", "nullable": True},
+        "ranking": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "model_id": {"type": "string"},
+                    "predicted_success": {"type": "number"},
+                    "rationale": {"type": "string"},
+                },
+                "required": ["model_id", "predicted_success", "rationale"],
+            },
+        },
+    },
+    "required": ["recommended", "ranking"],
+}
+
+_GEMINI_CLASSIFY_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "task_type": {"type": "string", "enum": [t.value for t in TaskType]},
+        "difficulty": {"type": "string", "enum": [d.value for d in Difficulty]},
+    },
+    "required": ["task_type", "difficulty"],
+}
+
+
+class GeminiReasoner:
+    def __init__(self, *, model: str, api_key: str, timeout_ms: int, max_tokens: int):
+        import google.genai as genai  # lazy; optional extra
+
+        self._genai = genai
+        self._model = model
+        self._max_tokens = max_tokens
+        # Bound the call so a hung provider can't stall a recommendation (genai timeout
+        # is in milliseconds). Without this the Gemini client would wait indefinitely.
+        self._client = genai.Client(api_key=api_key, http_options={"timeout": timeout_ms})
+
+    async def _json_call(self, *, system: str, user: str, schema: dict) -> Any | None:
+        try:
+            resp = await self._client.aio.models.generate_content(
+                model=self._model,
+                contents=user,
+                config={
+                    "system_instruction": system,
+                    "response_mime_type": "application/json",
+                    "response_schema": schema,
+                    "max_output_tokens": self._max_tokens,
+                },
+            )
+            text = getattr(resp, "text", None)
+            if not text:
+                return None
+            return json.loads(text)
+        except Exception as exc:  # noqa: BLE001 — reasoner must never break a recommendation
+            log.warning("reasoner_call_failed", model=self._model, error=str(exc))
+            return None
+
+    async def rank(
+        self,
+        *,
+        task: str,
+        task_type: str,
+        difficulty: str,
+        candidates: Sequence[CandidateView],
+        memory_block: str,
+        cost_quality_tradeoff: float,
+    ) -> ReasonerResult | None:
+        user = build_rank_user(
+            task=task,
+            task_type=task_type,
+            difficulty=difficulty,
+            candidates=candidates,
+            memory_block=memory_block,
+            cost_quality_tradeoff=cost_quality_tradeoff,
+        )
+        data = await self._json_call(system=RANK_SYSTEM, user=user, schema=_GEMINI_RANKING_SCHEMA)
+        if data is None:
+            return None
+        return parse_ranking(data, {c.model_id for c in candidates})
+
+    async def classify(self, *, task: str) -> tuple[TaskType, Difficulty] | None:
+        data = await self._json_call(
+            system=CLASSIFY_SYSTEM, user=task[:2000], schema=_GEMINI_CLASSIFY_SCHEMA
+        )
+        if data is None:
+            return None
+        return parse_classification(data)

minima/llm/registry.py

@@ -0,0 +1,54 @@
+"""Build a reasoner from settings, or None when disabled/unconfigured."""
+
+from __future__ import annotations
+
+from minima.config import Settings
+from minima.llm.base import Reasoner
+from minima.logging import get_logger
+
+log = get_logger("minima.llm")
+
+
+def build_reasoner(settings: Settings) -> Reasoner | None:
+    provider = settings.minima_reasoner_provider.lower().strip()
+    if provider in ("", "none"):
+        return None
+
+    if provider == "anthropic":
+        if not settings.anthropic_api_key:
+            log.warning("reasoner_disabled_no_key", provider="anthropic")
+            return None
+        # The provider SDK is imported lazily (here and inside the constructor), so
+        # catch ImportError across both: a missing extra must degrade, not crash startup.
+        try:
+            from minima.llm.anthropic import DEFAULT_MODEL, AnthropicReasoner
+
+            return AnthropicReasoner(
+                model=settings.minima_reasoner_model or DEFAULT_MODEL,
+                api_key=settings.anthropic_api_key,
+                timeout_ms=settings.minima_reasoner_timeout_ms,
+                max_tokens=settings.minima_reasoner_max_tokens,
+            )
+        except ImportError:
+            log.warning("reasoner_extra_missing", provider="anthropic", extra="reasoner-anthropic")
+            return None
+
+    if provider == "gemini":
+        if not settings.gemini_api_key:
+            log.warning("reasoner_disabled_no_key", provider="gemini")
+            return None
+        try:
+            from minima.llm.gemini import DEFAULT_MODEL, GeminiReasoner
+
+            return GeminiReasoner(
+                model=settings.minima_reasoner_model or DEFAULT_MODEL,
+                api_key=settings.gemini_api_key,
+                timeout_ms=settings.minima_reasoner_timeout_ms,
+                max_tokens=settings.minima_reasoner_max_tokens,
+            )
+        except ImportError:
+            log.warning("reasoner_extra_missing", provider="gemini", extra="reasoner-gemini")
+            return None
+
+    log.warning("reasoner_unknown_provider", provider=provider)
+    return None

minima/logging.py

@@ -0,0 +1,28 @@
+"""Structured logging setup."""
+
+from __future__ import annotations
+
+import logging
+
+import structlog
+
+
+def configure_logging(level: str = "info") -> None:
+    log_level = getattr(logging, level.upper(), logging.INFO)
+    logging.basicConfig(format="%(message)s", level=log_level)
+    structlog.configure(
+        wrapper_class=structlog.make_filtering_bound_logger(log_level),
+        processors=[
+            structlog.contextvars.merge_contextvars,
+            structlog.processors.add_log_level,
+            structlog.processors.TimeStamper(fmt="iso"),
+            structlog.processors.StackInfoRenderer(),
+            structlog.processors.format_exc_info,
+            structlog.processors.JSONRenderer(),
+        ],
+        cache_logger_on_first_use=True,
+    )
+
+
+def get_logger(name: str = "minima") -> structlog.stdlib.BoundLogger:
+    return structlog.get_logger(name)

minima/main.py

@@ -0,0 +1,109 @@
+"""FastAPI application factory and lifespan wiring."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from collections.abc import AsyncIterator
+
+from fastapi import FastAPI
+
+from minima.api.errors import register_error_handlers
+from minima.api.routers import (
+    calibration,
+    feedback,
+    health,
+    models,
+    recommend,
+    savings,
+    strategies,
+)
+from minima.catalog.refresh import refresh_loop
+from minima.catalog.store import CatalogStore
+from minima.config import Settings, get_settings
+from minima.llm.registry import build_reasoner
+from minima.logging import configure_logging
+from minima.memory.adapter import Memory
+from minima.recommender.decisionlog import build_decision_log
+from minima.recommender.durablerefs import build_durable_refs
+from minima.recommender.engine import Recommender
+from minima.recommender.propensity import build_propensity
+from minima.recommender.recstore import LaneCounter, RecStore, build_recstore
+from minima.tenancy.passthrough import PassthroughRuntime
+from minima.version import __version__
+
+
+@contextlib.asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+    settings: Settings = app.state.settings
+    configure_logging(settings.minima_log_level)
+
+    injected: dict = getattr(app.state, "_injected", {})
+    catalog_store: CatalogStore = injected.get("catalog_store") or CatalogStore(settings)
+    recstore_backend: RecStore = injected.get("recstore") or build_recstore(settings)
+    propensity_backend = build_propensity(settings)
+    decision_log_backend = build_decision_log(settings)
+    reasoner = build_reasoner(settings)
+    lane_counter = LaneCounter()
+
+    app.state.catalog_store = catalog_store
+    app.state.lane_counter = lane_counter
+    injected_memory: Memory | None = injected.get("memory")
+    app.state.passthrough_runtime = injected.get("passthrough_runtime") or PassthroughRuntime(
+        settings=settings,
+        catalog_store=catalog_store,
+        reasoner=reasoner,
+        recstore_backend=recstore_backend,
+        propensity_backend=propensity_backend,
+        lane_counter=lane_counter,
+        memory_factory=(lambda _key: injected_memory) if injected_memory is not None else None,
+        decision_log_backend=decision_log_backend,
+        durable_refs_backend=build_durable_refs(settings),
+    )
+
+    refresh_task: asyncio.Task | None = None
+    if getattr(app.state, "_start_refresh", True):
+        refresh_task = asyncio.create_task(refresh_loop(settings, catalog_store))
+
+    try:
+        yield
+    finally:
+        if refresh_task is not None:
+            refresh_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await refresh_task
+
+
+def create_app(
+    *,
+    settings: Settings | None = None,
+    memory: Memory | None = None,
+    catalog_store: CatalogStore | None = None,
+    recstore: RecStore | None = None,
+    recommender: Recommender | None = None,
+    passthrough_runtime: PassthroughRuntime | None = None,
+    start_refresh: bool = True,
+) -> FastAPI:
+    app = FastAPI(title="Minima", version=__version__, lifespan=lifespan)
+    app.state.settings = settings or get_settings()
+    app.state._injected = {
+        "memory": memory,
+        "catalog_store": catalog_store,
+        "recstore": recstore,
+        "recommender": recommender,
+        "passthrough_runtime": passthrough_runtime,
+    }
+    app.state._start_refresh = start_refresh
+
+    register_error_handlers(app)
+    app.include_router(recommend.router)
+    app.include_router(feedback.router)
+    app.include_router(models.router)
+    app.include_router(strategies.router)
+    app.include_router(savings.router)
+    app.include_router(calibration.router)
+    app.include_router(health.router)
+    return app
+
+
+app = create_app()

minima/memory/__init__.py

@@ -0,0 +1 @@
+"""Mubit memory integration — the only place the Mubit SDK is touched."""