pcli-agent 0.1.0__py3-none-any.whl

pcli/cost/tracker.py

@@ -0,0 +1,126 @@
+"""Per-turn/session/global cost aggregation."""
+
+from __future__ import annotations
+
+import json
+from collections import defaultdict
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Literal
+
+from pcli.config.paths import cost_ledger_file
+from pcli.cost.pricing_table import PricingTable
+from pcli.llm.models import Usage
+from pcli.session.models import Session, TurnCost
+
+
+class CostTracker:
+    def __init__(
+        self,
+        session: Session,
+        *,
+        pricing_table: PricingTable | None = None,
+        ledger_path: Path | None = None,
+    ) -> None:
+        self._session = session
+        self._pricing = pricing_table or PricingTable.load()
+        self._ledger_path = ledger_path or cost_ledger_file()
+
+    def record_turn(
+        self,
+        model: str,
+        usage: Usage,
+        *,
+        source: Literal["main", "subagent", "compaction", "memory"] = "main",
+    ) -> TurnCost:
+        cost_usd = self._pricing.cost_usd(
+            model,
+            prompt_tokens=usage.prompt_tokens,
+            completion_tokens=usage.completion_tokens,
+            cached_tokens=usage.cached_tokens or 0,
+        )
+        turn = TurnCost(
+            turn_index=len(self._session.cost.turns),
+            model=model,
+            usage=usage,
+            cost_usd=cost_usd,
+            estimated=usage.estimated,
+            source=source,
+        )
+        self._session.cost.turns.append(turn)
+        self._session.cost.session_total_usd += cost_usd
+        self._session.cost.total_tokens += usage.total_tokens
+        self._append_to_global_ledger(turn)
+        return turn
+
+    def _append_to_global_ledger(self, turn: TurnCost) -> None:
+        record = {
+            "session_id": self._session.id,
+            "turn_index": turn.turn_index,
+            "model": turn.model,
+            "prompt_tokens": turn.usage.prompt_tokens,
+            "completion_tokens": turn.usage.completion_tokens,
+            "cached_tokens": turn.usage.cached_tokens or 0,
+            "total_tokens": turn.usage.total_tokens,
+            "cost_usd": turn.cost_usd,
+            "estimated": turn.estimated,
+            "created_at": turn.created_at.isoformat(),
+        }
+        path = self._ledger_path
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with path.open("a", encoding="utf-8") as fh:
+            fh.write(json.dumps(record) + "\n")
+
+
+def global_cost_report(since: datetime | None = None, *, ledger_path: Path | None = None) -> dict:
+    path = ledger_path or cost_ledger_file()
+    total_cost = 0.0
+    total_tokens = 0
+    turn_count = 0
+    by_model: dict[str, float] = defaultdict(float)
+
+    if path.exists():
+        with path.open("r", encoding="utf-8") as fh:
+            for line in fh:
+                line = line.strip()
+                if not line:
+                    continue
+                record = json.loads(line)
+                created_at = datetime.fromisoformat(record["created_at"])
+                if created_at.tzinfo is None:
+                    created_at = created_at.replace(tzinfo=UTC)
+                if since is not None and created_at < since:
+                    continue
+                total_cost += record["cost_usd"]
+                total_tokens += record["total_tokens"]
+                turn_count += 1
+                by_model[record["model"]] += record["cost_usd"]
+
+    return {
+        "total_cost_usd": total_cost,
+        "total_tokens": total_tokens,
+        "turn_count": turn_count,
+        "by_model": dict(by_model),
+    }
+
+
+def cost_budget_reason(session: Session, max_session_cost_usd: float | None) -> str | None:
+    """None if there's no cap (max_session_cost_usd unset) or spend is still
+    under it; otherwise a formatted reason string for AgentLoop.run_turn's
+    budget_check to surface as a termination note - the one place that owns
+    this wording, so every call site (main loop, headless/scheduled runs,
+    subagents, memory extraction - see their own run_turn call sites) stays
+    consistent. session.cost.session_total_usd already includes subagent/
+    compaction/memory-extraction spend folded in (CostTracker.record_turn),
+    so this one check covers all of it regardless of which loop is asking."""
+    if max_session_cost_usd is None:
+        return None
+    spent = session.cost.session_total_usd
+    if spent < max_session_cost_usd:
+        return None
+    return (
+        f"Reached the session cost budget (${max_session_cost_usd:.2f}) - spent "
+        f"${spent:.4f} so far. Raise max_session_cost_usd (in the TUI: /budget <amount>; "
+        "otherwise PCLI_MAX_SESSION_COST_USD or config.toml) to continue this session, or "
+        "start a new one."
+    )

