generic-ml-wrapper 0.1.0__py3-none-any.whl

generic_ml_wrapper/application/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The application layer: domain, ports, use cases, wiring."""

generic_ml_wrapper/application/domain/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Pure domain: entities and services, no I/O."""

generic_ml_wrapper/application/domain/model/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Domain value objects."""

generic_ml_wrapper/application/domain/model/client_status.py

@@ -0,0 +1,44 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The ClientStatus value object: what a client reports to its status line."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+_MAX_CONTEXT_PCT = 100
+
+
+@dataclass(frozen=True)
+class ClientStatus:
+    """A client's live status, parsed from the payload it pipes to the status line.
+
+    Each field is optional because a client may not report it (or not yet).
+
+    Attributes:
+        model: The active model's display name, or ``None``.
+        context_pct: The context-window fill percentage, or ``None``.
+        session_cost_usd: The session's cumulative cost in USD, or ``None``.
+        extras: Client-specific, already-formatted status blocks (e.g. Claude's
+            quota) placed after the common fields; empty when the client reports
+            none. Each block carries its own label because its shape and name vary
+            by client, so the parser owns the formatting and the renderer only
+            places them.
+    """
+
+    model: str | None
+    context_pct: int | None
+    session_cost_usd: float | None
+    extras: tuple[str, ...]
+
+    def __post_init__(self) -> None:
+        """Reject an out-of-range context percentage or a negative cost."""
+        if self.context_pct is not None and not 0 <= self.context_pct <= _MAX_CONTEXT_PCT:
+            message = f"context_pct must be within 0..100, got {self.context_pct}"
+            raise ValueError(message)
+        if self.session_cost_usd is not None and (
+            self.session_cost_usd < 0 or not math.isfinite(self.session_cost_usd)
+        ):
+            message = f"session_cost_usd must be >= 0 and finite, got {self.session_cost_usd}"
+            raise ValueError(message)

generic_ml_wrapper/application/domain/model/identifiers.py

@@ -0,0 +1,76 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Validated identifier value objects.
+
+Each is a ``str`` subclass validated on construction, so an invalid identifier can
+never be built -- and, being a ``str``, it drops in wherever the raw value flowed
+before. Validation happens at the boundary (the CLI constructs them from argv),
+so bad input fails early with a clear message rather than deep in a filesystem path.
+"""
+
+from __future__ import annotations
+
+import re
+
+# A job id is a single safe path segment: letters, digits, '-' and '_', starting
+# with a letter or digit, at most 64 chars. No '.', '/', '\\', or NUL -- so no
+# '..' traversal, no absolute path, no separator can reach a filesystem path.
+_JOB_ID = re.compile(r"\A[A-Za-z0-9][A-Za-z0-9_-]{0,63}\Z")
+
+# A workflow name is lowercase kebab: the same rule new_workflow used, now shared.
+_WORKFLOW_NAME = re.compile(r"\A[a-z0-9][a-z0-9-]*\Z")
+
+# An environment-variable name: POSIX portable (letters, digits, '_'; not a leading digit).
+_ENV_VAR_NAME = re.compile(r"\A[A-Za-z_][A-Za-z0-9_]*\Z")
+
+
+class IdentifierError(ValueError):
+    """Raised when a string is not a valid identifier of its kind."""
+
+
+class JobId(str):
+    """A validated job identifier (a safe single path segment)."""
+
+    __slots__ = ()
+
+    def __new__(cls, value: str) -> JobId:
+        """Return the validated job id, or raise :class:`IdentifierError`."""
+        if not _JOB_ID.match(value):
+            message = (
+                f"invalid job id {value!r}: allowed characters are letters, digits, "
+                "'-' and '_'; it must start with a letter or digit and be at most 64 characters"
+            )
+            raise IdentifierError(message)
+        return super().__new__(cls, value)
+
+
+class WorkflowName(str):
+    """A validated workflow name (lowercase letters/digits and ``-``)."""
+
+    __slots__ = ()
+
+    def __new__(cls, value: str) -> WorkflowName:
+        """Return the validated workflow name, or raise :class:`IdentifierError`."""
+        if not _WORKFLOW_NAME.match(value):
+            message = (
+                f"invalid workflow name {value!r}: allowed characters are lowercase "
+                "letters, digits and '-'; it must start with a letter or digit"
+            )
+            raise IdentifierError(message)
+        return super().__new__(cls, value)
+
+
+class EnvVarName(str):
+    """A validated environment-variable name (POSIX portable)."""
+
+    __slots__ = ()
+
+    def __new__(cls, value: str) -> EnvVarName:
+        """Return the validated env-var name, or raise :class:`IdentifierError`."""
+        if not _ENV_VAR_NAME.match(value):
+            message = (
+                f"invalid environment-variable name {value!r}: allowed characters are "
+                "letters, digits and '_'; it must not start with a digit"
+            )
+            raise IdentifierError(message)
+        return super().__new__(cls, value)

