lithe 0.9.4__py3-none-any.whl

lithe/__init__.py

@@ -0,0 +1,64 @@
+"""lithe — a reusable, storage-free ReAct agent kernel.
+
+Hosts (e.g. a thesis-writing application) plug in their own tools, prompt,
+domain model and persistence. The kernel knows nothing about how runs are
+stored, or even whether they are: it emits events (which a host may sink to a
+DB, a file, or drop) and reads prior turns through an optional memory provider
+(added in a later step).
+
+Layout:
+  - llm        : OpenAI-compatible chat client (retry/backoff/jitter)
+  - events     : Event vocabulary, EventSink, SSE serialization
+  - context    : AgentContext (typed, mapping-compatible)
+  - modes      : AgentMode / ToolCategory + category filtering
+  - actions    : Action model + UndoEngine (pure logic, no storage)
+  - tools      : ToolSpec / ToolResult / ToolRegistry (dispatch + undo wiring)
+"""
+# Single source of truth for the package version; pyproject reads it via
+# [tool.setuptools.dynamic] (statically, without importing this module).
+__version__ = "0.9.4"
+
+from lithe.actions import (  # noqa: F401
+    Action, Reverter, UndoEngine, UndoReport,
+)
+from lithe.context import AgentContext  # noqa: F401
+from lithe.events import Event, EventSink, EventType, to_sse  # noqa: F401
+from lithe.llm import (  # noqa: F401
+    bearer_headers, chat_completion, first_content, strip_think,
+)
+from lithe.memory import (  # noqa: F401
+    DEFAULT_REPLAY_LIMIT, DEFAULT_TOOL_RESULT_CAP, MemoryProvider,
+    recap_text, replay_messages, reasoning_summary_text, run_timeline,
+    truncate_tool_result, window_with_recap,
+)
+from lithe.modes import (  # noqa: F401
+    AgentMode, ToolCategory, categories_for, register_mode,
+)
+from lithe.runtime import (  # noqa: F401
+    DEFAULT_CONTEXT_BUDGET, DEFAULT_REPEAT_CALL_LIMIT, AgentRuntime,
+    LLMConfig, RunStats,
+)
+from lithe.tools import (  # noqa: F401
+    ToolHandler, ToolMiddleware, ToolRegistry, ToolResult, ToolSpec,
+)
+from lithe.transports import (  # noqa: F401
+    ChatCompletionsTransport, LLMTransport, ResponsesTransport, make_transport,
+)
+
+__all__ = [
+    "Action", "AgentContext", "AgentMode", "AgentRuntime",
+    "ChatCompletionsTransport",
+    "DEFAULT_CONTEXT_BUDGET", "DEFAULT_REPEAT_CALL_LIMIT",
+    "DEFAULT_REPLAY_LIMIT", "DEFAULT_TOOL_RESULT_CAP",
+    "Event", "EventSink", "EventType", "LLMConfig", "LLMTransport",
+    "MemoryProvider",
+    "ResponsesTransport",
+    "Reverter", "RunStats",
+    "ToolCategory", "ToolHandler", "ToolMiddleware",
+    "ToolRegistry", "ToolResult", "ToolSpec", "UndoEngine", "UndoReport",
+    "bearer_headers", "categories_for", "chat_completion", "first_content",
+    "make_transport", "register_mode",
+    "recap_text", "replay_messages", "reasoning_summary_text",
+    "run_timeline", "strip_think",
+    "to_sse", "truncate_tool_result", "window_with_recap",
+]

lithe/actions.py

