interlens 0.1.0__py3-none-any.whl

interlens/__init__.py

@@ -0,0 +1,85 @@
+from .message import Message
+from .transcript import Transcript
+from .context_item import ContextItem
+from .conversation import Conversation
+from .template import ConversationTemplate
+from .reasoning_visibility import ReasoningVisibility
+from .execution_mode import ExecutionMode
+from .participant import Participant
+from .participant.participants.model_participant import ModelParticipant
+from .participant.participants.qwen import QwenModelParticipant
+from .participant.participants.gemma import GemmaModelParticipant
+from .participant.participants.api_participant import APIParticipant
+from .participant.config import ParticipantConfig, ModelParticipantConfig, APIParticipantConfig
+from .context import ContextPolicy, ErrorPolicy, DropOldestPolicy, SlidingWindowPolicy, SummarizePolicy
+from .hooks import MessageHook, MessageHookResult, HookAction
+from .stop import (
+	StopCondition,
+	AnyStopCondition,
+	TurnStopCondition,
+	TokenStopCondition,
+	ElapsedTimeStopCondition,
+	StopStringCondition,
+)
+from .interp import ActivationCache, CaptureSpec, SteeringSpec, Patch, token_logprobs, decoder_layers
+from .tools import Tool, ToolCall, ToolResult, ToolRegistry, DEFAULT_REGISTRY
+from .runner import (
+	available_devices, ConversationSpec, run_conversations, RunResult, RunReport, rollout,
+	register_analyzer, register_worker_init,
+)
+from .factories import conversation_from_models, conversation_from_ids, AutoModelParticipant, ModelLike
+
+__all__ = [
+	"Message",
+	"Transcript",
+	"ContextItem",
+	"Conversation",
+	"ConversationTemplate",
+	"ReasoningVisibility",
+	"ExecutionMode",
+	"Participant",
+	"ModelParticipant",
+	"QwenModelParticipant",
+	"GemmaModelParticipant",
+	"APIParticipant",
+	"ParticipantConfig",
+	"ModelParticipantConfig",
+	"APIParticipantConfig",
+	"ContextPolicy",
+	"ErrorPolicy",
+	"DropOldestPolicy",
+	"SlidingWindowPolicy",
+	"SummarizePolicy",
+	"MessageHook",
+	"MessageHookResult",
+	"HookAction",
+	"StopCondition",
+	"AnyStopCondition",
+	"TurnStopCondition",
+	"TokenStopCondition",
+	"ElapsedTimeStopCondition",
+	"StopStringCondition",
+	"ActivationCache",
+	"CaptureSpec",
+	"SteeringSpec",
+	"Patch",
+	"token_logprobs",
+	"decoder_layers",
+	"Tool",
+	"ToolCall",
+	"ToolResult",
+	"ToolRegistry",
+	"DEFAULT_REGISTRY",
+	"available_devices",
+	"ConversationSpec",
+	"run_conversations",
+	"RunResult",
+	"RunReport",
+	"rollout",
+	"register_analyzer",
+	"register_worker_init",
+	"conversation_from_models",
+	"conversation_from_ids",
+	"AutoModelParticipant",
+	"ModelLike",
+]

interlens/context/__init__.py

@@ -0,0 +1,23 @@
+from .context_policy import ContextPolicy
+from .error_policy import ErrorPolicy
+from .drop_oldest_policy import DropOldestPolicy
+from .sliding_window_policy import SlidingWindowPolicy
+from .summarize_policy import SummarizePolicy
+
+# Registry for (de)serializing policies by ``kind`` (their class name), so templates round-trip.
+_POLICIES = {c.__name__: c for c in (ErrorPolicy, DropOldestPolicy, SlidingWindowPolicy, SummarizePolicy)}
+
+
+def context_policy_from_dict(data: dict) -> ContextPolicy:
+	params = {k: v for k, v in data.items() if k != "kind"}
+	return _POLICIES[data["kind"]](**params)
+
+
+__all__ = [
+	"ContextPolicy",
+	"ErrorPolicy",
+	"DropOldestPolicy",
+	"SlidingWindowPolicy",
+	"SummarizePolicy",
+	"context_policy_from_dict",
+]

