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

generic_ml_wrapper/application/port/outbound/workflow_source.py

@@ -0,0 +1,58 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The outbound port for reading, seeding, and compiling workflows."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class WorkflowSourcePort(ABC):
+    """Seed default workflows, check/create workflow folders, and compile context."""
+
+    @abstractmethod
+    def seed(self) -> None:
+        """Copy the packaged default workflows into the user's home, missing-only."""
+
+    @abstractmethod
+    def names(self) -> list[str]:
+        """Return the names of the runnable workflows, sorted.
+
+        Excludes the shared base and the create-workflow meta-workflow.
+
+        Returns:
+            The runnable workflow names (empty if none exist).
+        """
+
+    @abstractmethod
+    def exists(self, name: str) -> bool:
+        """Return whether a runnable workflow exists.
+
+        Args:
+            name: The workflow name.
+
+        Returns:
+            ``True`` if the workflow has a ``workflow.md``.
+        """
+
+    @abstractmethod
+    def create(self, name: str) -> str:
+        """Create an empty folder for a new workflow.
+
+        Args:
+            name: The workflow name.
+
+        Returns:
+            The absolute path to the created folder.
+        """
+
+    @abstractmethod
+    def compile(self, name: str) -> str:
+        """Compile a workflow's operating context.
+
+        Args:
+            name: The workflow name.
+
+        Returns:
+            The shared base followed by the workflow's steps.
+        """

generic_ml_wrapper/application/port/outbound/workspace.py

@@ -0,0 +1,27 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The outbound port for inspecting the working environment."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from generic_ml_wrapper.application.domain.model.workspace import Workspace
+
+
+class WorkspaceInspectorPort(ABC):
+    """Report the run's working environment (folder and git state).
+
+    This is client-agnostic: the wrapper computes these facts itself rather than
+    reading them from a client's payload, so every client's status line carries
+    them identically.
+    """
+
+    @abstractmethod
+    def inspect(self) -> Workspace:
+        """Inspect the current working environment.
+
+        Returns:
+            The working directory and git state (fields the environment does not
+            provide are ``None``; ``dirty`` is ``0`` when clean or unknown).
+        """

generic_ml_wrapper/application/usecase/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Use-case implementations; depend only on ports."""

generic_ml_wrapper/application/usecase/bootstrap.py

@@ -0,0 +1,24 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The Bootstrap use case: ensure the runtime layout exists."""
+
+from __future__ import annotations
+
+from generic_ml_wrapper.application.port.inbound.bootstrap import Bootstrap
+from generic_ml_wrapper.application.port.outbound.layout_seeder import LayoutSeederPort
+
+
+class BootstrapUseCase(Bootstrap):
+    """Ensure the runtime layout by delegating to a layout seeder."""
+
+    def __init__(self, seeder: LayoutSeederPort) -> None:
+        """Wire the use case to its outbound seeder.
+
+        Args:
+            seeder: The seeder that creates missing directories and the config.
+        """
+        self._seeder = seeder
+
+    def execute(self) -> None:
+        """Ensure the runtime layout exists (idempotent, missing-only)."""
+        self._seeder.ensure()

generic_ml_wrapper/application/usecase/export_usage.py