@@ -0,0 +1,105 @@
+"""Reversible mutations and the undo engine.
+
+A write tool records an :class:`Action` (what it changed: kind/target/old/new)
+and registers a :class:`Reverter` that knows how to reverse that kind.
+:class:`UndoEngine` replays the reversals newest-first. None of this touches
+storage: the engine takes a list of actions (from this run's in-memory state,
+or read back by a host from wherever it persisted them), so undo works with or
+without a database.
+
+Reverters may be sync or async (``async def`` / coroutine-returning) — an
+async reverter can roll back through remote APIs; :meth:`UndoEngine.undo`
+awaits whatever the reverter returns.
+"""
+from __future__ import annotations
+
+import inspect
+from dataclasses import dataclass, field
+from typing import Any
+from collections.abc import Callable
+
+from lithe.context import AgentContext
+
+# Action statuses that mean "the mutation is currently in effect" and so should
+# be reverted. Pending/proposed changes that were never applied are skipped.
+_REVERTIBLE = frozenset({"applied", "approved"})
+
+
+@dataclass
+class Action:
+    """One recorded mutation produced by a write tool.
+
+    ``id`` is opaque and host-assigned (e.g. a DB row id); the kernel only uses
+    it for ordering/reporting. ``old_value``/``new_value`` are domain-shaped and
+    interpreted by the matching reverter.
+    """
+    kind: str
+    target: str
+    old_value: Any = None
+    new_value: Any = None
+    status: str = "applied"
+    id: Any = None
+    subagent: str | None = None
+
+
+# A reverter reverses one action kind: ``fn(action, ctx)`` returning None (sync)
+# or an awaitable (async, e.g. rolling back through a remote API). It is
+# best-effort: a partial failure (e.g. a file already gone) must not abort the
+# rest of an undo run, so each reverter owns its own error handling.
+Reverter = Callable[[Action, AgentContext], Any]
+
+
+@dataclass
+class UndoReport:
+    ok: bool = True
+    reverted: int = 0
+    skipped: int = 0
+    errors: list[str] = field(default_factory=list)
+
+
+class UndoEngine:
+    """Revert a list of actions newest-first via registered reverters.
+
+    Pure logic: no storage. Unknown kinds and non-revertible statuses are
+    skipped; a reverter that raises is recorded as an error (not fatal) so the
+    rest of the run still reverts.
+    """
+
+    def __init__(self, reverters: dict[str, Reverter] | None = None):
+        self._reverters: dict[str, Reverter] = dict(reverters or {})
+
+    def register(self, kind: str, reverter: Reverter) -> None:
+        self._reverters[kind] = reverter
+
+    @property
+    def reverters(self) -> dict[str, Reverter]:
+        return dict(self._reverters)
+
+    async def undo(self, actions: list[Action], ctx: AgentContext) -> UndoReport:
+        """Revert *actions* newest-first, awaiting async reverters.
+
+        Pure logic: no storage. Unknown kinds and non-revertible statuses are
+        skipped; a reverter that raises is recorded as an error (not fatal) so
+        the rest of the run still reverts. A reverter's awaitable result is
+        awaited — an error *inside* the awaitable counts the same as a sync
+        raise.
+        """
+        report = UndoReport()
+        for action in reversed(actions):
+            if action.status not in _REVERTIBLE:
+                report.skipped += 1
+                continue
+            fn = self._reverters.get(action.kind)
+            if fn is None:
+                report.skipped += 1
+                continue
+            try:
+                result = fn(action, ctx)
+                if inspect.isawaitable(result):
+                    await result
+            except Exception as exc:  # noqa: BLE001
+                report.errors.append(f"{action.kind} {action.target}: {exc}")
+                report.ok = False
+                continue
+            report.reverted += 1
+        return report

lithe/bundles/__init__.py

