docagent-cli 0.0.35__py3-none-any.whl

docagent_cli/_session_stats.py

@@ -0,0 +1,114 @@
+"""Lightweight session statistics and token formatting utilities.
+
+This module is intentionally kept free of heavy dependencies (no pydantic, no
+config, no widget imports) so that `app.py` can import `SessionStats` and
+`format_token_count` at module level without pulling in the full
+`textual_adapter` dependency tree.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+SpinnerStatus = Literal["Thinking", "Offloading"] | None
+"""Valid spinner display states, or `None` to hide."""
+
+
+@dataclass
+class ModelStats:
+    """Token stats for a single model within a session.
+
+    Attributes:
+        request_count: Number of LLM API requests made to this model.
+        input_tokens: Cumulative input tokens sent to this model.
+        output_tokens: Cumulative output tokens received from this model.
+    """
+
+    request_count: int = 0
+    input_tokens: int = 0
+    output_tokens: int = 0
+
+
+@dataclass
+class SessionStats:
+    """Stats accumulated over a single agent turn (or full session).
+
+    Attributes:
+        request_count: Total LLM API requests made (each chunk with
+            usage_metadata counts as one completed request).
+        input_tokens: Cumulative input tokens across all LLM requests.
+        output_tokens: Cumulative output tokens across all LLM requests.
+        wall_time_seconds: Wall-clock duration from stream start to end.
+        per_model: Per-model breakdown keyed by model name.
+            Populated only when `record_request` receives a non-empty
+            `model_name`. Empty dict means no named-model requests were
+            recorded; `print_usage_table` omits the model table in that case and
+            shows only the wall-time line (if applicable).
+    """
+
+    request_count: int = 0
+    input_tokens: int = 0
+    output_tokens: int = 0
+    wall_time_seconds: float = 0.0
+    per_model: dict[str, ModelStats] = field(default_factory=dict)
+
+    def record_request(
+        self,
+        model_name: str,
+        input_toks: int,
+        output_toks: int,
+    ) -> None:
+        """Accumulate token counts for one completed LLM request.
+
+        Updates both the session totals and the per-model breakdown.
+
+        Args:
+            model_name: The model that served this request (used as the
+                per-model key). Pass an empty string to skip the per-model
+                breakdown for this request.
+            input_toks: Input tokens for this request.
+            output_toks: Output tokens for this request.
+        """
+        self.request_count += 1
+        self.input_tokens += input_toks
+        self.output_tokens += output_toks
+        if model_name:
+            entry = self.per_model.setdefault(model_name, ModelStats())
+            entry.request_count += 1
+            entry.input_tokens += input_toks
+            entry.output_tokens += output_toks
+
+    def merge(self, other: SessionStats) -> None:
+        """Merge another `SessionStats` into this one (mutates *self*).
+
+        Used to accumulate per-turn stats into a session-level total.
+
+        Args:
+            other: The stats to fold in.
+        """
+        self.request_count += other.request_count
+        self.input_tokens += other.input_tokens
+        self.output_tokens += other.output_tokens
+        self.wall_time_seconds += other.wall_time_seconds
+        for model, ms in other.per_model.items():
+            entry = self.per_model.setdefault(model, ModelStats())
+            entry.request_count += ms.request_count
+            entry.input_tokens += ms.input_tokens
+            entry.output_tokens += ms.output_tokens
+
+
+def format_token_count(count: int) -> str:
+    """Format a token count into a human-readable short string.
+
+    Args:
+        count: Number of tokens.
+
+    Returns:
+        Formatted string like `'12.5K'`, `'1.2M'`, or `'500'`.
+    """
+    if count >= 1_000_000:  # noqa: PLR2004
+        return f"{count / 1_000_000:.1f}M"
+    if count >= 1000:  # noqa: PLR2004
+        return f"{count / 1000:.1f}K"
+    return str(count)

docagent_cli/_testing_models.py

@@ -0,0 +1,144 @@
+"""Internal chat models used by local integration tests."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from langchain_core.language_models.fake_chat_models import GenericFakeChatModel
+from langchain_core.messages import AIMessage, BaseMessage
+from langchain_core.outputs import ChatGeneration, ChatResult
+from pydantic import Field
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Sequence
+
+    from langchain_core.callbacks import CallbackManagerForLLMRun
+    from langchain_core.language_models import LanguageModelInput
+    from langchain_core.runnables import Runnable
+    from langchain_core.tools import BaseTool
+
+
+class DeterministicIntegrationChatModel(GenericFakeChatModel):
+    """Deterministic chat model for CLI integration tests.
+
+    This subclasses LangChain's `GenericFakeChatModel` so the implementation
+    stays aligned with the core fake-chat-model test surface, while overriding
+    generation to remain prompt-driven and restart-safe for real CLI server
+    integration tests.
+
+    Why the existing `langchain_core` fakes cannot be reused here:
+
+    1. Every core fake (`GenericFakeChatModel`, `FakeListChatModel`,
+        `FakeMessagesListChatModel`) pops from an iterator or cycles an index —
+        the actual prompt is ignored. CLI integration tests start and stop the
+        server process, which resets in-memory state. An iterator-based model
+        either raises `StopIteration` or replays from the beginning after a
+        restart, producing wrong or missing responses. This model derives output
+        solely from the prompt text, so identical input always produces
+        identical output regardless of process lifecycle.
+
+    2. The agent runtime calls `model.bind_tools(schemas)` during
+        initialization. None of the core fakes implement `bind_tools`, so they
+        raise `AttributeError` in any agent-loop context. This model provides a
+        no-op passthrough.
+
+    3. The CLI server reads `model.profile` for capability negotiation (e.g.
+        `tool_calling`, `max_input_tokens`). Core fakes have no such attribute,
+        causing `AttributeError` or silent misconfiguration at runtime.
+
+    Additionally, the compact middleware issues summarization prompts mid-
+    conversation. A list-based model cannot distinguish these from normal user
+    turns without pre-knowledge of exact call ordering, whereas this model
+    detects summary requests by inspecting the prompt content.
+    """
+
+    model: str = "fake"
+    # Required by `GenericFakeChatModel`, but our override does not consume it.
+    messages: object = Field(default_factory=lambda: iter(()))
+    profile: dict[str, Any] | None = Field(
+        default_factory=lambda: {
+            "tool_calling": True,
+            "max_input_tokens": 8000,
+        }
+    )
+
+    def bind_tools(
+        self,
+        tools: Sequence[dict[str, Any] | type | Callable | BaseTool],  # noqa: ARG002
+        *,
+        tool_choice: str | None = None,  # noqa: ARG002
+        **kwargs: Any,  # noqa: ARG002
+    ) -> Runnable[LanguageModelInput, AIMessage]:
+        """Return self so the agent can bind tool schemas during tests."""
+        return self
+
+    def _generate(
+        self,
+        messages: list[BaseMessage],
+        stop: list[str] | None = None,  # noqa: ARG002
+        run_manager: CallbackManagerForLLMRun | None = None,  # noqa: ARG002
+        **kwargs: Any,  # noqa: ARG002
+    ) -> ChatResult:
+        """Produce a deterministic reply derived from the prompt text.
+
+        Returns:
+            A single-message `ChatResult` with deterministic content.
+        """
+        prompt = "\n".join(
+            text
+            for message in messages
+            if (text := self._stringify_message(message)).strip()
+        )
+        if self._looks_like_summary_request(prompt):
+            content = "integration summary"
+        else:
+            excerpt = " ".join(prompt.split()[-18:])
+            if excerpt:
+                content = f"integration reply: {excerpt}"
+            else:
+                content = "integration reply"
+
+        return ChatResult(
+            generations=[ChatGeneration(message=AIMessage(content=content))]
+        )
+
+    @property
+    def _llm_type(self) -> str:
+        """Return the LangChain model type identifier."""
+        return "deterministic-integration"
+
+    @staticmethod
+    def _stringify_message(message: BaseMessage) -> str:
+        """Flatten message content into plain text for deterministic responses.
+
+        Returns:
+            Plain-text content extracted from the message.
+        """
+        content = message.content
+        if isinstance(content, str):
+            return content
+        if isinstance(content, list):
+            parts: list[str] = []
+            for block in content:
+                if isinstance(block, str):
+                    parts.append(block)
+                elif isinstance(block, dict) and block.get("type") == "text":
+                    text = block.get("text")
+                    if isinstance(text, str):
+                        parts.append(text)
+            return " ".join(parts)
+        return str(content)
+
+    @staticmethod
+    def _looks_like_summary_request(prompt: str) -> bool:
+        """Detect the middleware's summary-generation prompt.
+
+        Returns:
+            `True` when the prompt appears to be a summarization request.
+        """
+        lowered = prompt.lower()
+        return (
+            "messages to summarize" in lowered
+            or "condense the following conversation" in lowered
+            or "<summary>" in lowered
+        )

docagent_cli/_version.py

@@ -0,0 +1,17 @@
+"""Version information and lightweight constants for `docagent-cli`."""
+
+__version__ = "0.0.34"  # x-release-please-version
+
+DOCS_URL = "https://docs.langchain.com/oss/python/docagent/cli"
+"""URL for `docagent-cli` documentation."""
+
+PYPI_URL = "https://pypi.org/pypi/docagent-cli/json"
+"""PyPI JSON API endpoint for version checks."""
+
+CHANGELOG_URL = (
+    "https://github.com/langchain-ai/docagent/blob/main/libs/cli/CHANGELOG.md"
+)
+"""URL for the full changelog."""
+
+USER_AGENT = f"docagent-cli/{__version__} update-check"
+"""User-Agent header sent with PyPI requests."""