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

generic_ml_wrapper/application/port/inbound/list_jobs.py

@@ -0,0 +1,33 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The inbound port for listing the jobs with recorded activity."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class JobSummary:
+    """A one-line summary of a job's recorded activity.
+
+    Attributes:
+        job: The job identifier.
+        session_count: How many sessions have been recorded for the job.
+    """
+
+    job: str
+    session_count: int
+
+
+class ListJobs(ABC):
+    """List the jobs that have recorded sessions."""
+
+    @abstractmethod
+    def execute(self) -> list[JobSummary]:
+        """List the jobs with recorded activity.
+
+        Returns:
+            One summary per job, sorted by job id.
+        """

generic_ml_wrapper/application/port/inbound/list_sessions.py

@@ -0,0 +1,36 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The inbound port for listing a job's sessions."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class SessionSummary:
+    """A one-line summary of a recorded session.
+
+    Attributes:
+        session_id: The session's human-readable id.
+        client: The client the session runs on.
+    """
+
+    session_id: str
+    client: str
+
+
+class ListSessions(ABC):
+    """List the sessions recorded for a job."""
+
+    @abstractmethod
+    def execute(self, job: str) -> list[SessionSummary]:
+        """List a job's sessions.
+
+        Args:
+            job: The job identifier.
+
+        Returns:
+            One summary per session, oldest first.
+        """

generic_ml_wrapper/application/port/inbound/list_workflows.py

@@ -0,0 +1,19 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The inbound port for listing the available workflows."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class ListWorkflows(ABC):
+    """List the runnable workflows."""
+
+    @abstractmethod
+    def execute(self) -> list[str]:
+        """List the runnable workflow names.
+
+        Returns:
+            The workflow names, sorted (empty if none exist).
+        """

generic_ml_wrapper/application/port/inbound/new_workflow.py

@@ -0,0 +1,48 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The inbound port for authoring a new workflow."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class NewWorkflowCommand:
+    """A request to author a new workflow.
+
+    Attributes:
+        name: The new workflow's name (lowercase letters, digits, dashes).
+        client: The client to run the authoring session on.
+    """
+
+    name: str
+    client: str
+
+
+class WorkflowNameError(ValueError):
+    """Raised when a workflow name is invalid or reserved."""
+
+
+class WorkflowExistsError(ValueError):
+    """Raised when a workflow with the requested name already exists."""
+
+
+class NewWorkflow(ABC):
+    """Author a new workflow through the create-workflow interview."""
+
+    @abstractmethod
+    def execute(self, command: NewWorkflowCommand) -> int:
+        """Run the authoring session for a new workflow.
+
+        Args:
+            command: The request describing the workflow name and client.
+
+        Returns:
+            The client's exit code.
+
+        Raises:
+            WorkflowNameError: If the name is invalid or reserved.
+            WorkflowExistsError: If a workflow with that name already exists.
+        """

generic_ml_wrapper/application/port/inbound/render_statusline.py

@@ -0,0 +1,24 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The inbound port for rendering a status line and recording usage."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class RenderStatusline(ABC):
+    """Render a client's status line and record its usage."""
+
+    @abstractmethod
+    def execute(self, payload_json: str, job: str | None, session: str | None) -> str:
+        """Parse the client's payload, record usage, and render the status line.
+
+        Args:
+            payload_json: The raw JSON the client piped to the status-line command.
+            job: The active job, or ``None`` if unknown (usage is not recorded then).
+            session: The active session, or ``None`` if unknown.
+
+        Returns:
+            The status line to print (may be empty if the client reported nothing).
+        """

generic_ml_wrapper/application/port/inbound/set_credential.py

@@ -0,0 +1,35 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The inbound port for storing a workflow credential."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class SetCredentialCommand:
+    """A request to store one credential for a workflow.
+
+    Attributes:
+        workflow: The workflow the credential belongs to.
+        name: The environment-variable name to export at launch.
+        value: The secret value.
+    """
+
+    workflow: str
+    name: str
+    value: str
+
+
+class SetCredential(ABC):
+    """Store a single workflow credential in the wrapper's own store."""
+
+    @abstractmethod
+    def execute(self, command: SetCredentialCommand) -> None:
+        """Store the credential described by the command.
+
+        Args:
+            command: The workflow, environment-variable name, and secret value.
+        """