@@ -0,0 +1,62 @@
+"""Optional capability bundles for lithe.
+
+These are NOT part of the zero-I/O core engine; they are reusable, host-agnostic
+capabilities a host opts into. The core never imports from here, so
+``import lithe`` alone stays storage- and I/O-free — bundles are pulled in
+only when a host needs them.
+"""
+from lithe.bundles.admin import (  # noqa: F401
+    ToolPackage, check_packages, list_tool_packages_admin, list_tools_admin,
+    package_meta, package_of, tool_categories,
+)
+from lithe.bundles.download import (  # noqa: F401
+    register_download_tools,
+)
+from lithe.bundles.host import (  # noqa: F401
+    AgentHost, DictToolAdapter, StoreSink, assemble_messages, undo_run,
+)
+from lithe.bundles.images import (  # noqa: F401
+    register_image_tools,
+)
+from lithe.bundles.mcp import (  # noqa: F401
+    MCPServerConfig, MCPManager, parse_servers,
+)
+from lithe.bundles.patch import (  # noqa: F401
+    register_apply_patch_tool,
+)
+from lithe.bundles.sandbox import CodeRunner, register_code_tools  # noqa: F401
+from lithe.bundles.skills import (  # noqa: F401
+    PACKAGE_FILE, ROOT_PACKAGE, SKILL_MAIN, RemoteSkillSource, SkillLibrary,
+    SkillPackages, register_skill_tool,
+)
+from lithe.bundles.store import (  # noqa: F401
+    BlobStore, ConversationStore, JsonlRunStore, RunStore, StoredAction,
+    StoredMessage, StoredRun,
+)
+from lithe.bundles.subagents import (  # noqa: F401
+    SubagentEngine, SubagentRoster, SubagentSpec, make_delegate_tool,
+    make_parallel_delegate_tool, register_delegate_tool, register_delegate_tools,
+)
+from lithe.bundles.todos import (  # noqa: F401
+    JsonTodoStore, TodoStore, register_todo_tools, todos_block,
+)
+from lithe.bundles.workspace import Workspace, register_file_tools  # noqa: F401
+
+__all__ = [
+    "AgentHost", "BlobStore", "CodeRunner", "ConversationStore",
+    "DictToolAdapter", "JsonTodoStore", "JsonlRunStore", "MCPManager",
+    "MCPServerConfig", "RunStore",
+    "PACKAGE_FILE", "ROOT_PACKAGE", "SKILL_MAIN", "RemoteSkillSource",
+    "SkillLibrary", "SkillPackages", "StoreSink", "StoredAction",
+    "StoredMessage", "StoredRun",
+    "SubagentEngine", "SubagentRoster", "SubagentSpec", "TodoStore",
+    "ToolPackage", "Workspace",
+    "assemble_messages", "check_packages", "list_tool_packages_admin",
+    "list_tools_admin", "make_delegate_tool", "make_parallel_delegate_tool",
+    "package_meta", "package_of", "parse_servers", "register_apply_patch_tool",
+    "register_code_tools", "register_download_tools",
+    "register_delegate_tool", "register_delegate_tools", "register_file_tools",
+    "register_image_tools", "register_skill_tool", "register_todo_tools",
+    "tool_categories",
+    "todos_block", "undo_run",
+]

lithe/bundles/_textmatch.py