generic_ml_wrapper/application/domain/model/run.py

@@ -0,0 +1,35 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The RunContext handed to a client caller."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class RunContext:
+    """Everything a caller needs to launch and meter one run.
+
+    Attributes:
+        job: The job identifier.
+        session_id: The session's human-readable id.
+        client: The client to launch.
+        uuid: The client-side session id, or ``None``.
+        resume: Whether this run resumes an existing session.
+        cwd: The working directory to launch in, or ``None`` for the current one.
+        context: Operating context to inject into the session, or ``None``.
+        kickoff: An opening message to start the session on, or ``None``.
+        env: Extra environment variables to export for the run (name/value pairs),
+            e.g. a workflow's resolved credentials.
+    """
+
+    job: str
+    session_id: str
+    client: str
+    uuid: str | None
+    resume: bool
+    cwd: str | None = None
+    context: str | None = None
+    kickoff: str | None = None
+    env: tuple[tuple[str, str], ...] = ()

generic_ml_wrapper/application/domain/model/session.py

@@ -0,0 +1,24 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The Session value object."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Session:
+    """A named, resumable client conversation belonging to a job.
+
+    Attributes:
+        session_id: The human-readable id, ``<job>_NNN``.
+        job: The job this session belongs to.
+        client: The client it runs on (e.g. ``"claude"``).
+        uuid: The client-side session id (Claude's ``--session-id``), or ``None``.
+    """
+
+    session_id: str
+    job: str
+    client: str
+    uuid: str | None

generic_ml_wrapper/application/domain/model/turn_usage.py

@@ -0,0 +1,62 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The TurnUsage value object: one metered request/response round."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class TurnUsage:
+    """The token (and optional cost) usage of a single client turn.
+
+    A turn is one request/response round a metering gateway observed on the wire.
+
+    Attributes:
+        session_id: The session the turn belongs to.
+        input_tokens: Prompt tokens sent upstream.
+        output_tokens: Completion tokens received.
+        cost_usd: The turn's cost in USD when the gateway can compute it, else
+            ``None`` (e.g. no price is known for the model).
+        model: The model that served the turn, or ``None`` if unreported.
+        cache_creation_tokens: Prompt tokens written to the cache this turn.
+        cache_read_tokens: Prompt tokens served from the cache this turn.
+        timestamp: The turn's wall-clock time (epoch seconds), or ``0.0``.
+        duration_s: How long the turn took, in seconds, or ``0.0``.
+        turn_id: The provider's id for this turn, or ``None``.
+    """
+
+    session_id: str
+    input_tokens: int
+    output_tokens: int
+    cost_usd: float | None
+    model: str | None
+    cache_creation_tokens: int = 0
+    cache_read_tokens: int = 0
+    timestamp: float = 0.0
+    duration_s: float = 0.0
+    turn_id: str | None = None
+
+    def __post_init__(self) -> None:
+        """Reject impossible usage: negative counts, or non-finite/negative amounts."""
+        for name in (
+            "input_tokens",
+            "output_tokens",
+            "cache_creation_tokens",
+            "cache_read_tokens",
+        ):
+            value: int = getattr(self, name)
+            if value < 0:
+                message = f"{name} must be non-negative, got {value}"
+                raise ValueError(message)
+        if self.cost_usd is not None and (self.cost_usd < 0 or not math.isfinite(self.cost_usd)):
+            message = f"cost_usd must be a non-negative finite number, got {self.cost_usd}"
+            raise ValueError(message)
+        if self.timestamp < 0 or not math.isfinite(self.timestamp):
+            message = f"timestamp must be a non-negative finite number, got {self.timestamp}"
+            raise ValueError(message)
+        if self.duration_s < 0 or not math.isfinite(self.duration_s):
+            message = f"duration_s must be a non-negative finite number, got {self.duration_s}"
+            raise ValueError(message)