generic_ml_wrapper/application/port/inbound/start_job.py

@@ -0,0 +1,53 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The inbound port for starting work on a job."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class StartJobCommand:
+    """A request to start (or resume) a session on a job.
+
+    Attributes:
+        job: The job identifier.
+        client: The client to launch.
+        resume_latest: Resume the job's most recent session instead of minting one.
+        workflow: A workflow to run on the job, or ``None`` for the plain wrapper.
+    """
+
+    job: str
+    client: str
+    resume_latest: bool = False
+    workflow: str | None = None
+
+
+class UnknownWorkflowError(ValueError):
+    """Raised when a requested workflow does not exist."""
+
+
+class ResumeNotSupportedError(ValueError):
+    """Raised when resuming is requested for a client that cannot resume (e.g. codex)."""
+
+
+class StartJob(ABC):
+    """Start or resume a session on a job and hand over to the client."""
+
+    @abstractmethod
+    def execute(self, command: StartJobCommand) -> int:
+        """Run the use case.
+
+        Args:
+            command: The request describing job, client, resume, and workflow.
+
+        Returns:
+            The client's exit code.
+
+        Raises:
+            UnknownWorkflowError: If a workflow was requested but does not exist.
+            ResumeNotSupportedError: If resume was requested for a client whose
+                caller cannot resume a session.
+        """

