induscode 0.1.0__py3-none-any.whl

induscode/window_budget/condenser.py

@@ -0,0 +1,170 @@
+"""Window-budget — the condenser factory (the conductor-consumable seam;
+port of TS ``src/window-budget/condenser.ts``).
+
+:func:`create_condenser` ties the three pure pieces together into a single
+function the conductor can drop into its auto-compaction hook:
+
+1. **Gate**   — :func:`~.budget.is_over_budget` asks "is this transcript
+   large enough to condense?" against the bound model's window and the
+   :class:`~.contract.BudgetPolicy`.
+2. **Slice**  — :func:`~.budget.plan_slice` splits the transcript into a
+   ``dropped`` head (older turns to fold away) and a verbatim ``kept`` tail,
+   never cutting between a ``toolCall`` and its ``toolResult``.
+3. **Condense** — :func:`~.summarize.summarize` turns the dropped head into
+   one synthetic digest message (scope ``"session"``), via the injectable
+   model completer.
+
+The returned value is a :data:`~.contract.Condenser` — structurally the
+conductor ``CondenseFn``
+(``(messages) -> list[AgentMessage] | Awaitable[list[AgentMessage]]``):
+
+- When over budget it returns ``[summary_message, *kept]`` (a strictly
+  smaller transcript: one digest in place of the dropped prefix, plus the
+  recent tail).
+- Otherwise it returns the input list unchanged — the SAME list object (the
+  no-op identity the conductor expects when nothing needs doing; tests pin
+  ``is``-identity on this path).
+
+It is **network-free-testable**: with no ``model`` bound the gate cannot
+measure a window, so the condenser is an identity transform; inject a
+:class:`~.contract.CompleteFn` stub (and a ``model``) to drive the summary
+path with no real API call.
+
+Branch-archival is *not* a second engine — :func:`condense_scope` forwards to
+the shared :func:`~.summarize.summarize` core pinned to scope ``"branch"``.
+:func:`condense` is the matching session-scope entrypoint. Both are
+re-exported here so callers can summarize a slice directly without building a
+full ``Condenser``.
+
+TWO COMPACTION ENGINES — KEEP THEM DISTINCT (analysis 05 §1 / risk-3)
+---------------------------------------------------------------------
+This module is the app's **conductor ``CondenseFn``** seam. The framework
+ships its own compactor, :mod:`indusagi.runtime.memory`
+(``should_compact`` / ``find_cut_point`` / ``summarize`` / ``compact``), but
+it is a DIFFERENT engine and is never wired into the conductor:
+
+============  =============================================  ==========================================
+              window_budget (this module)                    indusagi.runtime.memory (framework)
+============  =============================================  ==========================================
+message type  ``indusagi.ai`` ``AgentMessage`` (+ agent      ``llmgateway.contract.Turn``
+              custom messages)
+keep_recent   **tokens** (default 6000)                      **turns** (default 8)
+trigger       ratio **0.75** of the window                   ratio **0.8**
+completer     ``indusagi.ai.complete_simple`` (injectable)   ``ModelInvoker``
+digest head   ``[session digest …]`` / ``[branch digest …]``  ``[condensed earlier context]``
+============  =============================================  ==========================================
+
+Do not substitute one for the other: the policies, prompts, and digest
+headers differ, and tests pin this module's headers.
+"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+
+from .budget import is_over_budget, plan_slice
+from .contract import (
+    AgentMessage,
+    BudgetPolicy,
+    CompleteFn,
+    Condenser,
+    CondenserDeps,
+    Model,
+    Summary,
+)
+from .summarize import SummarizeDeps, condense_scope, summarize
+
+__all__ = [
+    "DEFAULT_POLICY",
+    "condense",
+    "condense_scope",
+    "create_condenser",
+]
+
+
+# ---------------------------------------------------------------------------
+# Default policy (config-sourced thresholds)
+# ---------------------------------------------------------------------------
+
+#: The fallback :class:`~.contract.BudgetPolicy` when the caller supplies
+#: none. These are ordinary configuration defaults — a window-relative ratio
+#: plus a token tail — computed from the model's own context window rather
+#: than fixed magic numbers.
+#:
+#: - ``trigger_ratio`` 0.75 — condense once ~three-quarters of the window is used.
+#: - ``keep_recent``   6000 — keep roughly the last 6k tokens of turns verbatim.
+#: - ``reserve_tokens`` 2048 — carve a little headroom off the window first.
+DEFAULT_POLICY = BudgetPolicy(
+    trigger_ratio=0.75,
+    keep_recent=6000,
+    reserve_tokens=2048,
+)
+
+
+# ---------------------------------------------------------------------------
+# Factory
+# ---------------------------------------------------------------------------
+
+
+def create_condenser(deps: CondenserDeps | None = None) -> Condenser:
+    """Build a :data:`~.contract.Condenser` from a
+    :class:`~.contract.CondenserDeps` bundle. The result plugs straight into
+    the conductor's ``CondenseFn`` seam.
+
+    Behavior of the returned condenser, given a transcript ``messages``:
+
+    - If no ``model`` is bound (so the window is unknown), or the transcript
+      is **not** over budget, return ``messages`` **unchanged** (the same
+      list object).
+    - Otherwise ``plan_slice`` the transcript; if there is nothing to drop
+      (``cut == 0``) return it unchanged; else ``summarize`` the dropped head
+      (scope ``"session"``) and return ``[summary.message, *plan.kept]``.
+
+    All dependencies are optional, so ``create_condenser()`` yields a
+    working, network-free condenser (a no-op until a model and policy are
+    supplied).
+    """
+    if deps is None:
+        deps = CondenserDeps()
+    policy: BudgetPolicy = deps.policy if deps.policy is not None else DEFAULT_POLICY
+    model: Model | None = deps.model
+    complete: CompleteFn | None = deps.complete
+
+    async def condenser(messages: list[AgentMessage]) -> list[AgentMessage]:
+        # No model → no window to measure against → nothing to do (identity).
+        if model is None:
+            return messages
+
+        # Under budget → leave the transcript exactly as-is (conductor no-op).
+        if not is_over_budget(messages, model, policy):
+            return messages
+
+        # Decide where to cut (forward prefix-sum + binary search, tool-pair safe).
+        plan = plan_slice(messages, policy)
+        if plan.cut == 0 or not plan.dropped:
+            # Nothing condensable (everything is within the recent tail) → identity.
+            return messages
+
+        # Fold the dropped head into one synthetic digest, then splice it
+        # ahead of the verbatim recent tail.
+        summary = await condense(plan.dropped, SummarizeDeps(complete=complete, model=model))
+        return [summary.message, *plan.kept]
+
+    return condenser
+
+
+# ---------------------------------------------------------------------------
+# Direct summarization entrypoints (session + branch)
+# ---------------------------------------------------------------------------
+
+
+async def condense(
+    messages: list[AgentMessage],
+    deps: SummarizeDeps | None = None,
+) -> Summary:
+    """Session-scope summarization: fold a slice of dropped messages into one
+    digest for the active session. A thin wrapper over the shared
+    :func:`~.summarize.summarize` core pinned to scope ``"session"`` (the
+    default), so callers don't pass the flag."""
+    base = deps if deps is not None else SummarizeDeps()
+    return await summarize(messages, replace(base, scope="session"))