@@ -0,0 +1,115 @@
+"""Shared fuzzy line-matching ladder for the file-editing tools.
+
+The ladder locates a block of expected lines inside a file, trying
+progressively weaker comparisons so a model's near-miss output (a stray
+trailing space, missing indentation, typographic Unicode punctuation) still
+lands instead of failing the edit:
+
+1. exact equality
+2. ignore trailing whitespace (``rstrip``)
+3. ignore leading/trailing whitespace (``strip``)
+4. fold typographic Unicode punctuation to ASCII look-alikes, then compare
+
+Each pass scans the whole candidate range, so a weaker comparator never
+shadows a stronger hit at a later offset. ``apply_patch``'s chunk seeking and
+``edit_file``'s whole-line fallback both build on these primitives.
+"""
+from __future__ import annotations
+
+import operator
+from collections.abc import Callable
+
+
+def normalize_unicode(s: str) -> str:
+    """Fold common typographic punctuation to its ASCII look-alikes."""
+    for src, dst in (("\u2018", "'"), ("\u2019", "'"), ("\u201a", "'"),
+                     ("\u201b", "'"), ("\u201c", '"'), ("\u201d", '"'),
+                     ("\u201e", '"'), ("\u201f", '"'), ("\u2010", "-"),
+                     ("\u2011", "-"), ("\u2012", "-"), ("\u2013", "-"),
+                     ("\u2014", "-"), ("\u2015", "-"), ("\u2026", "..."),
+                     ("\u00a0", " ")):
+        s = s.replace(src, dst)
+    return s
+
+
+# Ordered exact → rstrip → strip → unicode-folded.
+COMPARATORS: tuple[Callable[[str, str], bool], ...] = (
+    operator.eq,
+    lambda a, b: a.rstrip() == b.rstrip(),
+    lambda a, b: a.strip() == b.strip(),
+    lambda a, b: normalize_unicode(a.strip()) == normalize_unicode(b.strip()),
+)
+
+
+def try_match(lines: list[str], pattern: list[str], start: int,
+              compare: Callable[[str, str], bool], eof: bool = False) -> int:
+    """First ladder-position match of *pattern* in *lines* at/after *start*.
+
+    With ``eof``, a tail-anchored match is preferred (for appending at end of
+    file) before the forward scan. Returns ``-1`` when *compare* finds nothing.
+    """
+    n = len(pattern)
+    if eof:
+        from_end = len(lines) - n
+        if from_end >= start and all(
+                compare(lines[from_end + j], pattern[j]) for j in range(n)):
+            return from_end
+    for i in range(start, len(lines) - n + 1):
+        if all(compare(lines[i + j], pattern[j]) for j in range(n)):
+            return i
+    return -1
+
+
+def seek_sequence(lines: list[str], pattern: list[str], start: int = 0,
+                  eof: bool = False) -> int:
+    """Locate *pattern* via the comparator ladder; ``-1`` when nothing hits.
+
+    ``eof`` only *prefers* a tail-anchored hit (it then falls back to a
+    forward scan) — callers that need a hard tail anchor (patch
+    ``*** End of File`` chunks) use :func:`seek_tail` instead."""
+    if not pattern:
+        return -1
+    for compare in COMPARATORS:
+        found = try_match(lines, pattern, start, compare, eof)
+        if found != -1:
+            return found
+    return -1
+
+
+def seek_tail(lines: list[str], pattern: list[str]) -> int:
+    """Hard tail anchor: the ONLY acceptable position is the last
+    ``len(pattern)`` lines of the file, tried through the comparator ladder.
+
+    Returns that position, or ``-1`` when no comparator matches the tail —
+    a weaker forward hit elsewhere in the file is never accepted. This is
+    what ``*** End of File`` patch chunks need: "append at end of file"
+    must fail loudly when the tail doesn't line up, not silently edit a
+    look-alike site earlier in the file."""
+    if not pattern:
+        return -1
+    pos = len(lines) - len(pattern)
+    if pos < 0:
+        return -1
+    for compare in COMPARATORS:
+        if all(compare(lines[pos + j], pattern[j]) for j in range(len(pattern))):
+            return pos
+    return -1
+
+
+def line_span_hits(lines: list[str], pattern: list[str]) -> list[int]:
+    """All non-overlapping match starts, strongest comparator that hits.
+
+    Returns ``[]`` when no comparator matches anywhere. Strength has priority
+    over coverage: hits from a weaker comparator are never merged in.
+    """
+    if not pattern:
+        return []
+    for compare in COMPARATORS:
+        hits: list[int] = []
+        i = 0
+        while (found := try_match(lines, pattern, i, compare)) != -1:
+            hits.append(found)
+            i = found + len(pattern)
+        if hits:
+            return hits
+    return []

lithe/bundles/admin.py