pcli/llm/client.py

@@ -0,0 +1,285 @@
+"""Async client for an OpenAI-compatible chat-completions gateway."""
+
+from __future__ import annotations
+
+import asyncio
+import random
+from collections.abc import AsyncIterator
+from typing import Any, Self
+
+import httpx
+from tenacity import retry, retry_if_exception_type, stop_after_attempt, wait_exponential_jitter
+
+from pcli.config.settings import Settings
+from pcli.cost.context_detect import detect_context_limit as _detect_context_limit
+from pcli.llm.errors import GatewayError
+from pcli.llm.models import ChatMessage, StreamEvent, ToolDefinition, Usage
+from pcli.llm.streaming import parse_sse_stream
+
+
+def _backoff_seconds(attempt: int) -> float:
+    return min(20.0, float(2**attempt)) + random.uniform(0, 1)
+
+
+class GatewayClient:
+    def __init__(self, settings: Settings) -> None:
+        if not settings.is_configured():
+            raise GatewayError("Gateway URL and API key must be configured before use.")
+        self._settings = settings
+        headers = {"Content-Type": "application/json"}
+        if settings.gateway_api_key:
+            if settings.gateway_auth_header.lower() == "authorization":
+                headers["Authorization"] = f"Bearer {settings.gateway_api_key}"
+            else:
+                headers[settings.gateway_auth_header] = settings.gateway_api_key
+        self._client = httpx.AsyncClient(
+            base_url=settings.gateway_base_url.rstrip("/"),
+            headers=headers,
+            timeout=settings.effective_request_timeout_s,
+        )
+        # The constructor-level timeout above is only a fallback baseline —
+        # every actual request passes timeout=self._effective_timeout()
+        # explicitly (httpx supports a per-request override), so a setting
+        # change (e.g. via the /timeout command) takes effect on the very
+        # next request instead of requiring GatewayClient to be rebuilt.
+
+    def _effective_timeout(self) -> float:
+        return self._settings.effective_request_timeout_s
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        await self.aclose()
+
+    def _network_error_hint(self, exc: httpx.HTTPError) -> str | None:
+        """Turns a raw httpx transport failure into something the user can
+        actually act on: which setting to change, and to what — grounded in
+        a real debugged case where a local model streaming at ~5 tokens/sec
+        tripped the 120s default mid-response, and pcli's only trace of it
+        was an opaque "Gateway error" with the underlying exception text."""
+        timeout = self._settings.effective_request_timeout_s
+        suggestion = max(600, int(timeout * 3))
+        gateway_kind = "local API gateway" if self._settings.is_local_api() else "gateway"
+
+        if isinstance(exc, httpx.ConnectTimeout):
+            return (
+                f"Couldn't connect to the {gateway_kind} within {timeout:g}s "
+                f"(request_timeout_s={timeout:g}). Check it's actually running at "
+                f"{self._settings.gateway_base_url!r} — or, if it's just slow to accept "
+                f"connections (e.g. still loading a model), set a larger request_timeout_s "
+                f"(e.g. {suggestion}) via PCLI_REQUEST_TIMEOUT_S or config.toml."
+            )
+        if isinstance(exc, httpx.TimeoutException):
+            local_note = (
+                "Local models are often much slower than hosted ones — " if self._settings.is_local_api() else ""
+            )
+            return (
+                f"Read timed out on the {gateway_kind} (request_timeout_s={timeout:g}). "
+                f"{local_note}Set a larger request_timeout_s (e.g. {suggestion}) via "
+                "PCLI_REQUEST_TIMEOUT_S or config.toml."
+            )
+        if isinstance(exc, httpx.ConnectError):
+            return (
+                f"Couldn't reach the {gateway_kind} at {self._settings.gateway_base_url!r} — "
+                "check that it's running and that gateway_base_url is correct."
+            )
+        return None
+
+    def _http_status_hint(self, status_code: int, body: str = "") -> str | None:
+        # Checked before the status-code-specific branches below: OpenAI-
+        # compatible gateways (including llama.cpp/LM Studio) report a
+        # context-length overflow as a 400 with wording that varies by
+        # backend, so this is a text match on the body rather than a status
+        # code alone. Worth surfacing as its own hint rather than a raw
+        # gateway error string, since the cause isn't obvious from a bare
+        # "invalid_request_error" — this is also the one context-length
+        # failure mode pcli's own turn-based auto-compaction can't catch: a
+        # subagent's own nested tool-calling loop has no compaction of its
+        # own (see tools/_nested_agent.py), so a long subagent task can hit
+        # this mid-turn with no prior warning.
+        body_lower = body.lower()
+        if status_code == 400 and (
+            "context_length_exceeded" in body_lower
+            or "context length" in body_lower
+            or "context window" in body_lower
+            or ("maximum" in body_lower and "token" in body_lower)
+        ):
+            return (
+                "This looks like a context-length overflow — the request (conversation history "
+                "plus tool results) is larger than the model can accept in one call. If this is "
+                "the main conversation, /context-limit sets the context window pcli assumes for "
+                "auto-compaction; if it's a subagent's own task, its conversation has no "
+                "compaction of its own, so try splitting the task into smaller, narrower steps."
+            )
+        if status_code in (401, 403):
+            if self._settings.gateway_api_key:
+                return "The gateway rejected the configured gateway_api_key — check it's correct and hasn't expired."
+            return (
+                "No gateway_api_key is configured and this gateway appears to require one — "
+                "set PCLI_GATEWAY_API_KEY or gateway_api_key in config.toml."
+            )
+        if status_code == 429:
+            return (
+                f"Rate-limited by the gateway. pcli already retries with backoff (up to "
+                f"max_retries={self._settings.max_retries}) — if this keeps happening, raise "
+                "max_retries or reduce request frequency."
+            )
+        if status_code >= 500:
+            return "This is usually transient on the gateway's side — trying again shortly often helps."
+        return None
+
+    def _build_payload(
+        self,
+        messages: list[ChatMessage],
+        *,
+        model: str | None,
+        tools: list[ToolDefinition] | None,
+        stream: bool,
+        temperature: float | None,
+        max_tokens: int | None = None,
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "model": model or self._settings.default_model,
+            "messages": [m.to_wire() for m in messages],
+            "stream": stream,
+        }
+        if tools:
+            payload["tools"] = [t.model_dump() for t in tools]
+        if temperature is not None:
+            payload["temperature"] = temperature
+        if max_tokens is not None:
+            payload["max_tokens"] = max_tokens
+        if stream:
+            payload["stream_options"] = {"include_usage": True}
+        return payload
+
+    async def chat_stream(
+        self,
+        messages: list[ChatMessage],
+        *,
+        model: str | None = None,
+        tools: list[ToolDefinition] | None = None,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+    ) -> AsyncIterator[StreamEvent]:
+        """Streams chat events. Retries (with backoff) only apply to failures that
+        happen before any event has been yielded — once partial output has reached
+        the caller, retrying the whole request would duplicate it, so a mid-stream
+        failure is raised immediately instead.
+
+        `max_tokens`, when given, is the dynamic per-request cap computed by
+        cost/context.py's compute_max_response_tokens — see AgentLoop, which
+        is what actually sets it.
+        """
+        payload = self._build_payload(
+            messages, model=model, tools=tools, stream=True, temperature=temperature,
+            max_tokens=max_tokens,
+        )
+        max_attempts = max(1, self._settings.max_retries)
+        last_error: GatewayError | None = None
+
+        for attempt in range(1, max_attempts + 1):
+            started = False
+            try:
+                async with self._client.stream(
+                    "POST", "/chat/completions", json=payload, timeout=self._effective_timeout()
+                ) as response:
+                    if response.status_code >= 400:
+                        body = await response.aread()
+                        body_text = body.decode(errors="replace")
+                        raise GatewayError.from_http_status(
+                            response.status_code,
+                            body_text,
+                            hint=self._http_status_hint(response.status_code, body_text),
+                        )
+                    async for event in parse_sse_stream(response.aiter_lines()):
+                        started = True
+                        yield event
+                    return
+            except GatewayError as exc:
+                last_error = exc
+                if not exc.retryable or started or attempt == max_attempts:
+                    raise
+            except httpx.HTTPError as exc:
+                last_error = GatewayError.from_network_error(str(exc), hint=self._network_error_hint(exc))
+                if started or attempt == max_attempts:
+                    raise last_error
+
+            await asyncio.sleep(_backoff_seconds(attempt))
+
+        if last_error:
+            raise last_error
+
+    async def collect(
+        self,
+        messages: list[ChatMessage],
+        *,
+        model: str | None = None,
+        tools: list[ToolDefinition] | None = None,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+    ) -> tuple[ChatMessage, Usage]:
+        """Consumes chat_stream and returns the final assembled message + usage."""
+        from pcli.llm.models import ToolCall, ToolCallCompleteEvent, UsageEvent
+
+        text_parts: list[str] = []
+        tool_calls: list[ToolCall] = []
+        usage = Usage()
+
+        async for event in self.chat_stream(
+            messages, model=model, tools=tools, temperature=temperature, max_tokens=max_tokens
+        ):
+            if event.kind == "text_delta":
+                text_parts.append(event.text)
+            elif isinstance(event, ToolCallCompleteEvent):
+                tool_calls = event.tool_calls
+            elif isinstance(event, UsageEvent):
+                usage = event.usage
+
+        message = ChatMessage(
+            role="assistant",
+            content="".join(text_parts) or None,
+            tool_calls=tool_calls or None,
+        )
+        return message, usage
+
+    @retry(
+        stop=stop_after_attempt(3),
+        wait=wait_exponential_jitter(initial=1, max=10),
+        retry=retry_if_exception_type(httpx.HTTPError),
+        reraise=True,
+    )
+    async def health_check(self) -> bool:
+        """Best-effort reachability probe against the gateway's models endpoint."""
+        response = await self._client.get("/models", timeout=self._effective_timeout())
+        return response.status_code < 500
+
+    async def list_models(self) -> list[str]:
+        """Fetches available model IDs from the gateway's OpenAI-compatible
+        `GET /models` endpoint (`{"data": [{"id": "..."}, ...]}`)."""
+        try:
+            response = await self._client.get("/models", timeout=self._effective_timeout())
+        except httpx.HTTPError as exc:
+            raise GatewayError.from_network_error(str(exc), hint=self._network_error_hint(exc)) from exc
+        if response.status_code >= 400:
+            raise GatewayError.from_http_status(
+                response.status_code,
+                response.text,
+                hint=self._http_status_hint(response.status_code, response.text),
+            )
+        payload = response.json()
+        entries = payload.get("data", []) if isinstance(payload, dict) else []
+        ids = [entry["id"] for entry in entries if isinstance(entry, dict) and "id" in entry]
+        return sorted(ids)
+
+    async def detect_context_limit(self, model: str) -> int | None:
+        """Best-effort: queries this gateway directly for model's real
+        context window, trying several known backend-specific extensions
+        (see cost/context_detect.py — no single standard covers this).
+        None if nothing answered, including for hosted-only gateways that
+        expose no such information at all. Never raises."""
+        return await _detect_context_limit(self._client, model)