generic_ml_wrapper/application/port/outbound/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Outbound ports: what the app needs from the world."""

generic_ml_wrapper/application/port/outbound/cli_caller.py

@@ -0,0 +1,97 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The outbound port for launching and metering a client — the CliCaller seam."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from generic_ml_wrapper.application.domain.model.run import RunContext
+
+
+class CliCaller(ABC):
+    """Launch and meter one client run.
+
+    One stateful instance per run: state set up in ``start_metering`` (before
+    launch) is used by ``start_client`` and torn down in ``end_metering`` (after
+    the client exits). ``start_client`` blocks, so quitting the client is the stop
+    signal — the caller runs ``start_metering`` → ``start_client`` → ``end_metering``.
+    """
+
+    def __init__(self, run: RunContext) -> None:
+        """Bind the caller to a run.
+
+        Args:
+            run: The run this caller will launch and meter.
+        """
+        self.run = run
+
+    def can_deliver_statusline(self) -> bool:
+        """Whether this client hosts a status line the wrapper renders into.
+
+        ``True`` only for clients with a command-backed status-line hook (Claude
+        Code, cursor-agent); ``False`` for clients that expose no such hook (Codex
+        shows fixed built-ins; vibe has its own UI). The wrapper drives its
+        status-line rendering only when this is ``True``. Default: ``False``.
+
+        Returns:
+            ``True`` if the wrapper can render a status line for this client.
+        """
+        return False
+
+    def can_meter_per_call(self) -> bool:
+        """Whether this caller records per-turn usage (e.g. via a metering gateway).
+
+        ``True`` only for callers that route the client's traffic through a gateway
+        able to read each request/response's token usage. Together with a config
+        toggle this gates deep metering: it runs only when the caller can do it and
+        the user asked for it. Default: ``False``.
+
+        Returns:
+            ``True`` if this caller can record per-turn usage.
+        """
+        return False
+
+    def can_resume(self) -> bool:
+        """Whether this client can resume a prior session.
+
+        ``True`` for clients whose launch can reopen a named/identified session
+        (Claude ``--resume``, cursor-agent ``--resume``, vibe ``--resume``);
+        ``False`` for clients with no usable resume path (Codex mints a fresh
+        conversation and exposes no session id we can target without scanning its
+        local store). ``--resume-latest`` is refused when this is ``False`` rather
+        than silently starting a new session. Default: ``True``.
+
+        Returns:
+            ``True`` if this caller can resume a prior session.
+        """
+        return True
+
+    def start_metering(self) -> None:  # noqa: B027  (optional hook; default no-op by design)
+        """Set up metering before launch. Default: do nothing."""
+
+    @abstractmethod
+    def start_client(self) -> int:
+        """Launch the client, blocking until it exits.
+
+        Returns:
+            The client's exit code.
+        """
+
+    def end_metering(self) -> None:  # noqa: B027  (optional hook; default no-op by design)
+        """Tear down metering after the client exits. Default: do nothing."""
+
+
+class CliCallerProvider(ABC):
+    """Resolve the caller to use for a given run."""
+
+    @abstractmethod
+    def for_run(self, run: RunContext) -> CliCaller:
+        """Return the caller instance for a run.
+
+        Args:
+            run: The run to launch.
+
+        Returns:
+            A caller bound to the run.
+        """

generic_ml_wrapper/application/port/outbound/client_status.py

@@ -0,0 +1,27 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The per-client outbound port for parsing a status-line payload."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from generic_ml_wrapper.application.domain.model.client_status import ClientStatus
+
+
+class ClientStatusParserPort(ABC):
+    """Parse a client's status-line payload into a client-agnostic ``ClientStatus``.
+
+    Each client pipes a different payload shape, so this is implemented per client.
+    """
+
+    @abstractmethod
+    def parse(self, payload: dict[str, object]) -> ClientStatus:
+        """Parse a client's status payload.
+
+        Args:
+            payload: The decoded JSON the client piped to the status-line command.
+
+        Returns:
+            The parsed status (fields the client omitted are ``None``).
+        """

generic_ml_wrapper/application/port/outbound/credentials_store.py

@@ -0,0 +1,36 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The outbound port for the wrapper's own credentials store."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class CredentialsStorePort(ABC):
+    """Store and resolve per-workflow credentials the wrapper owns.
+
+    Credentials are grouped by workflow; within a workflow each entry's name is the
+    exact environment variable to export at launch, and its value is the secret.
+    """
+
+    @abstractmethod
+    def resolve(self, workflow: str) -> dict[str, str]:
+        """Return a workflow's credentials as an env-var-name to value mapping.
+
+        Args:
+            workflow: The workflow whose credentials to read.
+
+        Returns:
+            The mapping of environment-variable name to secret (empty if none).
+        """
+
+    @abstractmethod
+    def set(self, workflow: str, name: str, value: str) -> None:
+        """Store one credential for a workflow, replacing any prior value.
+
+        Args:
+            workflow: The workflow the credential belongs to.
+            name: The environment-variable name to export at launch.
+            value: The secret value.
+        """

generic_ml_wrapper/application/port/outbound/interceptor.py

@@ -0,0 +1,25 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The outbound port for an interceptor: a text transform applied at a named target."""
+
+from __future__ import annotations
+
+from abc import ABC
+
+from generic_ml_wrapper.application.domain.service.interceptor import Interceptor
+
+
+class InterceptorPort(Interceptor, ABC):
+    """Outbound port for an interceptor; the contract is the domain :class:`Interceptor`.
+
+    Interceptors are chained (0..N), ordered, and each targets a name: the
+    compile-time context sections (``profile``, ``rules``, ``workflow``, ``context``)
+    or, for clients routed through the metering relay, the live wire (``request`` for
+    the outbound request body, ``response`` for the captured response body). A logger,
+    a compressor, and a secret-anonymiser are all interceptors. An interceptor must be
+    non-destructive on failure — it returns the text unchanged rather than raising — so
+    a misconfigured interceptor never kills a compile or a turn.
+
+    Adapters implement :meth:`Interceptor.intercept`; this port exists so the composition
+    root can resolve interceptor specs to a stable outbound contract.
+    """

generic_ml_wrapper/application/port/outbound/layout_seeder.py

@@ -0,0 +1,18 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The outbound port for seeding the runtime layout on first run."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class LayoutSeederPort(ABC):
+    """Create the wrapper's runtime directories and a default config, missing-only."""
+
+    @abstractmethod
+    def ensure(self) -> None:
+        """Create any missing runtime directories and seed a default config.
+
+        Idempotent: existing directories and an existing config are left untouched.
+        """

generic_ml_wrapper/application/port/outbound/per_turn_metering.py