@@ -0,0 +1,93 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The ExportUsage use case: assemble a job's usage report."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from generic_ml_wrapper.application.port.inbound.export_usage import (
+    ExportUsage,
+    ModelTotal,
+    SessionCost,
+    TurnRow,
+    UsageReport,
+)
+from generic_ml_wrapper.application.port.outbound.per_turn_metering import PerTurnMeteringPort
+from generic_ml_wrapper.application.port.outbound.usage_store import UsageStorePort
+
+if TYPE_CHECKING:
+    from generic_ml_wrapper.application.domain.model.turn_usage import TurnUsage
+
+_UNKNOWN_MODEL = "(unknown)"
+
+
+class ExportUsageUseCase(ExportUsage):
+    """Assemble a job's usage report from the per-turn store and the session-cost store."""
+
+    def __init__(self, usage: UsageStorePort, turns: PerTurnMeteringPort) -> None:
+        """Wire the use case to its usage stores.
+
+        Args:
+            usage: The per-session cost store (from the status line).
+            turns: The per-turn token store (from a metering gateway).
+        """
+        self._usage = usage
+        self._turns = turns
+
+    def execute(self, job: str) -> UsageReport:
+        """Build a job's usage report.
+
+        Args:
+            job: The job identifier.
+
+        Returns:
+            Per-turn rows (chronological), per-model totals, per-session cost, and
+            job totals.
+        """
+        recorded = self._turns.turns_for_job(job)
+        turns = tuple(sorted((_row(turn) for turn in recorded), key=lambda row: row.timestamp))
+        models = _model_totals(recorded)
+        costs = self._usage.session_costs(job)
+        session_costs = tuple(SessionCost(session, costs[session]) for session in sorted(costs))
+        return UsageReport(
+            job=job,
+            turns=turns,
+            models=models,
+            session_costs=session_costs,
+            turn_count=len(recorded),
+            input_tokens=sum(model.input_tokens for model in models),
+            output_tokens=sum(model.output_tokens for model in models),
+            cache_tokens=sum(model.cache_tokens for model in models),
+            duration_s=round(sum(model.duration_s for model in models), 1),
+            total_usd=round(sum(cost.cost_usd for cost in session_costs), 2),
+        )
+
+
+def _row(turn: TurnUsage) -> TurnRow:
+    return TurnRow(
+        timestamp=turn.timestamp,
+        model=turn.model or _UNKNOWN_MODEL,
+        duration_s=turn.duration_s,
+        input_tokens=turn.input_tokens,
+        output_tokens=turn.output_tokens,
+        cache_tokens=turn.cache_creation_tokens + turn.cache_read_tokens,
+        turn_id=turn.turn_id,
+    )
+
+
+def _model_totals(recorded: list[TurnUsage]) -> tuple[ModelTotal, ...]:
+    # model -> [calls, input, output, cache, duration]
+    totals: dict[str, list[float]] = {}
+    for turn in recorded:
+        model = turn.model or _UNKNOWN_MODEL
+        acc = totals.setdefault(model, [0, 0, 0, 0, 0.0])
+        acc[0] += 1
+        acc[1] += turn.input_tokens
+        acc[2] += turn.output_tokens
+        acc[3] += turn.cache_creation_tokens + turn.cache_read_tokens
+        acc[4] += turn.duration_s
+    return tuple(
+        ModelTotal(model, int(a[0]), int(a[1]), int(a[2]), int(a[3]), round(a[4], 1))
+        for model, a in sorted(totals.items())
+    )

generic_ml_wrapper/application/usecase/list_jobs.py

@@ -0,0 +1,31 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The ListJobs use case: summarise each job's recorded sessions."""
+
+from __future__ import annotations
+
+from generic_ml_wrapper.application.port.inbound.list_jobs import JobSummary, ListJobs
+from generic_ml_wrapper.application.port.outbound.session_store import SessionStorePort
+
+
+class ListJobsUseCase(ListJobs):
+    """Summarise each job that has recorded sessions."""
+
+    def __init__(self, store: SessionStorePort) -> None:
+        """Wire the use case to the session store.
+
+        Args:
+            store: Where jobs and their sessions are read from.
+        """
+        self._store = store
+
+    def execute(self) -> list[JobSummary]:
+        """List the jobs with recorded activity.
+
+        Returns:
+            One summary per job, sorted by job id.
+        """
+        return [
+            JobSummary(job=job, session_count=len(self._store.ids_for_job(job)))
+            for job in self._store.jobs()
+        ]

generic_ml_wrapper/application/usecase/list_sessions.py

@@ -0,0 +1,34 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The ListSessions use case: summarise a job's recorded sessions."""
+
+from __future__ import annotations
+
+from generic_ml_wrapper.application.port.inbound.list_sessions import ListSessions, SessionSummary
+from generic_ml_wrapper.application.port.outbound.session_store import SessionStorePort
+
+
+class ListSessionsUseCase(ListSessions):
+    """Summarise the sessions recorded for a job."""
+
+    def __init__(self, store: SessionStorePort) -> None:
+        """Wire the use case to the session store.
+
+        Args:
+            store: Where the job's sessions are read from.
+        """
+        self._store = store
+
+    def execute(self, job: str) -> list[SessionSummary]:
+        """List a job's sessions.
+
+        Args:
+            job: The job identifier.
+
+        Returns:
+            One summary per session, oldest first.
+        """
+        return [
+            SessionSummary(session_id=session.session_id, client=session.client)
+            for session in self._store.sessions_for_job(job)
+        ]

generic_ml_wrapper/application/usecase/list_workflows.py