pcli/llm/errors.py

@@ -0,0 +1,37 @@
+"""Error hierarchy for the gateway client, with retry classification."""
+
+from __future__ import annotations
+
+
+class GatewayError(Exception):
+    """Raised for any failure talking to the LLM gateway."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        retryable: bool = False,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.retryable = retryable
+
+    @classmethod
+    def from_http_status(cls, status_code: int, message: str, *, hint: str | None = None) -> GatewayError:
+        retryable = status_code == 429 or status_code >= 500
+        full_message = f"{message} {hint}" if hint else message
+        return cls(full_message, status_code=status_code, retryable=retryable)
+
+    @classmethod
+    def from_network_error(cls, message: str, *, hint: str | None = None) -> GatewayError:
+        # hint is folded directly into .message (not kept as a separate
+        # attribute) so every existing call site that already displays
+        # str(exc)/exc.message — chat.py's turn/compaction/models handlers,
+        # subagent_tool.py's "Subagent failed: {exc}", ... — picks up
+        # actionable config guidance automatically, with no per-site change
+        # needed. See GatewayClient._network_error_hint/_http_status_hint
+        # for what gets suggested and why.
+        full_message = f"{message} {hint}" if hint else message
+        return cls(full_message, status_code=None, retryable=True)

pcli/llm/models.py

@@ -0,0 +1,100 @@
+"""Pydantic models for the OpenAI-compatible chat-completions wire format."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel
+
+Role = Literal["system", "user", "assistant", "tool"]
+
+
+class ToolCallFunction(BaseModel):
+    name: str
+    arguments: str = ""
+
+
+class ToolCall(BaseModel):
+    id: str
+    type: Literal["function"] = "function"
+    function: ToolCallFunction
+
+
+class ChatMessage(BaseModel):
+    role: Role
+    content: str | None = None
+    tool_calls: list[ToolCall] | None = None
+    tool_call_id: str | None = None
+    name: str | None = None
+
+    def to_wire(self) -> dict[str, Any]:
+        data: dict[str, Any] = {"role": self.role}
+        if self.content is not None:
+            data["content"] = self.content
+        if self.tool_calls:
+            data["tool_calls"] = [tc.model_dump() for tc in self.tool_calls]
+        if self.tool_call_id:
+            data["tool_call_id"] = self.tool_call_id
+        if self.name:
+            data["name"] = self.name
+        return data
+
+
+class ToolDefinition(BaseModel):
+    """A single entry in the OpenAI-style `tools=[...]` request payload."""
+
+    type: Literal["function"] = "function"
+    function: dict[str, Any]
+
+
+class Usage(BaseModel):
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    total_tokens: int = 0
+    cached_tokens: int | None = None
+    estimated: bool = False
+
+
+class TextDelta(BaseModel):
+    kind: Literal["text_delta"] = "text_delta"
+    text: str
+
+
+class ReasoningDelta(BaseModel):
+    """A fragment of a reasoning/"thinking" model's chain-of-thought,
+    streamed under `delta.reasoning_content` (or `delta.reasoning`) by
+    OpenAI-compatible servers that expose it as a channel separate from the
+    final answer (`delta.content`) — e.g. vLLM/SGLang/LM Studio serving
+    DeepSeek-R1-style or Nemotron "thinking" models. Never folded into the
+    assistant message's actual content; see agent/loop.py."""
+
+    kind: Literal["reasoning_delta"] = "reasoning_delta"
+    text: str
+
+
+class ToolCallDelta(BaseModel):
+    kind: Literal["tool_call_delta"] = "tool_call_delta"
+    index: int
+    id: str | None = None
+    name: str | None = None
+    arguments_fragment: str = ""
+
+
+class ToolCallCompleteEvent(BaseModel):
+    kind: Literal["tool_call_complete"] = "tool_call_complete"
+    tool_calls: list[ToolCall]
+
+
+class UsageEvent(BaseModel):
+    kind: Literal["usage"] = "usage"
+    usage: Usage
+
+
+class FinishEvent(BaseModel):
+    kind: Literal["finish"] = "finish"
+    reason: str | None = None
+
+
+StreamEvent = (
+    TextDelta | ReasoningDelta | ToolCallDelta | ToolCallCompleteEvent | UsageEvent | FinishEvent
+)