@@ -0,0 +1,133 @@
+"""Admin bundle: tool-management helpers over a :class:`~lithe.tools.ToolRegistry`.
+
+Source for an admin panel: group the registered tools by category and by display
+package, flag enabled/disabled, and check package integrity at startup. Pure over
+the registry + a packages list — **packages carry no enable/disable semantics**
+(tools stay togglable per-name); they are display grouping only, exactly as a
+host's ``TOOL_PACKAGES`` already are.
+
+The package *content* (ids, displays, which tools belong where) is host data
+passed in as :class:`ToolPackage`; only the *mechanism* lives here.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from collections.abc import Collection, Iterable
+
+from lithe.tools import ToolRegistry
+
+_CAT_ORDER = ("read", "write", "meta")
+
+
+@dataclass
+class ToolPackage:
+    """Display-only grouping of tools (no enable/disable semantics)."""
+    id: str
+    display: str
+    description: str = ""
+    tools: list[str] = field(default_factory=list)
+
+
+def _entry(ts) -> dict:
+    return {"name": ts.name, "description": ts.description or "",
+            "parameters": ts.parameters or {"type": "object", "properties": {}}}
+
+
+def tool_categories(registry: ToolRegistry) -> dict[str, list[dict]]:
+    """Group every registered tool by read/write/meta category.
+
+    Each entry is a compact ``{name, description, parameters}`` (no OpenAI
+    envelope) suitable for display. Order within a category is registration order.
+    """
+    cats: dict[str, list[dict]] = {c: [] for c in _CAT_ORDER}
+    for name in registry.names():
+        ts = registry.spec(name)
+        if ts is None:
+            continue
+        cats.setdefault(ts.category.value, []).append(_entry(ts))
+    return cats
+
+
+def package_of(packages: Iterable[ToolPackage], name: str) -> str | None:
+    """Return the package id a tool belongs to, or None if unregistered."""
+    for p in packages:
+        if name in p.tools:
+            return p.id
+    return None
+
+
+def package_meta(packages: Iterable[ToolPackage], pkg_id: str) -> ToolPackage | None:
+    """Return the raw package (id/display/description/tools) or None."""
+    for p in packages:
+        if p.id == pkg_id:
+            return p
+    return None
+
+
+def list_tools_admin(registry: ToolRegistry, *,
+                     disabled: Collection[str] = (),
+                     packages: Iterable[ToolPackage] = ()) -> list[dict]:
+    """Flat tool list for the admin panel, ordered read → write → meta.
+
+    Each entry: ``{name, description, parameters, category, package, enabled}``.
+    ``disabled`` is the per-name set the host turns tools off with; there is no
+    package-level disable.
+    """
+    dis = frozenset(disabled or ())
+    pkgs = tuple(packages or ())
+    buckets: dict[str, list[dict]] = {c: [] for c in _CAT_ORDER}
+    for name in registry.names():
+        ts = registry.spec(name)
+        if ts is None:
+            continue
+        cat = ts.category.value
+        buckets.setdefault(cat, []).append(
+            {**_entry(ts), "category": cat,
+             "package": package_of(pkgs, name), "enabled": name not in dis})
+    return [e for c in _CAT_ORDER for e in buckets.get(c, [])]
+
+
+def list_tool_packages_admin(registry: ToolRegistry,
+                             packages: Iterable[ToolPackage], *,
+                             disabled: Collection[str] = ()) -> list[dict]:
+    """Group every tool by its package for the admin panel (display only).
+
+    One entry per package in the given order; each package carries
+    ``id`` / ``display`` / ``description`` and a ``tools[]`` list where every tool
+    has ``name`` / ``description`` / ``parameters`` / ``category`` / ``enabled``.
+    """
+    dis = frozenset(disabled or ())
+    cat_of = {e["name"]: cat for cat, entries in tool_categories(registry).items()
+              for e in entries}
+    out: list[dict] = []
+    for p in packages:
+        tools = []
+        for name in p.tools:
+            ts = registry.spec(name)
+            entry = _entry(ts) if ts is not None else {
+                "name": name, "description": "", "parameters": {}}
+            tools.append({**entry, "category": cat_of.get(name, ""),
+                          "enabled": name not in dis})
+        out.append({"id": p.id, "display": p.display,
+                    "description": p.description, "tools": tools})
+    return out
+
+
+def check_packages(registry: ToolRegistry,
+                   packages: Iterable[ToolPackage], *,
+                   extra_names: Collection[str] = ()) -> dict:
+    """Integrity check: packages must cover every tool exactly once.
+
+    Returns ``{'ok': bool, 'missing': [...], 'extra': [...]}`` for startup
+    logging. ``missing`` = registry tools (plus ``extra_names``) with no package;
+    ``extra`` = registered names that no longer exist. Non-blocking.
+    """
+    declared = set(registry.names()) | set(extra_names or ())
+    registered = {t for p in packages for t in p.tools}
+    return {"ok": declared == registered,
+            "missing": sorted(declared - registered),
+            "extra": sorted(registered - declared)}
+
+
+__all__ = ["ToolPackage", "check_packages", "list_tool_packages_admin",
+           "list_tools_admin", "package_meta", "package_of", "tool_categories"]