generic_ml_wrapper/application/domain/model/workspace.py

@@ -0,0 +1,31 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The Workspace value object: environment facts the wrapper reports itself."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Workspace:
+    """The working environment a run executes in, computed by the wrapper.
+
+    These facts are client-agnostic: the wrapper derives them from the working
+    directory and git, so they enrich the status line the same way for every
+    client. Each field is optional because the run may not be in a git repository
+    (or in any resolvable directory at all).
+
+    Attributes:
+        folder: The working directory (home abbreviated to ``~``), or ``None``.
+        repo: The git repository's name, or ``None`` outside a repository.
+        branch: The checked-out branch, or ``None`` outside a repository.
+        short_sha: The current commit's short hash, or ``None``.
+        dirty: The count of uncommitted changes (``0`` when clean).
+    """
+
+    folder: str | None
+    repo: str | None
+    branch: str | None
+    short_sha: str | None
+    dirty: int

generic_ml_wrapper/application/domain/service/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Pure domain services."""

generic_ml_wrapper/application/domain/service/interceptor.py

@@ -0,0 +1,30 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The ``Interceptor`` abstraction: a text transform applied at a named target.
+
+This is the domain-owned contract the :class:`InterceptorChain` sequences. The
+outbound :class:`~generic_ml_wrapper.application.port.outbound.interceptor.InterceptorPort`
+extends it, so the dependency points inward (port -> domain) and the domain never
+reaches out to a port.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class Interceptor(ABC):
+    """Transform a piece of text flowing through gmlw at a named target."""
+
+    @abstractmethod
+    def intercept(self, text: str, target: str) -> str:
+        """Return the transformed text (or the input unchanged).
+
+        Args:
+            text: The text to transform.
+            target: The target it is running for (e.g. ``context``, ``request``,
+                ``response``), so one interceptor can behave per target.
+
+        Returns:
+            The transformed text.
+        """

generic_ml_wrapper/application/domain/service/interceptor_chain.py

@@ -0,0 +1,57 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The InterceptorChain: apply per-target interceptors in order."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from generic_ml_wrapper.application.domain.service.interceptor import Interceptor
+
+
+class InterceptorChain:
+    """An ordered set of ``(target, interceptor)`` pairs applied at named targets.
+
+    Each interceptor targets a name; :meth:`apply` runs, in declared order, those
+    whose target matches (a target may have 0..N, and one interceptor may appear
+    under several targets). The compile applies the context targets
+    (``profile``/``rules``/``workflow``/``context``); the metering relay applies the
+    wire targets (``request``/``response``). An empty chain is the identity.
+    """
+
+    def __init__(self, interceptors: Sequence[tuple[str, Interceptor]]) -> None:
+        """Bind the chain to its ordered interceptors.
+
+        Args:
+            interceptors: The ``(target, interceptor)`` pairs, in application order.
+        """
+        self._interceptors = tuple(interceptors)
+
+    def has(self, target: str) -> bool:
+        """Whether any interceptor is bound to ``target``.
+
+        Args:
+            target: The target name to check.
+
+        Returns:
+            ``True`` if at least one interceptor targets it.
+        """
+        return any(interceptor_target == target for interceptor_target, _ in self._interceptors)
+
+    def apply(self, target: str, text: str) -> str:
+        """Apply every interceptor bound to ``target``, in order.
+
+        Args:
+            target: The target name to run interceptors for.
+            text: The text to transform.
+
+        Returns:
+            The text after the matching interceptors have run.
+        """
+        for interceptor_target, interceptor in self._interceptors:
+            if interceptor_target == target:
+                text = interceptor.intercept(text, target)
+        return text

generic_ml_wrapper/application/domain/service/rule_cleaner.py

@@ -0,0 +1,35 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Pure rule cleaning: drop bookkeeping and human-only notes before the model sees it."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+
+_FRONTMATTER = re.compile(r"\A---\n.*?\n---\n", re.DOTALL)
+_BLANKS = re.compile(r"\n{3,}")
+
+
+def clean_rule(text: str, sections: Sequence[str]) -> str:
+    """Strip a rule's frontmatter and any human-only sections, losslessly for the model.
+
+    Removes the leading YAML frontmatter (bookkeeping such as name/status) and each
+    ``**Name:**`` section listed in ``sections`` (running until the next ``**Header:**``
+    marker, a markdown ``# `` heading, or end of text). Blank runs are collapsed. The
+    ``# `` stop is load-bearing: without it a trailing block would swallow the next
+    rule's title. Idempotent.
+
+    Args:
+        text: The raw rule text.
+        sections: Bold-header section names to drop (case-sensitive on the name).
+
+    Returns:
+        The cleaned rule text.
+    """
+    text = _FRONTMATTER.sub("", text, count=1)
+    if sections:
+        names = "|".join(re.escape(name) for name in sections)
+        stop = r"(?:^\*\*[^*:\n]+:\*\*|^#\s)"
+        text = re.compile(rf"(?ms)^\*\*(?:{names}):\*\*.*?(?={stop}|\Z)").sub("", text)
+    return _BLANKS.sub("\n\n", text).strip()

generic_ml_wrapper/application/domain/service/session_naming.py

@@ -0,0 +1,30 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Pure session naming: mint the next ``<job>_NNN`` id."""
+
+from __future__ import annotations
+
+import re
+
+_SUFFIX = re.compile(r"_(\d+)$")
+
+
+def next_session_id(job: str, existing_ids: list[str]) -> str:
+    """Return the next sequential session id for a job.
+
+    Ids are ``<job>_NNN`` (three-digit, 1-based). The next number is one past the
+    highest existing suffix, so gaps never cause a collision.
+
+    Args:
+        job: The job identifier.
+        existing_ids: The session ids already recorded for the job.
+
+    Returns:
+        The next session id, e.g. ``"JOB-1_001"``.
+    """
+    highest = 0
+    for session_id in existing_ids:
+        match = _SUFFIX.search(session_id)
+        if match:
+            highest = max(highest, int(match.group(1)))
+    return f"{job}_{highest + 1:03d}"

generic_ml_wrapper/application/domain/service/statusline_renderer.py

@@ -0,0 +1,81 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Pure rendering of the working environment and client status into one line."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from generic_ml_wrapper.application.domain.model.client_status import ClientStatus
+    from generic_ml_wrapper.application.domain.model.workspace import Workspace
+
+_SEPARATOR = "  ·  "
+
+
+def render_statusline(status: ClientStatus, workspace: Workspace) -> str:
+    """Render the working environment and client status as a single line.
+
+    The wrapper's own facts (git, folder) come first, then the common client
+    fields (model, context), then any client-specific ``extras`` (already
+    formatted, e.g. Claude's quota), then cost. Blocks the environment or client
+    did not provide are omitted, so a bare environment with an empty status yields
+    an empty line.
+
+    Args:
+        status: The parsed client status.
+        workspace: The working environment the wrapper computed.
+
+    Returns:
+        The status line (no trailing newline).
+    """
+    blocks = [
+        _git(workspace),
+        _folder(workspace),
+        status.model,
+        None if status.context_pct is None else f"ctx {status.context_pct}%",
+        *status.extras,
+        None if status.session_cost_usd is None else f"${status.session_cost_usd:.2f}",
+    ]
+    return _SEPARATOR.join(block for block in blocks if block)
+
+
+def render_usage_row(label: str, name: str, turns: int, tokens: int, cost_usd: float) -> str:
+    """Render one usage footer row -- ``<label> <name> · N turns · tok · $`` -- indented.
+
+    Used for both the current-session row (``label="session"``) and the whole-job
+    total (``label="job"``). Turns/tokens show only when deep-metered (``turns`` > 0);
+    the cost always shows. The leading indent sets the footer apart from the live line.
+
+    Args:
+        label: The scope label, ``"session"`` or ``"job"``.
+        name: The session id or job id.
+        turns: The recorded turn count for this scope (``0`` if unmetered).
+        tokens: The total tokens across those turns (input + output + cache).
+        cost_usd: The scope's cumulative cost.
+
+    Returns:
+        The footer row (no trailing newline).
+    """
+    parts = [f"{label} {name}"]
+    if turns:
+        parts.append(f"{turns} turns")
+        parts.append(f"{tokens} tok")
+    parts.append(f"${cost_usd:.2f}")
+    return "  " + " · ".join(parts)
+
+
+def _git(workspace: Workspace) -> str | None:
+    if workspace.branch is None:
+        return None
+    head = f"{workspace.repo}/{workspace.branch}" if workspace.repo else workspace.branch
+    parts = [f"git {head}"]
+    if workspace.short_sha:
+        parts.append(workspace.short_sha)
+    if workspace.dirty:
+        parts.append(f"dirty:{workspace.dirty}")
+    return " ".join(parts)
+
+
+def _folder(workspace: Workspace) -> str | None:
+    return None if workspace.folder is None else f"📁 {workspace.folder}"

generic_ml_wrapper/application/port/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The ports: the application's boundary."""

generic_ml_wrapper/application/port/inbound/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Inbound ports: the use cases the app offers."""

generic_ml_wrapper/application/port/inbound/bootstrap.py

@@ -0,0 +1,15 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The inbound port for first-run self-initialization."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class Bootstrap(ABC):
+    """Ensure the wrapper's runtime layout exists, creating only what is missing."""
+
+    @abstractmethod
+    def execute(self) -> None:
+        """Create any missing parts of the ``~/.gmlw`` layout (idempotent)."""

generic_ml_wrapper/application/port/inbound/export_usage.py

@@ -0,0 +1,109 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The inbound port for reporting a job's recorded usage."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class TurnRow:
+    """One metered turn, for the per-turn table.
+
+    Attributes:
+        timestamp: The turn's wall-clock time (epoch seconds), or ``0.0``.
+        model: The model that served the turn.
+        duration_s: How long the turn took, in seconds.
+        input_tokens: Fresh prompt tokens.
+        output_tokens: Completion tokens.
+        cache_tokens: Cache creation + read prompt tokens.
+        turn_id: The provider's id for the turn, or ``None``.
+    """
+
+    timestamp: float
+    model: str
+    duration_s: float
+    input_tokens: int
+    output_tokens: int
+    cache_tokens: int
+    turn_id: str | None
+
+
+@dataclass(frozen=True)
+class ModelTotal:
+    """A model's totals across the job.
+
+    Attributes:
+        model: The model's name.
+        calls: How many turns this model served.
+        input_tokens: Total fresh prompt tokens.
+        output_tokens: Total completion tokens.
+        cache_tokens: Total cache prompt tokens.
+        duration_s: Total duration, in seconds.
+    """
+
+    model: str
+    calls: int
+    input_tokens: int
+    output_tokens: int
+    cache_tokens: int
+    duration_s: float
+
+
+@dataclass(frozen=True)
+class SessionCost:
+    """A session's recorded cost.
+
+    Attributes:
+        session_id: The session's human-readable id.
+        cost_usd: The session's cumulative cost in USD.
+    """
+
+    session_id: str
+    cost_usd: float
+
+
+@dataclass(frozen=True)
+class UsageReport:
+    """A job's recorded usage: per-turn rows, totals by model, cost by session, totals.
+
+    Attributes:
+        job: The job identifier.
+        turns: Every metered turn, chronological.
+        models: Totals by model, sorted by model name.
+        session_costs: Recorded cost per session, sorted by session id.
+        turn_count: The number of metered turns.
+        input_tokens: The job's total fresh prompt tokens.
+        output_tokens: The job's total completion tokens.
+        cache_tokens: The job's total cache prompt tokens.
+        duration_s: The job's total metered duration, in seconds.
+        total_usd: The job's total cost across its sessions.
+    """
+
+    job: str
+    turns: tuple[TurnRow, ...] = ()
+    models: tuple[ModelTotal, ...] = ()
+    session_costs: tuple[SessionCost, ...] = ()
+    turn_count: int = 0
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cache_tokens: int = 0
+    duration_s: float = 0.0
+    total_usd: float = 0.0
+
+
+class ExportUsage(ABC):
+    """Report the usage recorded for a job."""
+
+    @abstractmethod
+    def execute(self, job: str) -> UsageReport:
+        """Build a job's usage report.
+
+        Args:
+            job: The job identifier.
+
+        Returns:
+            The job's per-turn rows, per-model totals, per-session cost, and totals.
+        """