@@ -0,0 +1,28 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The ListWorkflows use case: the runnable workflow names."""
+
+from __future__ import annotations
+
+from generic_ml_wrapper.application.port.inbound.list_workflows import ListWorkflows
+from generic_ml_wrapper.application.port.outbound.workflow_source import WorkflowSourcePort
+
+
+class ListWorkflowsUseCase(ListWorkflows):
+    """List the runnable workflows from the workflow source."""
+
+    def __init__(self, workflows: WorkflowSourcePort) -> None:
+        """Wire the use case to the workflow source.
+
+        Args:
+            workflows: Where the workflows are read from.
+        """
+        self._workflows = workflows
+
+    def execute(self) -> list[str]:
+        """List the runnable workflow names.
+
+        Returns:
+            The workflow names, sorted (empty if none exist).
+        """
+        return self._workflows.names()

generic_ml_wrapper/application/usecase/new_workflow.py

@@ -0,0 +1,109 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The NewWorkflow use case: author a workflow via the create-workflow interview."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from generic_ml_wrapper.application.domain.model.identifiers import IdentifierError, WorkflowName
+from generic_ml_wrapper.application.domain.model.run import RunContext
+from generic_ml_wrapper.application.domain.model.session import Session
+from generic_ml_wrapper.application.domain.service.session_naming import next_session_id
+from generic_ml_wrapper.application.port.inbound.new_workflow import (
+    NewWorkflow,
+    NewWorkflowCommand,
+    WorkflowExistsError,
+    WorkflowNameError,
+)
+from generic_ml_wrapper.application.port.outbound.cli_caller import CliCallerProvider
+from generic_ml_wrapper.application.port.outbound.session_store import SessionStorePort
+from generic_ml_wrapper.application.port.outbound.workflow_source import WorkflowSourcePort
+
+_META = "create-workflow"
+_RESERVED = frozenset({_META, "_common"})
+
+
+class NewWorkflowUseCase(NewWorkflow):
+    """Create a workflow folder and run the create-workflow authoring session."""
+
+    def __init__(
+        self,
+        workflows: WorkflowSourcePort,
+        store: SessionStorePort,
+        callers: CliCallerProvider,
+        uuid_factory: Callable[[], str],
+    ) -> None:
+        """Wire the use case to its outbound ports.
+
+        Args:
+            workflows: Seeds, checks, creates, and compiles workflows.
+            store: Records the authoring session.
+            callers: Resolves the client caller for the run.
+            uuid_factory: Mints a client-side session uuid.
+        """
+        self._workflows = workflows
+        self._store = store
+        self._callers = callers
+        self._uuid_factory = uuid_factory
+
+    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.
+        """
+        name = command.name
+        try:
+            WorkflowName(name)
+        except IdentifierError as error:
+            raise WorkflowNameError(str(error)) from error
+        if name in _RESERVED:
+            message = f"reserved workflow name: {name!r}"
+            raise WorkflowNameError(message)
+        self._workflows.seed()
+        if self._workflows.exists(name):
+            message = f"workflow already exists: {name!r}"
+            raise WorkflowExistsError(message)
+
+        folder = self._workflows.create(name)
+        # The authoring session's store is rooted apart from real work jobs (the
+        # composition root injects the authoring root), so the job is just the
+        # workflow name — no prefix, no folder-name collision with a real job.
+        job = name
+        session = Session(
+            session_id=next_session_id(job, self._store.ids_for_job(job)),
+            job=job,
+            client=command.client,
+            uuid=self._uuid_factory(),
+        )
+        self._store.record(session)
+
+        run = RunContext(
+            job=job,
+            session_id=session.session_id,
+            client=session.client,
+            uuid=session.uuid,
+            resume=False,
+            cwd=folder,
+            context=self._workflows.compile(_META),
+            kickoff=(
+                f"You are creating a new workflow named {name!r}. Your working "
+                f"directory is its folder ({folder}); write the new workflow.md there. "
+                "Follow the create-workflow steps: interview me, then draft and save "
+                "the workflow. Start by asking what this workflow is for."
+            ),
+        )
+        caller = self._callers.for_run(run)
+        caller.start_metering()
+        try:
+            return caller.start_client()
+        finally:
+            caller.end_metering()

generic_ml_wrapper/application/usecase/render_statusline.py

