geny-executor 2.63.0__tar.gz → 2.64.0__tar.gz

{geny_executor-2.63.0 → geny_executor-2.64.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: geny-executor
-Version: 2.63.0
+Version: 2.64.0
 Summary: Harness-engineered agent pipeline library with 21-stage dual-abstraction architecture, built on the Anthropic API
 Project-URL: Homepage, https://github.com/CocoRoF/geny-executor
 Project-URL: Repository, https://github.com/CocoRoF/geny-executor
@@ -10,7 +10,7 @@ Author-email: CocoRoF <cocorof@users.noreply.github.com>
 License-Expression: Apache-2.0
 License-File: LICENSE
 License-File: NOTICE
-Keywords: agent,ai,anthropic,claude,harness,llm,mcp>=1.0.0,<2,orchestration,pipeline
+Keywords: agent,ai,anthropic,claude,harness,llm,mcp>=1.0.0,<3,orchestration,pipeline
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Framework :: AsyncIO
 Classifier: Intended Audience :: Developers
@@ -29,7 +29,7 @@ Requires-Dist: ddgs>=9.11
 Requires-Dist: google-genai>=1.0.0
 Requires-Dist: httpx>=0.27
 Requires-Dist: jsonschema>=4.0
-Requires-Dist: mcp<2,>=1.0.0
+Requires-Dist: mcp<3,>=1.0.0
 Requires-Dist: numpy>=1.24
 Requires-Dist: openai>=1.50.0
 Requires-Dist: pgvector>=0.3.0

{geny_executor-2.63.0 → geny_executor-2.64.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "geny-executor"
-version = "2.63.0"
+version = "2.64.0"
 description = "Harness-engineered agent pipeline library with 21-stage dual-abstraction architecture, built on the Anthropic API"
 readme = "README.md"
 license = "Apache-2.0"
@@ -20,7 +20,7 @@ keywords = [
     "harness",
     "ai",
     "llm",
-    "mcp>=1.0.0,<2",
+    "mcp>=1.0.0,<3",
     "orchestration",
 ]
 classifiers = [
@@ -39,7 +39,7 @@ classifiers = [
 dependencies = [
     # Core runtime
     "anthropic>=0.52.0",
-    "mcp>=1.0.0,<2",
+    "mcp>=1.0.0,<3",
     "pydantic>=2.0",
     "jsonschema>=4.0",
     # httpx — declared explicitly because WebFetch imports it directly

geny_executor-2.64.0/src/geny_executor/audio/__init__.py

@@ -0,0 +1,29 @@
+"""Audio capability layer — model-gated media bridges.
+
+The model's content vocabulary is text/image/document only: there is no
+audio block. This package therefore holds the bridges that turn
+workspace audio into something the model can consume — starting with
+STT (:mod:`geny_executor.audio.stt`). The tool surface lives in
+``tools/built_in/audio_tools.py`` and is hidden behind
+``feature:stt_enabled`` until the host wires a provider.
+"""
+
+from geny_executor.audio.stt import (  # noqa: F401
+    STTError,
+    STTProvider,
+    STTResult,
+    STTSegment,
+    create_stt_client,
+    register_stt_provider,
+    unregister_stt_provider,
+)
+
+__all__ = [
+    "STTError",
+    "STTProvider",
+    "STTResult",
+    "STTSegment",
+    "create_stt_client",
+    "register_stt_provider",
+    "unregister_stt_provider",
+]

geny_executor-2.64.0/src/geny_executor/audio/stt/__init__.py

@@ -0,0 +1,25 @@
+"""Speech-to-text: provider Protocol + factory/registry + built-ins."""
+
+from geny_executor.audio.stt.provider import (  # noqa: F401
+    STT_ERROR_CATEGORIES,
+    STTError,
+    STTProvider,
+    STTResult,
+    STTSegment,
+)
+from geny_executor.audio.stt.registry import (  # noqa: F401
+    create_stt_client,
+    register_stt_provider,
+    unregister_stt_provider,
+)
+
+__all__ = [
+    "STT_ERROR_CATEGORIES",
+    "STTError",
+    "STTProvider",
+    "STTResult",
+    "STTSegment",
+    "create_stt_client",
+    "register_stt_provider",
+    "unregister_stt_provider",
+]

geny_executor-2.64.0/src/geny_executor/audio/stt/openai_compatible.py

@@ -0,0 +1,141 @@
+"""Built-in STT provider #1 — the OpenAI-compatible transcription API.
+
+``POST {api_url}/v1/audio/transcriptions`` (multipart) is the de-facto
+standard surface: OpenAI itself, vLLM-served Whisper (Geny's
+``whisper-stt`` container), Groq, faster-whisper servers … one client
+covers them all, which is why this is the only transport the executor
+ships. Anything more exotic plugs in via ``register_stt_provider``.
+
+Uses ``httpx`` (already a core dependency) — no new extras.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+import httpx
+
+from geny_executor.audio.stt.provider import (
+    STTError,
+    STTResult,
+    STTSegment,
+)
+
+_DEFAULT_TIMEOUT = 300.0  # long files legitimately take minutes
+
+
+def _categorize(status: int) -> str:
+    if status in (401, 403):
+        return "auth"
+    if status in (413, 429):
+        return "quota"
+    if status >= 500:
+        return "transient"
+    if status >= 400:
+        return "invalid"
+    return "unknown"
+
+
+class OpenAICompatibleSTT:
+    """STTProvider over the OpenAI-compatible transcription endpoint."""
+
+    def __init__(
+        self,
+        *,
+        api_url: str,
+        model: str,
+        api_key: Optional[str] = None,
+        timeout: float = _DEFAULT_TIMEOUT,
+        temperature: float = 0.0,
+        extra_headers: Optional[Dict[str, str]] = None,
+    ) -> None:
+        if not api_url:
+            raise ValueError("api_url is required")
+        if not model:
+            raise ValueError("model is required")
+        self._api_url = api_url.rstrip("/")
+        self._model = model
+        self._api_key = api_key or None
+        self._timeout = float(timeout or _DEFAULT_TIMEOUT)
+        self._temperature = temperature
+        self._extra_headers = dict(extra_headers or {})
+
+    @property
+    def descriptor(self) -> str:
+        return f"openai_compatible/{self._model}"
+
+    async def transcribe(
+        self,
+        audio: bytes,
+        *,
+        mime_type: str,
+        language: Optional[str] = None,
+        timestamps: bool = False,
+    ) -> STTResult:
+        if not audio:
+            raise STTError("audio payload is empty", category="invalid")
+
+        headers = dict(self._extra_headers)
+        if self._api_key:
+            headers["Authorization"] = f"Bearer {self._api_key}"
+
+        data: Dict[str, Any] = {
+            "model": self._model,
+            "response_format": "verbose_json" if timestamps else "json",
+            "temperature": str(self._temperature),
+        }
+        if language:
+            data["language"] = language
+
+        ext = (mime_type.rsplit("/", 1)[-1] or "bin").split(";")[0]
+        files = {"file": (f"audio.{ext}", audio, mime_type or "application/octet-stream")}
+
+        try:
+            async with httpx.AsyncClient(timeout=self._timeout) as client:
+                resp = await client.post(
+                    f"{self._api_url}/v1/audio/transcriptions",
+                    data=data,
+                    files=files,
+                    headers=headers,
+                )
+        except httpx.TimeoutException as exc:
+            raise STTError(f"STT request timed out: {exc}", category="transient") from exc
+        except httpx.HTTPError as exc:
+            raise STTError(f"STT transport error: {exc}", category="transient") from exc
+
+        if resp.status_code != 200:
+            body = resp.text[:300]
+            raise STTError(
+                f"STT endpoint returned HTTP {resp.status_code}: {body}",
+                category=_categorize(resp.status_code),
+            )
+
+        try:
+            payload = resp.json()
+        except ValueError:
+            # some servers honour response_format=text regardless
+            payload = {"text": resp.text}
+
+        segments = None
+        raw_segments = payload.get("segments") if isinstance(payload, dict) else None
+        if isinstance(raw_segments, list):
+            segments = []
+            for seg in raw_segments:
+                try:
+                    segments.append(STTSegment(
+                        start=float(seg.get("start", 0.0)),
+                        end=float(seg.get("end", 0.0)),
+                        text=str(seg.get("text", "")).strip(),
+                    ))
+                except (TypeError, ValueError):
+                    continue
+
+        text = str(payload.get("text", "")) if isinstance(payload, dict) else str(payload)
+        duration = payload.get("duration") if isinstance(payload, dict) else None
+        return STTResult(
+            text=text.strip(),
+            language=(payload.get("language") if isinstance(payload, dict) else None),
+            duration_seconds=float(duration) if isinstance(duration, (int, float)) else None,
+            segments=segments,
+            provider=self.descriptor,
+        )

geny_executor-2.64.0/src/geny_executor/audio/stt/provider.py

@@ -0,0 +1,102 @@
+"""STT provider interface — the swappable speech-to-text backend.
+
+Mirrors the embedding-client contract (the package's canonical
+"strong interface" seam): a deliberately minimal ``@runtime_checkable``
+Protocol, a small result dataclass, and a categorized error type so
+tools can turn failures into user-actionable messages.
+
+The host wires a concrete provider per session through
+``ToolContext.extras["stt"]`` (serializable config — provider name +
+endpoint + model), resolved via :func:`geny_executor.audio.stt.registry.
+create_stt_client`. Hosts with bespoke engines register them with
+:func:`register_stt_provider` and address them by name from plain
+config — no client-instance injection needed.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List, Optional, Protocol, runtime_checkable
+
+
+@dataclass
+class STTSegment:
+    """One timed span of the transcript (``timestamps=True`` results)."""
+
+    start: float
+    end: float
+    text: str
+
+    def to_dict(self) -> dict:
+        return {"start": self.start, "end": self.end, "text": self.text}
+
+
+@dataclass
+class STTResult:
+    """A completed transcription."""
+
+    text: str
+    language: Optional[str] = None
+    duration_seconds: Optional[float] = None
+    segments: Optional[List[STTSegment]] = None
+    #: Provider descriptor that produced this result ("provider/model").
+    provider: str = ""
+    extra: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        out: dict = {"text": self.text, "provider": self.provider}
+        if self.language:
+            out["language"] = self.language
+        if self.duration_seconds is not None:
+            out["duration_seconds"] = self.duration_seconds
+        if self.segments is not None:
+            out["segments"] = [s.to_dict() for s in self.segments]
+        return out
+
+
+#: Failure classes a caller can act on (embedding EmbeddingError parity).
+STT_ERROR_CATEGORIES = ("auth", "quota", "transient", "invalid", "unknown")
+
+
+class STTError(Exception):
+    """Categorized STT failure.
+
+    ``category`` ∈ :data:`STT_ERROR_CATEGORIES`:
+      * ``auth`` — key/endpoint rejected the request (401/403)
+      * ``quota`` — rate/size limits (413/429)
+      * ``transient`` — network / 5xx / timeout; retry may succeed
+      * ``invalid`` — the audio itself is unusable (bad format, empty)
+      * ``unknown`` — anything else
+    """
+
+    def __init__(self, message: str, *, category: str = "unknown") -> None:
+        super().__init__(message)
+        self.category = category if category in STT_ERROR_CATEGORIES else "unknown"
+
+
+@runtime_checkable
+class STTProvider(Protocol):
+    """Minimal speech-to-text backend contract.
+
+    Implementations MUST:
+      * be safe to call concurrently (or serialize internally);
+      * raise :class:`STTError` (never a bare transport exception) so the
+        tool layer can classify failures;
+      * treat ``language=None`` as auto-detect.
+    """
+
+    async def transcribe(
+        self,
+        audio: bytes,
+        *,
+        mime_type: str,
+        language: Optional[str] = None,
+        timestamps: bool = False,
+    ) -> STTResult:
+        """Transcribe ``audio`` and return the result."""
+        ...
+
+    @property
+    def descriptor(self) -> str:
+        """Stable identity, e.g. ``"openai_compatible/whisper-large-v3"``."""
+        ...

geny_executor-2.64.0/src/geny_executor/audio/stt/registry.py

@@ -0,0 +1,98 @@
+"""Factory + host-extension registry for STT providers.
+
+Single entrypoint :func:`create_stt_client` maps a provider string to a
+concrete :class:`~geny_executor.audio.stt.provider.STTProvider`.
+Built-in: ``openai_compatible`` (also aliased as ``openai`` /
+``whisper`` — they all speak ``/v1/audio/transcriptions``).
+
+Hosts register their own engines at runtime with
+:func:`register_stt_provider` — same seam as the embedding registry::
+
+    register_stt_provider("my-stt-service", build_my_client)
+    # …then, in ToolContext.extras:
+    {"stt": {"provider": "my-stt-service", "model": "…", ...}}
+
+which keeps the per-session config serializable while transport and
+credential logic stay entirely in the host.
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Any, Callable, Dict
+
+from geny_executor.audio.stt.provider import STTProvider
+
+_BUILTIN_ALIASES = {
+    "openai_compatible": "openai_compatible",
+    "openai": "openai_compatible",
+    "whisper": "openai_compatible",
+}
+
+_CUSTOM_BUILDERS: Dict[str, Callable[..., STTProvider]] = {}
+_CUSTOM_LOCK = threading.Lock()
+
+
+def register_stt_provider(
+    name: str,
+    builder: Callable[..., STTProvider],
+    *,
+    replace: bool = False,
+) -> None:
+    """Register a host-provided STT backend under ``name``.
+
+    ``builder`` is called as ``builder(**config)`` whenever
+    ``create_stt_client(name, **config)`` runs. Built-in names cannot be
+    shadowed (ValueError); re-registering a custom name requires
+    ``replace=True`` (idempotent boot paths pass it deliberately).
+    """
+    key = (name or "").lower().strip()
+    if not key:
+        raise ValueError("stt provider name must be a non-empty string")
+    if key in _BUILTIN_ALIASES:
+        raise ValueError(
+            f"cannot register stt provider {name!r}: shadows a built-in "
+            f"(built-ins: {sorted(set(_BUILTIN_ALIASES))})"
+        )
+    if not callable(builder):
+        raise TypeError("builder must be callable")
+    with _CUSTOM_LOCK:
+        if key in _CUSTOM_BUILDERS and not replace:
+            raise ValueError(
+                f"stt provider {name!r} is already registered "
+                "(pass replace=True to overwrite)"
+            )
+        _CUSTOM_BUILDERS[key] = builder
+
+
+def unregister_stt_provider(name: str) -> bool:
+    """Remove a host-registered backend. Returns True when it existed."""
+    key = (name or "").lower().strip()
+    with _CUSTOM_LOCK:
+        return _CUSTOM_BUILDERS.pop(key, None) is not None
+
+
+def create_stt_client(provider: str, **config: Any) -> STTProvider:
+    """Build an :class:`STTProvider` for ``provider``.
+
+    Unknown providers raise ``ValueError`` listing what IS available —
+    the tool layer surfaces that verbatim so misconfiguration is
+    self-explaining.
+    """
+    key = (provider or "").lower().strip() or "openai_compatible"
+
+    with _CUSTOM_LOCK:
+        custom = _CUSTOM_BUILDERS.get(key)
+    if custom is not None:
+        return custom(**config)
+
+    if key in _BUILTIN_ALIASES:
+        from geny_executor.audio.stt.openai_compatible import OpenAICompatibleSTT
+
+        return OpenAICompatibleSTT(**config)
+
+    with _CUSTOM_LOCK:
+        available = sorted(set(_BUILTIN_ALIASES) | set(_CUSTOM_BUILDERS))
+    raise ValueError(
+        f"unknown stt provider {provider!r}; available: {available}"
+    )

{geny_executor-2.63.0 → geny_executor-2.64.0}/src/geny_executor/memory/providers/file/stm_store.py

@@ -91,6 +91,8 @@ class _JSONLSTMStore:
         self._tz = tz
         self._lock = LoopAgnosticLock()
         self._hooks = hooks or MemoryHooks()
+        #: (stat-signature, parsed lines) — see _read_lines_sync.
+        self._lines_cache: Optional[tuple] = None
         # Appends since the last line-cap enforcement (audit M2): the cap
         # runs periodically rather than every append (which would re-read
         # the whole jsonl each time), bounding the file to
@@ -293,10 +295,27 @@ class _JSONLSTMStore:
             return self._read_lines_sync()
 
     def _read_lines_sync(self) -> List[str]:
-        if not self._path.exists():
+        """Whole-file line read with an (mtime_ns, size)-keyed cache.
+
+        recent()/search() — and host UIs layered on them — re-read the entire
+        jsonl on every call; on a byte-capped 16 MB transcript that is 16 MB
+        of IO+strip per page view. The file only changes through our own
+        append/truncate (plus rare external edits, which move mtime/size and
+        invalidate naturally), so caching the parsed line list against the
+        stat signature makes repeat reads O(1) without any staleness window."""
+        try:
+            st = self._path.stat()
+        except OSError:
+            self._lines_cache = None
             return []
+        key = (st.st_mtime_ns, st.st_size)
+        cached = self._lines_cache
+        if cached is not None and cached[0] == key:
+            return cached[1]
         with self._path.open("r", encoding="utf-8") as fh:
-            return [line.rstrip("\n") for line in fh if line.strip()]
+            lines = [line.rstrip("\n") for line in fh if line.strip()]
+        self._lines_cache = (key, lines)
+        return lines
 
 
 # ── record <-> Turn converters ───────────────────────────────────────

{geny_executor-2.63.0 → geny_executor-2.64.0}/src/geny_executor/tools/built_in/__init__.py

@@ -133,6 +133,7 @@ from geny_executor.tools.built_in.sandbox_exec_tool import SandboxExecTool
 # SSH — run commands / move files on the session's pre-configured servers.
 # Gated on feature:ssh_enabled; degrades to an install-hint error when the
 # optional ``asyncssh`` dependency is absent.
+from geny_executor.tools.built_in.audio_tools import AUDIO_TOOL_CLASSES
 from geny_executor.tools.built_in.ssh_tools import (
     SSH_TOOL_CLASSES,
     SshDownloadTool,
@@ -207,6 +208,7 @@ BUILT_IN_TOOL_CLASSES: Dict[str, Type[Tool]] = {
     # SSH — command/SFTP on the session's configured servers (gated on
     # feature:ssh_enabled); lazy-imports asyncssh with an install-hint fallback.
     **SSH_TOOL_CLASSES,
+    **AUDIO_TOOL_CLASSES,
 }
 
 
@@ -253,6 +255,8 @@ BUILT_IN_TOOL_FEATURES: Dict[str, List[str]] = {
     "atlassian": list(ATLASSIAN_TOOL_CLASSES.keys()),
     # Remote server ops over SSH/SFTP — run commands, transfer files, sudo.
     "ssh": list(SSH_TOOL_CLASSES.keys()),
+    # Workspace audio → text bridge (STT). Gated on feature:stt_enabled.
+    "audio": list(AUDIO_TOOL_CLASSES.keys()),
 }
 
 
@@ -315,6 +319,7 @@ __all__ = [
     "BROWSER_TOOL_CLASSES",
     "DOC_TOOL_CLASSES",
     "SSH_TOOL_CLASSES",
+    "AUDIO_TOOL_CLASSES",
     "SshListServersTool",
     "SshRunTool",
     "SshUploadTool",