interlens/context/context_policy.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from ..view import ViewSegment
+
+# Origins that must never be trimmed by a context policy: the system block, the scenario/moderator seed, and
+# private briefings all carry essential framing. Only ``turn`` segments (the growing dialogue middle) are
+# eligible for trimming.
+PRESERVED_ORIGINS = ("system", "moderator", "private_context")
+
+
+class ContextPolicy(ABC):
+	"""Decides how to fit a participant's view within its model's context window.
+
+	Crucially, ``fit`` runs on the **typed** ``ViewSegment`` list, *before* the family-specific ``finalize_view``
+	folds/merges anything. Operating pre-finalize means the policy can reliably preserve the system block and
+	moderator seed (their ``origin`` is still intact) and trim only ``turn`` segments, instead of trying to
+	reverse-engineer meaning out of already-folded text.
+	"""
+
+	@abstractmethod
+	def fit(self, segments: list[ViewSegment], tokenizer, limit: int | None) -> list[ViewSegment]:
+		...
+
+	def to_dict(self) -> dict:
+		"""Serialize as ``{"kind": ..., **params}``. Subclasses with parameters extend the params; the default
+		covers parameterless policies."""
+		return {"kind": type(self).__name__}
+
+	@staticmethod
+	def _limit(tokenizer, limit: int | None) -> int:
+		"""Resolve the effective token budget; falls back to the tokenizer's declared max length."""
+		if limit is not None:
+			return limit
+		return int(getattr(tokenizer, "model_max_length", 1_000_000_000) or 1_000_000_000)
+
+	@staticmethod
+	def _seg_tokens(segment: ViewSegment, tokenizer) -> int:
+		"""Approximate token cost of a segment's content (ignores per-template wrapper tokens — close enough for
+		fitting decisions)."""
+		return len(tokenizer(segment.content, add_special_tokens=False).input_ids)
+
+	@classmethod
+	def _total_tokens(cls, segments: list[ViewSegment], tokenizer) -> int:
+		return sum(cls._seg_tokens(s, tokenizer) for s in segments)

interlens/context/drop_oldest_policy.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from .context_policy import ContextPolicy, PRESERVED_ORIGINS
+from ..view import ViewSegment
+
+
+class DropOldestPolicy(ContextPolicy):
+	"""Drop the oldest ``turn`` segments (preserving system/moderator/private_context) until the view fits."""
+
+	def fit(self, segments: list[ViewSegment], tokenizer, limit: int | None) -> list[ViewSegment]:
+		budget = self._limit(tokenizer, limit)
+		if self._total_tokens(segments, tokenizer) <= budget:
+			return segments
+
+		# Indices of trimmable turns, oldest first.
+		turn_indices = [i for i, s in enumerate(segments) if s.origin == "turn"]
+		dropped: set[int] = set()
+		total = self._total_tokens(segments, tokenizer)
+		for i in turn_indices:
+			if total <= budget:
+				break
+			total -= self._seg_tokens(segments[i], tokenizer)
+			dropped.add(i)
+
+		kept = [s for i, s in enumerate(segments) if i not in dropped]
+		# If preserved framing alone still overflows, there's nothing left to trim — surface it rather than lie.
+		if self._total_tokens(kept, tokenizer) > budget:
+			raise ValueError(
+				f"cannot fit view within {budget} tokens even after dropping all turns "
+				f"(preserved {PRESERVED_ORIGINS} framing is too large)"
+			)
+		return kept

interlens/context/error_policy.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from .context_policy import ContextPolicy
+from ..view import ViewSegment
+
+
+class ErrorPolicy(ContextPolicy):
+	"""The safe default: raise if the view exceeds the context window rather than silently dropping content.
+
+	Silent truncation reads as "everything fit" when it didn't, which is exactly the kind of quiet data loss this
+	harness avoids. Callers who want trimming opt into ``DropOldestPolicy``/``SlidingWindowPolicy`` explicitly.
+	"""
+
+	def fit(self, segments: list[ViewSegment], tokenizer, limit: int | None) -> list[ViewSegment]:
+		budget = self._limit(tokenizer, limit)
+		total = self._total_tokens(segments, tokenizer)
+		if total > budget:
+			raise ValueError(
+				f"view ~{total} tokens exceeds context limit {budget}; choose a DropOldest/SlidingWindow "
+				f"context policy or shorten the scenario"
+			)
+		return segments