@@ -0,0 +1,117 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The RenderStatusline use case: parse a client payload, record usage, render."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, cast
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from generic_ml_wrapper.application.domain.model.turn_usage import TurnUsage
+
+from generic_ml_wrapper.application.domain.service.statusline_renderer import (
+    render_statusline,
+    render_usage_row,
+)
+from generic_ml_wrapper.application.port.inbound.render_statusline import RenderStatusline
+from generic_ml_wrapper.application.port.outbound.client_status import ClientStatusParserPort
+from generic_ml_wrapper.application.port.outbound.per_turn_metering import PerTurnMeteringPort
+from generic_ml_wrapper.application.port.outbound.usage_store import UsageStorePort
+from generic_ml_wrapper.application.port.outbound.workspace import WorkspaceInspectorPort
+
+
+class RenderStatuslineUseCase(RenderStatusline):
+    """Parse the client's status payload, record its session cost, and render a line."""
+
+    def __init__(
+        self,
+        parser: ClientStatusParserPort,
+        usage: UsageStorePort,
+        workspace: WorkspaceInspectorPort,
+        turns: PerTurnMeteringPort,
+    ) -> None:
+        """Wire the use case to its outbound ports.
+
+        Args:
+            parser: The client's status-payload parser.
+            usage: Where recorded session cost is persisted and read.
+            workspace: The inspector for the client-agnostic environment facts.
+            turns: The per-turn store, read for the job's cumulative usage footer.
+        """
+        self._parser = parser
+        self._usage = usage
+        self._workspace = workspace
+        self._turns = turns
+
+    def execute(self, payload_json: str, job: str | None, session: str | None) -> str:
+        """Parse the payload, record usage, and render the status line.
+
+        The live status is the first line; when a job is active, its cumulative
+        usage (turns · tokens · cost across sessions) is appended as a footer row.
+
+        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 (one or two lines) to print.
+        """
+        status = self._parser.parse(_decode(payload_json))
+        if job and session and status.session_cost_usd is not None:
+            self._usage.record_session_cost(job, session, status.session_cost_usd)
+        line = render_statusline(status, self._workspace.inspect())
+        footer = self._usage_footer(job, session) if job else ""
+        if not footer:
+            return line
+        return f"{line}\n{footer}" if line else footer
+
+    def _usage_footer(self, job: str, session: str | None) -> str:
+        """The usage rows below the live line: session, then job total across sessions.
+
+        The current session's usage comes first; the whole-job total is added only when
+        the job spans other sessions. Empty when the job has no recorded activity.
+        """
+        turns = self._turns.turns_for_job(job)
+        costs = self._usage.session_costs(job)
+        if not turns and not costs:
+            return ""
+        rows: list[str] = []
+        if session is not None:
+            session_turns = [turn for turn in turns if turn.session_id == session]
+            rows.append(
+                render_usage_row(
+                    "session",
+                    session,
+                    len(session_turns),
+                    _tokens(session_turns),
+                    costs.get(session, 0.0),
+                )
+            )
+            spans_other_sessions = any(turn.session_id != session for turn in turns) or any(
+                other != session for other in costs
+            )
+            if not spans_other_sessions:
+                return rows[0]
+        rows.append(
+            render_usage_row("job", job, len(turns), _tokens(turns), round(sum(costs.values()), 2))
+        )
+        return "\n".join(rows)
+
+
+def _tokens(turns: Sequence[TurnUsage]) -> int:
+    return sum(
+        turn.input_tokens + turn.output_tokens + turn.cache_creation_tokens + turn.cache_read_tokens
+        for turn in turns
+    )
+
+
+def _decode(payload_json: str) -> dict[str, object]:
+    try:
+        decoded: object = json.loads(payload_json)
+    except (json.JSONDecodeError, ValueError):
+        return {}
+    return cast("dict[str, object]", decoded) if isinstance(decoded, dict) else {}

generic_ml_wrapper/application/usecase/set_credential.py