induscode/window_budget/contract.py

@@ -0,0 +1,329 @@
+"""Window-budget contract — the FROZEN type surface of the context-window
+budgeting subsystem (port of TS ``src/window-budget/contract.ts``).
+
+A long-running coding session accrues messages — user turns, assistant turns,
+tool calls and their results — until the transcript approaches the model's
+context window. This subsystem keeps the session usable by *condensing* older
+history into a single structured summary message while keeping a verbatim
+tail of the most-recent turns. It answers three questions:
+
+1. **Budget**  — *when* are we over budget? A :class:`BudgetPolicy` carries
+   config-sourced thresholds (no magic literals);
+   :func:`~induscode.window_budget.budget.gate.is_over_budget` decides from a
+   real :class:`TokenEstimate`.
+2. **Slice**   — *where* do we cut?
+   :func:`~induscode.window_budget.budget.slice.plan_slice` computes a
+   :class:`CondensePlan` via a forward prefix-sum + binary search over a
+   cumulative-token array, never splitting a tool_call from its tool_result.
+3. **Condense** — *how* do we compress the dropped portion? A
+   :data:`Condenser` flattens the dropped messages, asks an injectable model
+   completer for a structured :class:`Summary`, and returns the rebuilt
+   transcript (summary + kept tail).
+
+This module declares *only* shapes plus the function-type seams — no behavior,
+no I/O, no prompt strings. Every later window-budget module (the meter, the
+slice planner, the condenser, the branch archivist, the prompt templates, and
+the public barrel) is written against the names declared here.
+
+Design stance:
+
+- Thresholds are **configuration, not constants**. :class:`BudgetPolicy`
+  fields are supplied by the caller; this module bakes in no fixed token
+  fingerprints. Defaults, if any, live in the implementation and are computed
+  relative to the model's own context window.
+- Branch-summarization is **not a separate engine**. It collapses into the
+  condenser behind a :data:`CondenseScope` flag (``"session" | "branch"``),
+  so there is one prompt-assembly path, one token estimator, one slicer.
+- The model completer is **injectable** (:class:`CompleteFn`, default the
+  framework's :func:`indusagi.ai.complete_simple`) so the condenser runs in
+  tests with no network.
+- The produced condenser is **conductor-consumable**: a :data:`Condenser` is
+  structurally the conductor ``CondenseFn``
+  (``(messages) -> list[AgentMessage] | Awaitable[list[AgentMessage]]``), so a
+  :class:`CondenserDeps`-built condenser plugs straight into the conductor's
+  auto-compaction seam.
+
+Port notes (Python framework deltas vs the TS source)
+-----------------------------------------------------
+- **``AgentMessage`` relocated AND narrower.** In TS it came from
+  ``indusagi/agent`` and the declaration-merged union already covered the
+  agent's custom session messages. In the Python framework the alias lives at
+  :data:`indusagi.ai.AgentMessage` and equals the bare LLM ``Message`` union
+  (``UserMessage | AssistantMessage | ToolResultMessage``) only. The agent's
+  custom message kinds — :class:`indusagi.agent.BashExecutionMessage`,
+  :class:`indusagi.agent.CustomMessage`,
+  :class:`indusagi.agent.BranchSummaryMessage`,
+  :class:`indusagi.agent.CompactionSummaryMessage` — are separate dataclasses
+  in :mod:`indusagi.agent`. This contract therefore **explicitly unions them**
+  into the app-level :data:`AgentMessage` alias, and every role-probing
+  consumer (the estimator, the slicer, the flattener) handles those roles via
+  ``getattr``/``isinstance`` duck probing, never dict access — messages are
+  frozen dataclasses here, not JSON records.
+- ``Model`` drops the TS ``<TApi>`` generic — :class:`indusagi.ai.Model`
+  carries ``api`` as a plain string tag.
+- The Web ``AbortSignal`` becomes the framework's ``CancelToken`` (forwarded
+  opaquely into ``SimpleStreamOptions.signal``; not re-typed here because the
+  framework keeps it internal).
+
+Framework anchors (all from the ``indusagi`` package — the sibling rebuilt
+framework this app targets):
+
+- ``AgentMessage`` (base union), ``Model``, ``Usage``, ``complete_simple``
+  (and its ``Api`` / ``AssistantMessage`` / ``Context`` /
+  ``SimpleStreamOptions`` / ``StreamLogger`` shapes) ← ``indusagi.ai``
+- ``BashExecutionMessage`` / ``CustomMessage`` / ``BranchSummaryMessage`` /
+  ``CompactionSummaryMessage`` ← ``indusagi.agent``
+
+This module never re-declares these; it composes them.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Literal, Protocol, TypeAlias
+
+from indusagi.agent import (
+    BashExecutionMessage,
+    BranchSummaryMessage,
+    CompactionSummaryMessage,
+    CustomMessage,
+)
+from indusagi.ai import (
+    AgentMessage as AiAgentMessage,
+)
+from indusagi.ai import (
+    Api,
+    AssistantMessage,
+    Context,
+    Model,
+    SimpleStreamOptions,
+    StreamLogger,
+    Usage,
+)
+
+__all__ = [
+    "AgentMessage",
+    "Api",
+    "BudgetPolicy",
+    "CompleteFn",
+    "CondensePlan",
+    "CondenseScope",
+    "Condenser",
+    "CondenserDeps",
+    "Model",
+    "Summary",
+    "TokenEstimate",
+    "Usage",
+]
+
+
+# ---------------------------------------------------------------------------
+# Message vocabulary (re-exported framework vocabulary, widened)
+# ---------------------------------------------------------------------------
+
+#: The transcript message union this subsystem operates on. The framework's
+#: :data:`indusagi.ai.AgentMessage` covers only the LLM ``Message`` trio, so —
+#: unlike the TS source, where declaration merging widened it implicitly —
+#: the agent's four custom session-message dataclasses are unioned in
+#: EXPLICITLY here (analysis 05 risk-2). A silent omission would mis-estimate
+#: tokens and skip those turns in digests.
+AgentMessage: TypeAlias = (
+    AiAgentMessage
+    | BashExecutionMessage
+    | CustomMessage
+    | BranchSummaryMessage
+    | CompactionSummaryMessage
+)
+
+
+# ---------------------------------------------------------------------------
+# Policy
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class BudgetPolicy:
+    """The config-sourced thresholds that govern when and how the transcript
+    is condensed. Every field is a *number the caller supplies* — there are no
+    magic token literals baked into this contract. An implementation may
+    provide defaults, but they are configuration values, not protected
+    constants, and deliberately differ from the legacy fingerprints.
+    """
+
+    # Fraction of the model's `contextWindow` at which condensing is
+    # triggered, in (0, 1]. The meter is "over budget" once the estimated
+    # context tokens cross `contextWindow * trigger_ratio`. Expressing the
+    # trigger as a ratio (rather than an absolute reserve) keeps it
+    # window-relative and free of baked-in token counts.
+    trigger_ratio: float
+
+    # How much of the recent transcript to keep verbatim, measured in
+    # estimated tokens. The slice planner preserves a tail of at least this
+    # many tokens (snapped to a legal boundary) and condenses everything
+    # before it.
+    keep_recent: int
+
+    # Optional token headroom to subtract from the window before the trigger
+    # is evaluated — a safety margin so a condense fires *before* the very
+    # next turn would overflow. When omitted, only `trigger_ratio` governs
+    # the trigger.
+    reserve_tokens: int | None = None
+
+
+# ---------------------------------------------------------------------------
+# Token measurement
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class TokenEstimate:
+    """The outcome of measuring a transcript against a model's window.
+
+    Anchors on the provider's authoritative ``usage`` count when available
+    (``anchored=True``) and falls back to a rough char/role estimate
+    otherwise; either way ``context_tokens`` is the figure ``is_over_budget``
+    compares to ``context_window``.
+    """
+
+    # Best estimate of tokens currently occupying the context window.
+    context_tokens: int
+
+    # The model's total context window, in tokens (`Model.contextWindow`).
+    context_window: int
+
+    # True when `context_tokens` is anchored on a real provider `usage`
+    # figure (only trailing, post-usage messages are estimated); False when
+    # the whole figure is a heuristic estimate.
+    anchored: bool
+
+
+# ---------------------------------------------------------------------------
+# Slice plan
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CondensePlan:
+    """The pre-computed result of ``plan_slice``: the chosen cut index and the
+    resulting partition of the transcript.
+
+    The cut is found by a *forward* prefix-sum + binary search: build a
+    cumulative estimated-token array over the messages, binary-search for the
+    boundary index nearest ``total - keep_recent``, then nudge to the closest
+    *legal* boundary — never landing between a ``toolCall`` and its
+    ``toolResult``.
+
+    Invariants:
+
+    - ``len(kept) + len(dropped) == len(messages)``
+    - ``dropped`` is the prefix ``messages[0:cut]`` (the older slice to condense)
+    - ``kept``    is the suffix ``messages[cut:]`` (the verbatim recent tail)
+    - ``cut`` is ``0`` when nothing is condensable (everything kept).
+    """
+
+    # Index of the legal cut boundary: dropped = messages[:cut].
+    cut: int
+
+    # The verbatim recent tail preserved as-is (messages[cut:]).
+    kept: list[AgentMessage]
+
+    # The older slice to be folded into a `Summary` (messages[:cut]).
+    dropped: list[AgentMessage]
+
+
+# ---------------------------------------------------------------------------
+# Condense scope
+# ---------------------------------------------------------------------------
+
+#: Which kind of condensing run this is — the flag that collapses
+#: branch-summarization into the single condenser path:
+#:
+#: - ``"session"`` — condense the *active* transcript in place (the trigger /
+#:   overflow path); keeps a recent tail, summarizes the head.
+#: - ``"branch"``  — archive an *abandoned* branch into one summary message so
+#:   its context isn't lost on tree navigation; no verbatim tail is retained.
+CondenseScope: TypeAlias = Literal["session", "branch"]
+
+
+# ---------------------------------------------------------------------------
+# Summary
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Summary:
+    """The structured result of summarizing a slice of dropped messages: a
+    single synthetic :data:`AgentMessage` that stands in for the messages it
+    covers.
+    """
+
+    # The synthetic summary message to splice into the rebuilt transcript.
+    message: AgentMessage
+
+    # How many source messages this summary replaces.
+    covered_count: int
+
+
+# ---------------------------------------------------------------------------
+# Model completer seam (injectable, default = framework complete_simple)
+# ---------------------------------------------------------------------------
+
+
+class CompleteFn(Protocol):
+    """The injectable model-completion function. Structurally identical to
+    the framework's :func:`indusagi.ai.complete_simple`
+    (``(model, context, options=None, logger=None) -> AssistantMessage``), so
+    the real ``complete_simple`` is the drop-in default and a test can pass a
+    no-network stub of the same shape. The condenser uses this single call to
+    turn flattened transcript text into a :class:`Summary`.
+    """
+
+    def __call__(
+        self,
+        model: Model,
+        context: Context,
+        options: SimpleStreamOptions | None = None,
+        logger: StreamLogger | None = None,
+    ) -> Awaitable[AssistantMessage]: ...
+
+
+# ---------------------------------------------------------------------------
+# Condenser factory seam
+# ---------------------------------------------------------------------------
+
+#: A condenser: takes the active branch's messages and returns the rebuilt
+#: transcript (condensed head + verbatim tail, or the input unchanged when
+#: there is nothing to do).
+#:
+#: This type is **structurally compatible with the conductor's
+#: ``CondenseFn``** (``(messages) -> list[AgentMessage] |
+#: Awaitable[list[AgentMessage]]``), so the result of the condenser factory
+#: plugs directly into the conductor's auto-compaction seam with no adapter.
+Condenser: TypeAlias = Callable[
+    [list[AgentMessage]],
+    "list[AgentMessage] | Awaitable[list[AgentMessage]]",
+]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CondenserDeps:
+    """Dependencies for building a :data:`Condenser`. All fields are optional
+    so a bare ``create_condenser()`` yields a working, network-free-testable
+    condenser:
+
+    - ``complete`` defaults to the framework's ``complete_simple``.
+    - ``policy`` defaults to the implementation's config-sourced thresholds.
+    - ``model`` is the summarization model; when omitted the condenser falls
+      back to a no-op (return input unchanged) rather than guess a model.
+    """
+
+    # The injectable model completer (default: framework complete_simple).
+    # Inject a stub of `CompleteFn` shape to run the condenser w/o network.
+    complete: CompleteFn | None = None
+
+    # The model used to write the summary. When omitted, condensing is a no-op.
+    model: Model | None = None
+
+    # The config-sourced budget thresholds (default: implementation defaults).
+    policy: BudgetPolicy | None = None

induscode/window_budget/summarize/__init__.py

@@ -0,0 +1,33 @@
+"""Window-budget — summarization subsystem barrel (port of TS
+``src/window-budget/summarize/index.ts``).
+
+Model-driven condensing of the dropped transcript prefix into one synthetic
+summary message, with re-authored prompts (new section names + a new tag
+vocabulary). Branch-archival folds in behind the scope flag —
+:func:`condense_scope` is the branch entrypoint over the same
+:func:`summarize` core.
+"""
+
+from ..contract import (
+    AgentMessage,
+    CompleteFn,
+    CondenseScope,
+    Model,
+    Summary,
+)
+from .condense import SummarizeDeps, condense_scope, summarize
+from .prompt import CONDENSER_BRIEF, build_summary_prompt, flatten_transcript
+
+__all__ = [
+    "AgentMessage",
+    "CONDENSER_BRIEF",
+    "CompleteFn",
+    "CondenseScope",
+    "Model",
+    "SummarizeDeps",
+    "Summary",
+    "build_summary_prompt",
+    "condense_scope",
+    "flatten_transcript",
+    "summarize",
+]