codealmanac 0.1.0.dev0__py3-none-any.whl

codealmanac/workflows/garden/requests.py

@@ -0,0 +1,22 @@
+from pathlib import Path
+
+from pydantic import field_validator
+
+from codealmanac.core.models import CodeAlmanacModel
+from codealmanac.core.text import required_text
+from codealmanac.services.harnesses.models import HarnessKind
+
+
+class RunGardenRequest(CodeAlmanacModel):
+    cwd: Path
+    harness: HarnessKind
+    wiki: str | None = None
+    title: str | None = None
+    guidance: str | None = None
+
+    @field_validator("title", "guidance")
+    @classmethod
+    def require_optional_text(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        return required_text(value, "garden request text")

codealmanac/workflows/garden/service.py

@@ -0,0 +1,239 @@
+from contextlib import suppress
+from pathlib import Path
+
+from codealmanac.prompts import PromptName, PromptRenderer, RenderPromptRequest
+from codealmanac.services.harnesses.models import HarnessRunResult
+from codealmanac.services.harnesses.requests import RunHarnessRequest
+from codealmanac.services.harnesses.service import HarnessesService
+from codealmanac.services.health.requests import HealthCheckRequest
+from codealmanac.services.health.service import HealthService
+from codealmanac.services.index.models import HealthReport, IndexSummary
+from codealmanac.services.index.service import IndexService
+from codealmanac.services.runs.models import RunEventKind, RunOperation, RunStatus
+from codealmanac.services.runs.requests import (
+    FinishRunRequest,
+    MarkRunRunningRequest,
+    RecordRunEventRequest,
+    RecordRunHarnessTranscriptRequest,
+    StartRunRequest,
+)
+from codealmanac.services.runs.service import RunsService
+from codealmanac.services.workspaces.models import Workspace
+from codealmanac.services.workspaces.requests import SelectWorkspaceRequest
+from codealmanac.services.workspaces.service import WorkspacesService
+from codealmanac.workflows.garden.models import GardenPromptPayload, GardenResult
+from codealmanac.workflows.garden.requests import RunGardenRequest
+from codealmanac.workflows.lifecycle import (
+    LifecycleMutationPolicy,
+    first_line,
+    harness_events,
+    harness_run_event_kind,
+    validate_harness_result,
+)
+
+GARDEN_PROMPT_SECTIONS = (
+    PromptName.BASE_PURPOSE,
+    PromptName.BASE_NOTABILITY,
+    PromptName.BASE_SYNTAX,
+    PromptName.OPERATION_GARDEN,
+)
+
+
+class GardenWorkflow:
+    def __init__(
+        self,
+        workspaces: WorkspacesService,
+        harnesses: HarnessesService,
+        runs: RunsService,
+        index: IndexService,
+        health: HealthService,
+        mutation_policy: LifecycleMutationPolicy,
+        prompts: PromptRenderer,
+    ):
+        self.workspaces = workspaces
+        self.harnesses = harnesses
+        self.runs = runs
+        self.index = index
+        self.health = health
+        self.mutation_policy = mutation_policy
+        self.prompts = prompts
+
+    def run(self, request: RunGardenRequest) -> GardenResult:
+        workspace = self.resolve_workspace(request.cwd, request.wiki)
+        started = self.runs.start(
+            StartRunRequest(
+                cwd=request.cwd,
+                wiki=request.wiki,
+                operation=RunOperation.GARDEN,
+                title=request.title or "Garden wiki",
+            )
+        )
+        self.runs.mark_running(
+            MarkRunRunningRequest(
+                cwd=request.cwd,
+                wiki=request.wiki,
+                run_id=started.run_id,
+            )
+        )
+        try:
+            index_before = self.index.summary(workspace.workspace_id)
+            health_before = self.health.check(
+                HealthCheckRequest(cwd=request.cwd, wiki=request.wiki)
+            )
+            self.record(
+                request,
+                started.run_id,
+                RunEventKind.MESSAGE,
+                "prepared garden context",
+            )
+            preflight = self.mutation_policy.preflight(workspace)
+            self.record(
+                request,
+                started.run_id,
+                RunEventKind.MESSAGE,
+                f"verified clean {workspace.almanac_root.as_posix()} preflight",
+            )
+            harness = self.harnesses.run(
+                RunHarnessRequest(
+                    kind=request.harness,
+                    cwd=workspace.root_path,
+                    prompt=render_garden_prompt(
+                        self.prompts,
+                        workspace,
+                        index_before,
+                        health_before,
+                        request.guidance,
+                    ),
+                    title=request.title,
+                )
+            )
+            self.record_harness_transcript(request, started.run_id, harness)
+            self.record_harness(request, started.run_id, harness)
+            safety = self.mutation_policy.validate(
+                preflight,
+                workspace,
+                harness.changed_files,
+            )
+            validate_harness_result(harness)
+            index_after = self.index.ensure_fresh(workspace.workspace_id)
+            finished = self.runs.finish(
+                FinishRunRequest(
+                    cwd=request.cwd,
+                    wiki=request.wiki,
+                    run_id=started.run_id,
+                    status=RunStatus.DONE,
+                    summary=harness.summary or "garden completed",
+                )
+            )
+            return GardenResult(
+                run=finished,
+                harness=harness,
+                safety=safety,
+                index=index_after,
+                health_before=health_before,
+            )
+        except Exception as error:
+            self.fail_run(request, started.run_id, error)
+            raise
+
+    def resolve_workspace(self, cwd: Path, wiki: str | None) -> Workspace:
+        if wiki is None:
+            return self.workspaces.resolve(cwd)
+        return self.workspaces.select(
+            SelectWorkspaceRequest(selector=wiki, base_path=cwd)
+        )
+
+    def record(
+        self,
+        request: RunGardenRequest,
+        run_id: str,
+        kind: RunEventKind,
+        message: str,
+    ) -> None:
+        self.runs.record_event(
+            RecordRunEventRequest(
+                cwd=request.cwd,
+                wiki=request.wiki,
+                run_id=run_id,
+                kind=kind,
+                message=message,
+            )
+        )
+
+    def record_harness_transcript(
+        self,
+        request: RunGardenRequest,
+        run_id: str,
+        harness: HarnessRunResult,
+    ) -> None:
+        if harness.transcript is None:
+            return
+        self.runs.record_harness_transcript(
+            RecordRunHarnessTranscriptRequest(
+                cwd=request.cwd,
+                wiki=request.wiki,
+                run_id=run_id,
+                transcript=harness.transcript,
+            )
+        )
+
+    def record_harness(
+        self,
+        request: RunGardenRequest,
+        run_id: str,
+        harness: HarnessRunResult,
+    ) -> None:
+        for event in harness_events(harness):
+            self.record(
+                request,
+                run_id,
+                harness_run_event_kind(event),
+                event.message,
+            )
+
+    def fail_run(
+        self,
+        request: RunGardenRequest,
+        run_id: str,
+        error: Exception,
+    ) -> None:
+        message = first_line(str(error)) or error.__class__.__name__
+        with suppress(Exception):
+            self.record(request, run_id, RunEventKind.ERROR, message)
+            self.runs.finish(
+                FinishRunRequest(
+                    cwd=request.cwd,
+                    wiki=request.wiki,
+                    run_id=run_id,
+                    status=RunStatus.FAILED,
+                    error=message,
+                )
+            )
+
+
+def render_garden_prompt(
+    prompts: PromptRenderer,
+    workspace: Workspace,
+    index: IndexSummary,
+    health: HealthReport,
+    guidance: str | None,
+) -> str:
+    payload = GardenPromptPayload(
+        workspace_name=workspace.name,
+        workspace_root=workspace.root_path,
+        almanac_root=workspace.almanac_path,
+        pages_root=workspace.almanac_path / "pages",
+        topics_file=workspace.almanac_path / "topics.yaml",
+        index=index,
+        health=health,
+        guidance=guidance,
+    )
+    return prompts.render(
+        RenderPromptRequest(
+            sections=GARDEN_PROMPT_SECTIONS,
+            context=(
+                "Runtime context:\n"
+                f"{payload.model_dump_json(indent=2)}\n",
+            ),
+        )
+    )

codealmanac/workflows/ingest/__init__.py

@@ -0,0 +1 @@
+"""Ingest workflow orchestration."""

codealmanac/workflows/ingest/models.py

@@ -0,0 +1,26 @@
+from pathlib import Path
+
+from codealmanac.core.models import CodeAlmanacModel
+from codealmanac.services.harnesses.models import HarnessRunResult
+from codealmanac.services.index.models import IndexRefreshResult
+from codealmanac.services.runs.models import RunRecord
+from codealmanac.services.sources.models import SourceBrief, SourceRuntime
+from codealmanac.workflows.lifecycle import LifecycleMutationReport
+
+
+class IngestPromptPayload(CodeAlmanacModel):
+    workspace_name: str
+    workspace_root: Path
+    almanac_root: Path
+    sources: tuple[SourceBrief, ...]
+    source_runtime: tuple[SourceRuntime, ...]
+    guidance: str | None = None
+
+
+class IngestResult(CodeAlmanacModel):
+    run: RunRecord
+    sources: tuple[SourceBrief, ...]
+    source_runtime: tuple[SourceRuntime, ...]
+    harness: HarnessRunResult
+    safety: LifecycleMutationReport
+    index: IndexRefreshResult

codealmanac/workflows/ingest/requests.py

@@ -0,0 +1,39 @@
+from pathlib import Path
+
+from pydantic import field_validator
+
+from codealmanac.core.models import CodeAlmanacModel
+from codealmanac.core.text import required_text
+from codealmanac.services.harnesses.models import HarnessKind
+
+
+class RunIngestRequest(CodeAlmanacModel):
+    cwd: Path
+    inputs: tuple[str, ...]
+    harness: HarnessKind
+    wiki: str | None = None
+    title: str | None = None
+    guidance: str | None = None
+
+    @field_validator("inputs")
+    @classmethod
+    def require_inputs(cls, value: tuple[str, ...]) -> tuple[str, ...]:
+        if len(value) == 0:
+            raise ValueError("at least one ingest input is required")
+        return value
+
+    @field_validator("title", "guidance")
+    @classmethod
+    def require_optional_text(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        return required_text(value, "ingest request text")
+
+
+class RunIngestWithRunRequest(RunIngestRequest):
+    run_id: str
+
+    @field_validator("run_id")
+    @classmethod
+    def require_run_id(cls, value: str) -> str:
+        return required_text(value, "ingest run id")

codealmanac/workflows/ingest/service.py

@@ -0,0 +1,302 @@
+from contextlib import suppress
+from pathlib import Path
+
+from codealmanac.prompts import PromptName, PromptRenderer, RenderPromptRequest
+from codealmanac.services.harnesses.models import HarnessRunResult
+from codealmanac.services.harnesses.requests import RunHarnessRequest
+from codealmanac.services.harnesses.service import HarnessesService
+from codealmanac.services.index.service import IndexService
+from codealmanac.services.runs.models import (
+    RunEventKind,
+    RunOperation,
+    RunRecord,
+    RunStatus,
+)
+from codealmanac.services.runs.requests import (
+    FinishRunRequest,
+    MarkRunRunningRequest,
+    RecordRunEventRequest,
+    RecordRunHarnessTranscriptRequest,
+    StartRunRequest,
+)
+from codealmanac.services.runs.service import RunsService
+from codealmanac.services.sources.models import SourceBrief, SourceRuntime
+from codealmanac.services.sources.requests import (
+    InspectSourceRuntimeRequest,
+    ResolveSourcesRequest,
+    SourceRuntimeContext,
+)
+from codealmanac.services.sources.service import SourcesService
+from codealmanac.services.workspaces.models import Workspace
+from codealmanac.services.workspaces.requests import SelectWorkspaceRequest
+from codealmanac.services.workspaces.service import WorkspacesService
+from codealmanac.workflows.ingest.models import IngestPromptPayload, IngestResult
+from codealmanac.workflows.ingest.requests import (
+    RunIngestRequest,
+    RunIngestWithRunRequest,
+)
+from codealmanac.workflows.lifecycle import (
+    LifecycleMutationPolicy,
+    first_line,
+    harness_events,
+    harness_run_event_kind,
+    validate_harness_result,
+)
+
+INGEST_PROMPT_SECTIONS = (
+    PromptName.BASE_PURPOSE,
+    PromptName.BASE_NOTABILITY,
+    PromptName.BASE_SYNTAX,
+    PromptName.OPERATION_INGEST,
+)
+
+
+class IngestWorkflow:
+    def __init__(
+        self,
+        workspaces: WorkspacesService,
+        sources: SourcesService,
+        harnesses: HarnessesService,
+        runs: RunsService,
+        index: IndexService,
+        mutation_policy: LifecycleMutationPolicy,
+        prompts: PromptRenderer,
+    ):
+        self.workspaces = workspaces
+        self.sources = sources
+        self.harnesses = harnesses
+        self.runs = runs
+        self.index = index
+        self.mutation_policy = mutation_policy
+        self.prompts = prompts
+
+    def run(self, request: RunIngestRequest) -> IngestResult:
+        started = self.start(request)
+        return self.run_with_run(
+            RunIngestWithRunRequest(
+                cwd=request.cwd,
+                inputs=request.inputs,
+                harness=request.harness,
+                wiki=request.wiki,
+                title=request.title,
+                guidance=request.guidance,
+                run_id=started.run_id,
+            )
+        )
+
+    def start(self, request: RunIngestRequest) -> RunRecord:
+        return self.runs.start(
+            StartRunRequest(
+                cwd=request.cwd,
+                wiki=request.wiki,
+                operation=RunOperation.INGEST,
+                title=request.title or default_title(request.inputs),
+            )
+        )
+
+    def run_with_run(self, request: RunIngestWithRunRequest) -> IngestResult:
+        workspace = self.resolve_workspace(request.cwd, request.wiki)
+        run_id = request.run_id
+        try:
+            self.runs.mark_running(
+                MarkRunRunningRequest(
+                    cwd=request.cwd,
+                    wiki=request.wiki,
+                    run_id=run_id,
+                )
+            )
+            preflight = self.mutation_policy.preflight(workspace)
+            self.record(
+                request,
+                run_id,
+                RunEventKind.MESSAGE,
+                f"verified clean {workspace.almanac_root.as_posix()} preflight",
+            )
+            sources = self.sources.resolve(
+                ResolveSourcesRequest(cwd=request.cwd, inputs=request.inputs)
+            )
+            self.record(
+                request,
+                run_id,
+                RunEventKind.MESSAGE,
+                f"resolved {len(sources)} {source_word(len(sources))}",
+            )
+            source_runtime = self.inspect_source_runtime(workspace, sources)
+            self.record(
+                request,
+                run_id,
+                RunEventKind.MESSAGE,
+                f"loaded {len(source_runtime)} source runtime snapshot"
+                f"{'' if len(source_runtime) == 1 else 's'}",
+            )
+            harness = self.harnesses.run(
+                RunHarnessRequest(
+                    kind=request.harness,
+                    cwd=workspace.root_path,
+                    prompt=render_ingest_prompt(
+                        self.prompts,
+                        workspace,
+                        sources,
+                        source_runtime,
+                        request.guidance,
+                    ),
+                    title=request.title,
+                )
+            )
+            self.record_harness_transcript(request, run_id, harness)
+            self.record_harness_events(request, run_id, harness)
+            safety = self.mutation_policy.validate(
+                preflight,
+                workspace,
+                harness.changed_files,
+            )
+            validate_harness_result(harness)
+            index = self.index.ensure_fresh(workspace.workspace_id)
+            finished = self.runs.finish(
+                FinishRunRequest(
+                    cwd=request.cwd,
+                    wiki=request.wiki,
+                    run_id=run_id,
+                    status=RunStatus.DONE,
+                    summary=harness.summary or "ingest completed",
+                )
+            )
+            return IngestResult(
+                run=finished,
+                sources=sources,
+                source_runtime=source_runtime,
+                harness=harness,
+                safety=safety,
+                index=index,
+            )
+        except Exception as error:
+            self.fail_run(request, run_id, error)
+            raise
+
+    def resolve_workspace(self, cwd: Path, wiki: str | None) -> Workspace:
+        if wiki is None:
+            return self.workspaces.resolve(cwd)
+        return self.workspaces.select(
+            SelectWorkspaceRequest(selector=wiki, base_path=cwd)
+        )
+
+    def record(
+        self,
+        request: RunIngestRequest,
+        run_id: str,
+        kind: RunEventKind,
+        message: str,
+    ) -> None:
+        self.runs.record_event(
+            RecordRunEventRequest(
+                cwd=request.cwd,
+                wiki=request.wiki,
+                run_id=run_id,
+                kind=kind,
+                message=message,
+            )
+        )
+
+    def record_harness_transcript(
+        self,
+        request: RunIngestRequest,
+        run_id: str,
+        harness: HarnessRunResult,
+    ) -> None:
+        if harness.transcript is None:
+            return
+        self.runs.record_harness_transcript(
+            RecordRunHarnessTranscriptRequest(
+                cwd=request.cwd,
+                wiki=request.wiki,
+                run_id=run_id,
+                transcript=harness.transcript,
+            )
+        )
+
+    def record_harness_events(
+        self,
+        request: RunIngestRequest,
+        run_id: str,
+        harness: HarnessRunResult,
+    ) -> None:
+        for event in harness_events(harness):
+            self.record(
+                request,
+                run_id,
+                harness_run_event_kind(event),
+                event.message,
+            )
+
+    def inspect_source_runtime(
+        self,
+        workspace: Workspace,
+        sources: tuple[SourceBrief, ...],
+    ) -> tuple[SourceRuntime, ...]:
+        return tuple(
+            self.sources.inspect_runtime(
+                InspectSourceRuntimeRequest(
+                    cwd=workspace.root_path,
+                    ref=source.ref,
+                    context=SourceRuntimeContext(
+                        ignored_directories=(workspace.almanac_root,)
+                    ),
+                )
+            )
+            for source in sources
+        )
+
+    def fail_run(
+        self,
+        request: RunIngestRequest,
+        run_id: str,
+        error: Exception,
+    ) -> None:
+        message = first_line(str(error)) or error.__class__.__name__
+        with suppress(Exception):
+            self.record(request, run_id, RunEventKind.ERROR, message)
+            self.runs.finish(
+                FinishRunRequest(
+                    cwd=request.cwd,
+                    wiki=request.wiki,
+                    run_id=run_id,
+                    status=RunStatus.FAILED,
+                    error=message,
+                )
+            )
+
+
+def render_ingest_prompt(
+    prompts: PromptRenderer,
+    workspace: Workspace,
+    sources: tuple[SourceBrief, ...],
+    source_runtime: tuple[SourceRuntime, ...],
+    guidance: str | None,
+) -> str:
+    payload = IngestPromptPayload(
+        workspace_name=workspace.name,
+        workspace_root=workspace.root_path,
+        almanac_root=workspace.almanac_path,
+        sources=sources,
+        source_runtime=source_runtime,
+        guidance=guidance,
+    )
+    return prompts.render(
+        RenderPromptRequest(
+            sections=INGEST_PROMPT_SECTIONS,
+            context=(
+                "Runtime context:\n"
+                f"{payload.model_dump_json(indent=2)}\n",
+            ),
+        )
+    )
+
+
+def default_title(inputs: tuple[str, ...]) -> str:
+    if len(inputs) == 1:
+        return f"Ingest {inputs[0]}"
+    return f"Ingest {len(inputs)} sources"
+
+
+def source_word(count: int) -> str:
+    return "source" if count == 1 else "sources"