minima-cli 0.4.9__py3-none-any.whl

minima_client/client.py

@@ -0,0 +1,301 @@
+"""Sync and async clients mirroring the Minima endpoints."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from minima.schemas.common import Constraints, OutcomeLabel, TaskInput
+from minima.schemas.feedback import FeedbackRequest, FeedbackResponse
+from minima.schemas.models_catalog import ModelsResponse
+from minima.schemas.recommend import RecommendRequest, RecommendResponse
+from minima.schemas.savings import CalibrationResponse, SavingsResponse
+from minima.schemas.strategies import StrategiesResponse
+from minima.schemas.workflow import WorkflowRequest, WorkflowResponse
+from minima_client.errors import raise_for_status
+
+
+def _report_params(
+    namespace: str | None, days: float | None, group_by: str | None = None
+) -> dict[str, Any]:
+    params: dict[str, Any] = {}
+    if namespace is not None:
+        params["namespace"] = namespace
+    if days is not None:
+        params["days"] = days
+    if group_by is not None:
+        params["group_by"] = group_by
+    return params
+
+TaskLike = str | TaskInput | dict[str, Any]
+
+
+def _coerce_task(task: TaskLike) -> TaskInput:
+    if isinstance(task, TaskInput):
+        return task
+    if isinstance(task, str):
+        return TaskInput(task=task)
+    if isinstance(task, dict):
+        return TaskInput(**task)
+    raise TypeError(f"unsupported task type: {type(task)!r}")
+
+
+def _headers(api_key: str | None) -> dict[str, str]:
+    return {"Authorization": f"Bearer {api_key}"} if api_key else {}
+
+
+def _feedback_request(
+    recommendation_id: str,
+    chosen_model_id: str,
+    outcome: OutcomeLabel | str,
+    **kwargs: Any,
+) -> FeedbackRequest:
+    return FeedbackRequest(
+        recommendation_id=recommendation_id,
+        chosen_model_id=chosen_model_id,
+        outcome=OutcomeLabel(outcome),
+        **kwargs,
+    )
+
+
+class MinimaClient:
+    def __init__(self, base_url: str, api_key: str | None = None, timeout: float = 10.0):
+        self._client = httpx.Client(
+            base_url=base_url.rstrip("/"), headers=_headers(api_key), timeout=timeout
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> MinimaClient:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def _post(self, path: str, model: Any) -> Any:
+        resp = self._client.post(path, json=model.model_dump(mode="json"))
+        raise_for_status(resp)
+        return resp.json()
+
+    def recommend(
+        self,
+        task: TaskLike,
+        *,
+        cost_quality_tradeoff: float = 5.0,
+        constraints: Constraints | None = None,
+        user_id: str | None = None,
+        namespace: str | None = None,
+        allow_llm_escalation: bool = True,
+        explain: bool = True,
+        baseline_model_id: str | None = None,
+    ) -> RecommendResponse:
+        req = RecommendRequest(
+            task=_coerce_task(task),
+            cost_quality_tradeoff=cost_quality_tradeoff,
+            constraints=constraints or Constraints(),
+            user_id=user_id,
+            namespace=namespace,
+            allow_llm_escalation=allow_llm_escalation,
+            explain=explain,
+            baseline_model_id=baseline_model_id,
+        )
+        return RecommendResponse.model_validate(self._post("/v1/recommend", req))
+
+    def recommend_workflow(self, req: WorkflowRequest) -> WorkflowResponse:
+        return WorkflowResponse.model_validate(self._post("/v1/recommend/workflow", req))
+
+    def savings(
+        self,
+        namespace: str | None = None,
+        days: float | None = None,
+        group_by: str | None = None,
+    ) -> SavingsResponse:
+        """Counterfactual savings + routing health for your org (estimated AND realized)."""
+        resp = self._client.get("/v1/savings", params=_report_params(namespace, days, group_by))
+        raise_for_status(resp)
+        return SavingsResponse.model_validate(resp.json())
+
+    def calibration(
+        self,
+        namespace: str | None = None,
+        days: float | None = None,
+    ) -> CalibrationResponse:
+        """Is predicted_success telling the truth? ECE, reliability, and drift flags."""
+        resp = self._client.get("/v1/calibration", params=_report_params(namespace, days))
+        raise_for_status(resp)
+        return CalibrationResponse.model_validate(resp.json())
+
+    def feedback(
+        self,
+        recommendation_id: str,
+        chosen_model_id: str,
+        outcome: OutcomeLabel | str,
+        **kwargs: Any,
+    ) -> FeedbackResponse:
+        req = _feedback_request(recommendation_id, chosen_model_id, outcome, **kwargs)
+        return FeedbackResponse.model_validate(self._post("/v1/feedback", req))
+
+    def models(
+        self,
+        provider: str | None = None,
+        task_type: str | None = None,
+        max_cost: float | None = None,
+        include_stale: bool = True,
+    ) -> ModelsResponse:
+        params = {
+            k: v
+            for k, v in {
+                "provider": provider,
+                "task_type": task_type,
+                "max_cost": max_cost,
+                "include_stale": include_stale,
+            }.items()
+            if v is not None
+        }
+        resp = self._client.get("/v1/models", params=params)
+        raise_for_status(resp)
+        return ModelsResponse.model_validate(resp.json())
+
+    def strategies(
+        self,
+        namespace: str | None = None,
+        max_strategies: int = 5,
+        lesson_types: list[str] | None = None,
+    ) -> StrategiesResponse:
+        params: dict[str, Any] = {"max_strategies": max_strategies}
+        if namespace is not None:
+            params["namespace"] = namespace
+        if lesson_types:
+            params["lesson_types"] = lesson_types
+        resp = self._client.get("/v1/strategies", params=params)
+        raise_for_status(resp)
+        return StrategiesResponse.model_validate(resp.json())
+
+    def health(self) -> dict[str, Any]:
+        resp = self._client.get("/v1/health")
+        raise_for_status(resp)
+        return resp.json()
+
+
+class AsyncMinimaClient:
+    def __init__(self, base_url: str, api_key: str | None = None, timeout: float = 10.0):
+        self._client = httpx.AsyncClient(
+            base_url=base_url.rstrip("/"), headers=_headers(api_key), timeout=timeout
+        )
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncMinimaClient:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    async def _post(self, path: str, model: Any) -> Any:
+        resp = await self._client.post(path, json=model.model_dump(mode="json"))
+        raise_for_status(resp)
+        return resp.json()
+
+    async def recommend(
+        self,
+        task: TaskLike,
+        *,
+        cost_quality_tradeoff: float = 5.0,
+        constraints: Constraints | None = None,
+        user_id: str | None = None,
+        namespace: str | None = None,
+        allow_llm_escalation: bool = True,
+        explain: bool = True,
+        baseline_model_id: str | None = None,
+    ) -> RecommendResponse:
+        req = RecommendRequest(
+            task=_coerce_task(task),
+            cost_quality_tradeoff=cost_quality_tradeoff,
+            constraints=constraints or Constraints(),
+            user_id=user_id,
+            namespace=namespace,
+            allow_llm_escalation=allow_llm_escalation,
+            explain=explain,
+            baseline_model_id=baseline_model_id,
+        )
+        return RecommendResponse.model_validate(await self._post("/v1/recommend", req))
+
+    async def recommend_workflow(self, req: WorkflowRequest) -> WorkflowResponse:
+        return WorkflowResponse.model_validate(await self._post("/v1/recommend/workflow", req))
+
+    async def savings(
+        self,
+        namespace: str | None = None,
+        days: float | None = None,
+        group_by: str | None = None,
+    ) -> SavingsResponse:
+        """Counterfactual savings + routing health for your org (estimated AND realized)."""
+        resp = await self._client.get(
+            "/v1/savings", params=_report_params(namespace, days, group_by)
+        )
+        raise_for_status(resp)
+        return SavingsResponse.model_validate(resp.json())
+
+    async def calibration(
+        self,
+        namespace: str | None = None,
+        days: float | None = None,
+    ) -> CalibrationResponse:
+        """Is predicted_success telling the truth? ECE, reliability, and drift flags."""
+        resp = await self._client.get("/v1/calibration", params=_report_params(namespace, days))
+        raise_for_status(resp)
+        return CalibrationResponse.model_validate(resp.json())
+
+    async def feedback(
+        self,
+        recommendation_id: str,
+        chosen_model_id: str,
+        outcome: OutcomeLabel | str,
+        **kwargs: Any,
+    ) -> FeedbackResponse:
+        req = _feedback_request(recommendation_id, chosen_model_id, outcome, **kwargs)
+        return FeedbackResponse.model_validate(await self._post("/v1/feedback", req))
+
+    async def strategies(
+        self,
+        namespace: str | None = None,
+        max_strategies: int = 5,
+        lesson_types: list[str] | None = None,
+    ) -> StrategiesResponse:
+        params: dict[str, Any] = {"max_strategies": max_strategies}
+        if namespace is not None:
+            params["namespace"] = namespace
+        if lesson_types:
+            params["lesson_types"] = lesson_types
+        resp = await self._client.get("/v1/strategies", params=params)
+        raise_for_status(resp)
+        return StrategiesResponse.model_validate(resp.json())
+
+    async def models(
+        self,
+        provider: str | None = None,
+        task_type: str | None = None,
+        max_cost: float | None = None,
+        include_stale: bool = True,
+    ) -> ModelsResponse:
+        params = {
+            k: v
+            for k, v in {
+                "provider": provider,
+                "task_type": task_type,
+                "max_cost": max_cost,
+                "include_stale": include_stale,
+            }.items()
+            if v is not None
+        }
+        resp = await self._client.get("/v1/models", params=params)
+        raise_for_status(resp)
+        return ModelsResponse.model_validate(resp.json())
+
+    async def health(self) -> dict[str, Any]:
+        resp = await self._client.get("/v1/health")
+        raise_for_status(resp)
+        return resp.json()

minima_client/errors.py

@@ -0,0 +1,23 @@
+"""Client error type."""
+
+from __future__ import annotations
+
+import httpx
+
+
+class MinimaError(Exception):
+    def __init__(self, status: int, detail: str):
+        super().__init__(f"minima error {status}: {detail}")
+        self.status = status
+        self.detail = detail
+
+
+def raise_for_status(resp: httpx.Response) -> None:
+    if resp.status_code < 400:
+        return
+    try:
+        body = resp.json()
+        detail = body.get("detail") or body.get("title") or str(body)
+    except Exception:  # noqa: BLE001
+        detail = resp.text
+    raise MinimaError(resp.status_code, detail)

minima_harness/LICENSE_PI

@@ -0,0 +1,32 @@
+MIT License Attribution
+=======================
+
+Portions of this package (`src/minima_harness/`) are derived from the
+`@earendil-works/pi <https://github.com/earendil-works/pi>`_ project, which is
+licensed under the MIT License:
+
+    MIT License
+
+    Copyright (c) the @earendil-works/pi contributors
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE.
+
+This is a from-scratch Python port of design and APIs; no source code was copied
+verbatim. The Minima integration layer (`src/minima_harness/minima/`) is original
+work and is governed by the project's own license.

minima_harness/__init__.py

@@ -0,0 +1,16 @@
+"""minima_harness — a lean Python port of @earendil-works/pi's agent harness, made
+Minima-native (routes each turn through Minima's recommender and feeds outcomes back).
+
+Phase 0 ships the unified LLM API surface (``minima_harness.ai``), the task corpus
+(``minima_harness.tasks``), and harness config (``minima_harness.minima.HarnessConfig``).
+The ported agent runtime and the Minima router land in later phases.
+
+Derived from the MIT-licensed @earendil-works/pi (see LICENSE_PI).
+"""
+
+from minima_harness import ai, minima, tasks
+from minima_harness.minima.config import HarnessConfig
+
+__version__ = "0.1.0"
+
+__all__ = ["HarnessConfig", "__version__", "ai", "minima", "tasks"]

minima_harness/agent/__init__.py

@@ -0,0 +1,72 @@
+"""minima_harness.agent — ported pi-agent-core: Agent + agent_loop + events + tools."""
+
+from minima_harness.agent.agent import Agent
+from minima_harness.agent.events import (
+    AgentEndEvent,
+    AgentEvent,
+    AgentStartEvent,
+    MessageEndEvent,
+    MessageStartEvent,
+    MessageUpdateEvent,
+    ToolExecutionEndEvent,
+    ToolExecutionStartEvent,
+    ToolExecutionUpdateEvent,
+    TurnEndEvent,
+    TurnStartEvent,
+)
+from minima_harness.agent.loop import agent_loop, agent_loop_continue
+from minima_harness.agent.state import (
+    AgentLoopConfig,
+    AgentState,
+    ConvertToLlm,
+    TransformContext,
+    default_convert_to_llm,
+)
+from minima_harness.agent.tools import (
+    AfterToolCall,
+    AfterToolCallContext,
+    AfterToolCallResult,
+    AgentTool,
+    BeforeToolCall,
+    BeforeToolCallContext,
+    BeforeToolCallResult,
+    ThinkingLevel,
+    ToolExecutionMode,
+    ToolResult,
+    error_result,
+    find_agent_tool,
+)
+
+__all__ = [
+    "AfterToolCall",
+    "AfterToolCallContext",
+    "AfterToolCallResult",
+    "Agent",
+    "AgentEndEvent",
+    "AgentEvent",
+    "AgentLoopConfig",
+    "AgentStartEvent",
+    "AgentState",
+    "AgentTool",
+    "BeforeToolCall",
+    "BeforeToolCallContext",
+    "BeforeToolCallResult",
+    "ConvertToLlm",
+    "MessageEndEvent",
+    "MessageStartEvent",
+    "MessageUpdateEvent",
+    "ThinkingLevel",
+    "ToolExecutionEndEvent",
+    "ToolExecutionMode",
+    "ToolExecutionStartEvent",
+    "ToolExecutionUpdateEvent",
+    "ToolResult",
+    "TransformContext",
+    "TurnEndEvent",
+    "TurnStartEvent",
+    "agent_loop",
+    "agent_loop_continue",
+    "default_convert_to_llm",
+    "error_result",
+    "find_agent_tool",
+]