@@ -0,0 +1,27 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The SetCredential use case: store a workflow credential."""
+
+from __future__ import annotations
+
+from generic_ml_wrapper.application.port.inbound.set_credential import (
+    SetCredential,
+    SetCredentialCommand,
+)
+from generic_ml_wrapper.application.port.outbound.credentials_store import CredentialsStorePort
+
+
+class SetCredentialUseCase(SetCredential):
+    """Store a workflow credential via the credentials store."""
+
+    def __init__(self, store: CredentialsStorePort) -> None:
+        """Wire the use case to the credentials store.
+
+        Args:
+            store: Where the credential is persisted.
+        """
+        self._store = store
+
+    def execute(self, command: SetCredentialCommand) -> None:
+        """Store the credential described by the command."""
+        self._store.set(command.workflow, command.name, command.value)

generic_ml_wrapper/application/usecase/start_job.py

@@ -0,0 +1,125 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The StartJob use case: resolve a session, record it, run the client."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import replace
+
+from generic_ml_wrapper.application.domain.model.run import RunContext
+from generic_ml_wrapper.application.domain.model.session import Session
+from generic_ml_wrapper.application.domain.service.session_naming import next_session_id
+from generic_ml_wrapper.application.port.inbound.start_job import (
+    ResumeNotSupportedError,
+    StartJob,
+    StartJobCommand,
+    UnknownWorkflowError,
+)
+from generic_ml_wrapper.application.port.outbound.cli_caller import CliCallerProvider
+from generic_ml_wrapper.application.port.outbound.credentials_store import CredentialsStorePort
+from generic_ml_wrapper.application.port.outbound.session_store import SessionStorePort
+from generic_ml_wrapper.application.port.outbound.workflow_source import WorkflowSourcePort
+
+
+class StartJobUseCase(StartJob):
+    """Resolve a session (new or resumed), optionally attach a workflow, run it."""
+
+    def __init__(
+        self,
+        store: SessionStorePort,
+        workflows: WorkflowSourcePort,
+        callers: CliCallerProvider,
+        uuid_factory: Callable[[], str],
+        credentials: CredentialsStorePort,
+    ) -> None:
+        """Wire the use case to its outbound ports.
+
+        Args:
+            store: Where sessions are persisted and read.
+            workflows: Seeds, checks, and compiles workflows.
+            callers: Resolves the client caller for a run.
+            uuid_factory: Mints a client-side session uuid for new sessions.
+            credentials: Resolves a workflow's credentials to export at launch.
+        """
+        self._store = store
+        self._workflows = workflows
+        self._callers = callers
+        self._uuid_factory = uuid_factory
+        self._credentials = credentials
+
+    def execute(self, command: StartJobCommand) -> int:
+        """Resolve the session, optionally inject a workflow, run the client.
+
+        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.
+        """
+        run, session = self._resolve(command)
+        if command.workflow is not None and not run.resume:
+            run = self._attach_workflow(run, command.workflow)
+        caller = self._callers.for_run(run)
+        if run.resume and not caller.can_resume():
+            message = f"session resume not supported on {run.client}"
+            raise ResumeNotSupportedError(message)
+        # Persist only once every precondition (workflow, caller, resume) has passed, so
+        # a rejected start never leaves a ghost session that burns an id and could be resumed.
+        if session is not None:
+            self._store.record(session)
+        caller.start_metering()
+        try:
+            return caller.start_client()
+        finally:
+            caller.end_metering()
+
+    def _attach_workflow(self, run: RunContext, workflow: str) -> RunContext:
+        self._workflows.seed()
+        if not self._workflows.exists(workflow):
+            message = f"unknown workflow: {workflow!r}"
+            raise UnknownWorkflowError(message)
+        kickoff = (
+            f"You are running the {workflow!r} workflow for {run.job}. Orient first — "
+            "read your context, look at what already exists, report where things stand, "
+            "then stop and wait. Do not start executing steps yet."
+        )
+        return replace(
+            run,
+            context=self._workflows.compile(workflow),
+            kickoff=kickoff,
+            env=tuple(self._credentials.resolve(workflow).items()),
+        )
+
+    def _resolve(self, command: StartJobCommand) -> tuple[RunContext, Session | None]:
+        """Mint the run (and the session to record, or ``None`` on resume) -- no write yet."""
+        if command.resume_latest:
+            latest = self._store.latest_for_job(command.job)
+            if latest is not None:
+                resumed = RunContext(
+                    job=latest.job,
+                    session_id=latest.session_id,
+                    client=latest.client,
+                    uuid=latest.uuid,
+                    resume=True,
+                )
+                return resumed, None
+        session = Session(
+            session_id=next_session_id(command.job, self._store.ids_for_job(command.job)),
+            job=command.job,
+            client=command.client,
+            uuid=self._uuid_factory(),
+        )
+        run = RunContext(
+            job=session.job,
+            session_id=session.session_id,
+            client=session.client,
+            uuid=session.uuid,
+            resume=False,
+        )
+        return run, session