interlens/context/sliding_window_policy.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from .context_policy import ContextPolicy
+from ..view import ViewSegment
+
+
+class SlidingWindowPolicy(ContextPolicy):
+	"""Keep the preserved framing plus the most recent ``keep_last`` turns; drop older turns.
+
+	``keep_system=True`` (the default) preserves the system/moderator/private_context framing regardless of the
+	window; set it False to also let framing fall outside the window (rarely wanted). Unlike ``DropOldestPolicy``
+	this is a fixed-size window rather than a fit-to-budget trim, so it's predictable turn-to-turn.
+	"""
+
+	def __init__(self, keep_last: int, keep_system: bool = True):
+		self.keep_last = keep_last
+		self.keep_system = keep_system
+
+	def to_dict(self) -> dict:
+		return {"kind": "SlidingWindowPolicy", "keep_last": self.keep_last, "keep_system": self.keep_system}
+
+	def fit(self, segments: list[ViewSegment], tokenizer, limit: int | None) -> list[ViewSegment]:
+		turn_indices = [i for i, s in enumerate(segments) if s.origin == "turn"]
+		keep_turns = set(turn_indices[-self.keep_last:]) if self.keep_last > 0 else set()
+
+		kept = []
+		for i, s in enumerate(segments):
+			if s.origin == "turn":
+				if i in keep_turns:
+					kept.append(s)
+			elif self.keep_system:
+				kept.append(s)
+		return kept

interlens/context/summarize_policy.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from .context_policy import ContextPolicy, PRESERVED_ORIGINS
+from ..view import ViewSegment
+
+
+class SummarizePolicy(ContextPolicy):
+	"""Compress older turns into a single summary segment instead of dropping them outright (the heaviest
+	policy).
+
+	Keeps the preserved framing (system / moderator / private_context) and the most recent ``keep_last`` turns
+	verbatim, and replaces the older middle turns with one summary segment produced by ``summarizer`` — a
+	callable ``list[str] -> str`` over the dropped turns' contents. With no summarizer it inserts a neutral
+	placeholder, so it degrades to a labelled drop rather than silently losing content.
+
+	``summarizer`` is a live callable and so is not serialized; a loaded template gets ``summarizer=None`` and
+	the caller re-injects one if needed.
+	"""
+
+	def __init__(self, keep_last: int = 4, summarizer=None):
+		self.keep_last = keep_last
+		self.summarizer = summarizer
+
+	def to_dict(self) -> dict:
+		return {"kind": "SummarizePolicy", "keep_last": self.keep_last}
+
+	def _summarize(self, texts: list[str]) -> str:
+		if self.summarizer is not None:
+			return self.summarizer(texts)
+		return f"[{len(texts)} earlier turns omitted]"
+
+	def fit(self, segments: list[ViewSegment], tokenizer, limit: int | None) -> list[ViewSegment]:
+		budget = self._limit(tokenizer, limit)
+		if self._total_tokens(segments, tokenizer) <= budget:
+			return segments
+
+		preserved = [s for s in segments if s.origin in PRESERVED_ORIGINS]
+		turns = [s for s in segments if s.origin == "turn"]
+		older = turns[: -self.keep_last] if self.keep_last > 0 else turns
+		recent = turns[-self.keep_last:] if self.keep_last > 0 else []
+		if not older:
+			return segments  # nothing old enough to summarize; leave as-is
+
+		summary = ViewSegment(role="user", origin="moderator",
+		                      content="[Summary of earlier conversation]\n" + self._summarize([s.content for s in older]))
+		# Preserve original ordering: framing first, then the summary standing in for older turns, then recent.
+		return preserved + [summary] + recent

interlens/context_item.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .participant.role import Role
+
+
+@dataclass
+class ContextItem:
+	"""A single item of *private* asymmetric knowledge given to one participant (a briefing, a document, a fact).
+
+	Deliberately distinct from ``Message``: a briefing is not a dialogue turn — it has no turn index and its
+	``author`` is nominal — so overloading ``Message`` would give it misleading turn/authorship semantics.
+
+	Role semantics are pinned rather than role-swapped: a briefing renders by default as **user-provided
+	context** (``role_hint=USER``) — the participant reads it as information handed to it, not as its own prior
+	speech — with ``SYSTEM`` available for standing private instructions. Private context is injected only into
+	the owning participant's view and never enters the shared transcript.
+	"""
+
+	content: str
+	role_hint: Role = "user"
+	author: str = "moderator"