pcli/llm/streaming.py

@@ -0,0 +1,108 @@
+"""Parses an OpenAI-compatible chat-completions SSE stream into StreamEvents.
+
+Tool-call arguments arrive fragmented across multiple chunks, keyed by the
+`index` field within `delta.tool_calls`; fragments must be accumulated until
+`finish_reason == "tool_calls"` before the full arguments JSON is usable.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator
+
+from pcli.llm.models import (
+    FinishEvent,
+    ReasoningDelta,
+    StreamEvent,
+    TextDelta,
+    ToolCall,
+    ToolCallCompleteEvent,
+    ToolCallDelta,
+    ToolCallFunction,
+    Usage,
+    UsageEvent,
+)
+
+
+class _ToolCallAccumulator:
+    def __init__(self) -> None:
+        self.id: str | None = None
+        self.name: str | None = None
+        self.arguments = ""
+
+    def to_tool_call(self) -> ToolCall:
+        return ToolCall(
+            id=self.id or "",
+            function=ToolCallFunction(name=self.name or "", arguments=self.arguments),
+        )
+
+
+async def parse_sse_stream(lines: AsyncIterator[str]) -> AsyncIterator[StreamEvent]:
+    accumulators: dict[int, _ToolCallAccumulator] = {}
+
+    async for raw_line in lines:
+        line = raw_line.strip()
+        if not line or not line.startswith("data:"):
+            continue
+        payload = line[len("data:") :].strip()
+        if payload == "[DONE]":
+            break
+        try:
+            chunk = json.loads(payload)
+        except json.JSONDecodeError:
+            continue
+
+        usage = chunk.get("usage")
+        if usage:
+            yield UsageEvent(
+                usage=Usage(
+                    prompt_tokens=usage.get("prompt_tokens", 0),
+                    completion_tokens=usage.get("completion_tokens", 0),
+                    total_tokens=usage.get("total_tokens", 0),
+                    cached_tokens=(usage.get("prompt_tokens_details") or {}).get("cached_tokens"),
+                )
+            )
+
+        choices = chunk.get("choices") or []
+        if not choices:
+            continue
+        choice = choices[0]
+        delta = choice.get("delta") or {}
+
+        content = delta.get("content")
+        if content:
+            yield TextDelta(text=content)
+
+        # Reasoning/"thinking" models (DeepSeek-R1-style, Nemotron "detailed
+        # thinking", ...) served through vLLM/SGLang/LM Studio stream their
+        # chain-of-thought under a separate field, never under `content` —
+        # a model that spends its whole response reasoning without ever
+        # transitioning to `content` previously vanished here entirely: no
+        # text, no tool call, no error, just a silently empty turn. Servers
+        # aren't consistent about the key name, so both are checked.
+        reasoning = delta.get("reasoning_content") or delta.get("reasoning")
+        if reasoning:
+            yield ReasoningDelta(text=reasoning)
+
+        for tc in delta.get("tool_calls") or []:
+            index = tc.get("index", 0)
+            acc = accumulators.setdefault(index, _ToolCallAccumulator())
+            if tc.get("id"):
+                acc.id = tc["id"]
+            fn = tc.get("function") or {}
+            if fn.get("name"):
+                acc.name = fn["name"]
+            frag = fn.get("arguments") or ""
+            if frag:
+                acc.arguments += frag
+            yield ToolCallDelta(
+                index=index, id=tc.get("id"), name=fn.get("name"), arguments_fragment=frag
+            )
+
+        finish_reason = choice.get("finish_reason")
+        if finish_reason:
+            if finish_reason == "tool_calls" and accumulators:
+                completed = [accumulators[i].to_tool_call() for i in sorted(accumulators)]
+                yield ToolCallCompleteEvent(tool_calls=completed)
+                accumulators.clear()
+            yield FinishEvent(reason=finish_reason)