@@ -0,0 +1,38 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The outbound port for recording per-turn usage a gateway meters."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from generic_ml_wrapper.application.domain.model.turn_usage import TurnUsage
+
+
+class PerTurnMeteringPort(ABC):
+    """Persist and read the per-turn token usage a metering gateway observes.
+
+    This is the deep-metering counterpart to the session-level cost store: where the
+    status line records one cumulative cost per session, a gateway records one entry
+    per request/response round.
+    """
+
+    @abstractmethod
+    def record(self, job: str, turn: TurnUsage) -> None:
+        """Append one metered turn for a job.
+
+        Args:
+            job: The job the turn belongs to.
+            turn: The turn's usage.
+        """
+
+    @abstractmethod
+    def turns_for_job(self, job: str) -> list[TurnUsage]:
+        """Return every recorded turn for a job, in the order recorded.
+
+        Args:
+            job: The job identifier.
+
+        Returns:
+            The recorded turns (empty if none).
+        """

generic_ml_wrapper/application/port/outbound/session_store.py

@@ -0,0 +1,62 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The outbound port for persisting and reading sessions."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from generic_ml_wrapper.application.domain.model.session import Session
+
+
+class SessionStorePort(ABC):
+    """Persist and read the sessions recorded for a job."""
+
+    @abstractmethod
+    def jobs(self) -> list[str]:
+        """Return the ids of all jobs that have recorded sessions.
+
+        Returns:
+            The job ids, sorted (empty if nothing has been recorded).
+        """
+
+    @abstractmethod
+    def record(self, session: Session) -> None:
+        """Append a session to its job's record.
+
+        Args:
+            session: The session to persist.
+        """
+
+    @abstractmethod
+    def sessions_for_job(self, job: str) -> list[Session]:
+        """Return the sessions recorded for a job, oldest first.
+
+        Args:
+            job: The job identifier.
+
+        Returns:
+            The sessions, oldest first (empty if the job is unknown).
+        """
+
+    @abstractmethod
+    def ids_for_job(self, job: str) -> list[str]:
+        """Return the session ids recorded for a job, oldest first.
+
+        Args:
+            job: The job identifier.
+
+        Returns:
+            The session ids, oldest first (empty if the job is unknown).
+        """
+
+    @abstractmethod
+    def latest_for_job(self, job: str) -> Session | None:
+        """Return the most recently recorded session for a job.
+
+        Args:
+            job: The job identifier.
+
+        Returns:
+            The latest session, or ``None`` if the job has none.
+        """

generic_ml_wrapper/application/port/outbound/transcript.py

@@ -0,0 +1,46 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The outbound port for recording a session's transcript: each call's in/out/usage."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from generic_ml_wrapper.application.domain.model.turn_usage import TurnUsage
+
+
+@dataclass(frozen=True)
+class TranscriptCall:
+    """One recorded call: its request, response, usage, and place in the session.
+
+    Attributes:
+        job: The job the call belongs to.
+        session: The session the call belongs to.
+        call_seq: The per-session call number (1-based).
+        request: The request body forwarded upstream.
+        response: The response body returned upstream (raw).
+        usage: The turn's usage, or ``None`` if none could be read.
+    """
+
+    job: str
+    session: str
+    call_seq: int
+    request: bytes
+    response: bytes
+    usage: TurnUsage | None
+
+
+class TranscriptPort(ABC):
+    """Persist a session's transcript -- the request, response, and usage of each call.
+
+    This is the opt-in provenance/cost-ledger counterpart to metering: where metering
+    records tokens, the transcript keeps the full request and response too, so a user
+    can later see, per call, what went in, what came back, and what it cost.
+    """
+
+    @abstractmethod
+    def record(self, call: TranscriptCall) -> None:
+        """Persist one call's request, response, and usage."""

generic_ml_wrapper/application/port/outbound/usage_store.py

@@ -0,0 +1,32 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The outbound port for persisting metered usage."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class UsageStorePort(ABC):
+    """Persist and read per-session usage recorded from a client's status payload."""
+
+    @abstractmethod
+    def record_session_cost(self, job: str, session: str, cost_usd: float) -> None:
+        """Record a session's cumulative cost (monotonic: the highest seen wins).
+
+        Args:
+            job: The job the session belongs to.
+            session: The session id.
+            cost_usd: The session's cumulative cost in USD.
+        """
+
+    @abstractmethod
+    def session_costs(self, job: str) -> dict[str, float]:
+        """Return the recorded cost per session for a job.
+
+        Args:
+            job: The job identifier.
+
+        Returns:
+            A mapping of session id to cumulative cost (empty if none recorded).
+        """