nexus-coding-agent 0.1.0__py3-none-any.whl

nexus/infrastructure/semantic.py

@@ -0,0 +1,276 @@
+"""Transactional exact pgvector retrieval and incremental indexing."""
+
+import asyncio
+from datetime import UTC, datetime
+from pathlib import Path
+from uuid import UUID, uuid4
+
+from sqlalchemy import delete, func, select, text
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from nexus.context.chunking import language_for, text_hash
+from nexus.domain.context import (
+    CodeChunk,
+    ContextCandidate,
+    EmbeddingConfig,
+    IndexCompatibility,
+    IndexCompatibilityStatus,
+    IndexRequest,
+    IndexResult,
+    RetrievalQuery,
+    RetrievalSource,
+)
+from nexus.domain.ports.context import Chunker, EmbeddingGateway
+from nexus.errors import ContextError
+from nexus.infrastructure.embedding import validate_vectors
+from nexus.infrastructure.repository_files import RepositoryFiles
+from nexus.infrastructure.semantic_models import SemanticChunkRow, SemanticIndexRow
+
+
+def _compatibility(row: SemanticIndexRow | None, config: EmbeddingConfig) -> IndexCompatibility:
+    if row is None:
+        return IndexCompatibility(
+            IndexCompatibilityStatus.INDEX_NOT_FOUND,
+            "Run nexus index to initialize semantic search.",
+        )
+    expected = (config.provider, config.model, config.dimension, "v1", "line_window_v1")
+    actual = (
+        row.embedding_provider,
+        row.embedding_model,
+        row.embedding_dimension,
+        row.index_version,
+        row.chunk_strategy_version,
+    )
+    if expected != actual:
+        return IndexCompatibility(
+            IndexCompatibilityStatus.INDEX_INCOMPATIBLE,
+            "Embedding/index configuration changed; run nexus index --rebuild.",
+        )
+    return IndexCompatibility(IndexCompatibilityStatus.COMPATIBLE, None)
+
+
+async def _lock(session: AsyncSession, repository_id: str, *, shared: bool = False) -> None:
+    operation = "pg_advisory_xact_lock_shared" if shared else "pg_advisory_xact_lock"
+    await session.execute(
+        text(f"SELECT {operation}(hashtextextended(:repository_id, 0))"),
+        {"repository_id": repository_id},
+    )
+
+
+class PgVectorSemanticSearchProvider:
+    def __init__(
+        self,
+        sessions: async_sessionmaker[AsyncSession],
+        embedding: EmbeddingGateway,
+    ) -> None:
+        self._sessions = sessions
+        self._embedding = embedding
+
+    async def validate_index(self, repository_id: str) -> IndexCompatibility:
+        try:
+            async with self._sessions() as session:
+                return _compatibility(
+                    await session.get(SemanticIndexRow, UUID(repository_id)),
+                    self._embedding.config,
+                )
+        except Exception as exc:
+            raise ContextError(
+                "Semantic index validation is unavailable.",
+                code="SEMANTIC_SEARCH_FAILED",
+                retryable=True,
+            ) from exc
+
+    async def search(self, query: RetrievalQuery) -> tuple[ContextCandidate, ...]:
+        try:
+            async with self._sessions() as session, session.begin():
+                await _lock(session, query.repository_id, shared=True)
+                compatible = _compatibility(
+                    await session.get(SemanticIndexRow, UUID(query.repository_id)),
+                    self._embedding.config,
+                )
+                if compatible.status is not IndexCompatibilityStatus.COMPATIBLE:
+                    raise ContextError(
+                        compatible.reason or "Index unavailable.", code=compatible.status.value
+                    )
+                vector = validate_vectors(
+                    (await self._embedding.embed_query(query.text),),
+                    1,
+                    self._embedding.config.dimension,
+                )[0]
+                distance = SemanticChunkRow.embedding.cosine_distance(list(vector))
+                rows = (
+                    await session.execute(
+                        select(SemanticChunkRow, distance.label("distance"))
+                        .where(SemanticChunkRow.repository_id == UUID(query.repository_id))
+                        .order_by(
+                            distance,
+                            SemanticChunkRow.file_path,
+                            SemanticChunkRow.start_line,
+                            SemanticChunkRow.content_hash,
+                        )
+                        .limit(min(query.limit, 20)),
+                    )
+                ).all()
+                return tuple(
+                    ContextCandidate(
+                        CodeChunk(
+                            row.file_path,
+                            row.language,
+                            row.symbol,
+                            row.start_line,
+                            row.end_line,
+                            row.content,
+                            row.content_hash,
+                            row.file_hash,
+                        ),
+                        None,
+                        rank,
+                        float(score),
+                        0.0,
+                        (RetrievalSource.SEMANTIC,),
+                    )
+                    for rank, (row, score) in enumerate(rows, 1)
+                )
+        except ContextError:
+            raise
+        except Exception as exc:
+            raise ContextError(
+                "Semantic query failed.", code="SEMANTIC_SEARCH_FAILED", retryable=True
+            ) from exc
+
+
+class PgVectorRepositoryIndexer:
+    def __init__(
+        self,
+        sessions: async_sessionmaker[AsyncSession],
+        embedding: EmbeddingGateway,
+        chunker: Chunker,
+        files: RepositoryFiles,
+    ) -> None:
+        self._sessions = sessions
+        self._embedding = embedding
+        self._chunker = chunker
+        self._files = files
+
+    async def index(self, request: IndexRequest) -> IndexResult:
+        try:
+            workspace = await asyncio.to_thread(Path(request.workspace_path).resolve)
+            if self._files.guard.root != workspace:
+                raise ValueError("Index workspace mismatch.")
+            async with self._sessions() as session, session.begin():
+                await _lock(session, request.repository_id)
+                repository = UUID(request.repository_id)
+                meta = await session.get(SemanticIndexRow, repository)
+                compatible = _compatibility(meta, self._embedding.config)
+                if (
+                    compatible.status is IndexCompatibilityStatus.INDEX_INCOMPATIBLE
+                    and not request.rebuild
+                ):
+                    raise ContextError(
+                        compatible.reason or "Rebuild required.", code="INDEX_INCOMPATIBLE"
+                    )
+                scan = await asyncio.to_thread(self._files.scan)
+                old = {
+                    path: file_hash
+                    for path, file_hash in (
+                        await session.execute(
+                            select(SemanticChunkRow.file_path, SemanticChunkRow.file_hash)
+                            .where(SemanticChunkRow.repository_id == repository)
+                            .distinct(),
+                        )
+                    ).all()
+                }
+                current = dict(scan.files)
+                removed = set(old) - current.keys()
+                changed = {
+                    path: content
+                    for path, content in current.items()
+                    if request.rebuild or old.get(path) != text_hash(content)
+                }
+                unchanged = len(current) - len(changed)
+                if request.rebuild:
+                    await session.execute(
+                        delete(SemanticChunkRow).where(
+                            SemanticChunkRow.repository_id == repository,
+                        )
+                    )
+                else:
+                    await session.execute(
+                        delete(SemanticChunkRow).where(
+                            SemanticChunkRow.repository_id == repository,
+                            SemanticChunkRow.file_path.in_(set(changed) | removed),
+                        )
+                    )
+                now = datetime.now(UTC)
+                for path, content in changed.items():
+                    chunks = self._chunker.chunk(
+                        file_path=path,
+                        language=language_for(path),
+                        content=content,
+                        file_hash=text_hash(content),
+                    )
+                    for offset in range(0, len(chunks), 32):
+                        batch = chunks[offset : offset + 32]
+                        vectors = validate_vectors(
+                            await self._embedding.embed_documents([c.content for c in batch]),
+                            len(batch),
+                            self._embedding.config.dimension,
+                        )
+                        for chunk, vector in zip(batch, vectors, strict=True):
+                            session.add(
+                                SemanticChunkRow(
+                                    id=uuid4(),
+                                    repository_id=repository,
+                                    file_path=chunk.file_path,
+                                    language=chunk.language,
+                                    symbol=chunk.symbol,
+                                    start_line=chunk.start_line,
+                                    end_line=chunk.end_line,
+                                    content=chunk.content,
+                                    content_hash=chunk.content_hash,
+                                    file_hash=chunk.file_hash,
+                                    embedding=list(vector),
+                                    created_at=now,
+                                    updated_at=now,
+                                )
+                            )
+                config = self._embedding.config
+                if meta is None:
+                    meta = SemanticIndexRow(repository_id=repository)
+                    session.add(meta)
+                meta.embedding_provider = config.provider
+                meta.embedding_model = config.model
+                meta.embedding_dimension = config.dimension
+                meta.index_version = "v1"
+                meta.chunk_strategy_version = "line_window_v1"
+                meta.indexed_at = now
+                await session.flush()
+                count = await session.scalar(
+                    select(func.count())
+                    .select_from(SemanticChunkRow)
+                    .where(SemanticChunkRow.repository_id == repository)
+                )
+                return IndexResult(
+                    request.repository_id,
+                    scan.scanned,
+                    len(changed),
+                    unchanged,
+                    len(removed),
+                    scan.skipped,
+                    int(count or 0),
+                    request.rebuild,
+                )
+        except ContextError as exc:
+            if exc.code == "INDEX_INCOMPATIBLE":
+                raise
+            raise ContextError(
+                "Index build failed; previous index transaction is preserved.",
+                code="INDEX_BUILD_FAILED",
+                retryable=True,
+            ) from exc
+        except Exception as exc:
+            raise ContextError(
+                "Index build failed; previous index transaction is preserved.",
+                code="INDEX_BUILD_FAILED",
+                retryable=True,
+            ) from exc

nexus/infrastructure/semantic_models.py

@@ -0,0 +1,56 @@
+"""Alembic-owned semantic tables, separate from checkpoint persistence."""
+
+from datetime import datetime
+from uuid import UUID
+
+from pgvector.sqlalchemy import VECTOR
+from sqlalchemy import CheckConstraint, DateTime, ForeignKey, Index, Text, UniqueConstraint
+from sqlalchemy.dialects.postgresql import UUID as PGUUID
+from sqlalchemy.orm import Mapped, mapped_column
+
+from nexus.infrastructure.persistence.models import Base
+
+
+class SemanticIndexRow(Base):
+    __tablename__ = "repository_semantic_indexes"
+    repository_id: Mapped[UUID] = mapped_column(
+        PGUUID(as_uuid=True),
+        ForeignKey("repositories.id"),
+        primary_key=True,
+    )
+    embedding_provider: Mapped[str] = mapped_column(Text)
+    embedding_model: Mapped[str] = mapped_column(Text)
+    embedding_dimension: Mapped[int]
+    index_version: Mapped[str] = mapped_column(Text)
+    chunk_strategy_version: Mapped[str] = mapped_column(Text)
+    indexed_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+
+
+class SemanticChunkRow(Base):
+    __tablename__ = "semantic_code_chunks"
+    __table_args__ = (
+        CheckConstraint("start_line >= 1", name="ck_semantic_start_line"),
+        CheckConstraint("end_line >= start_line", name="ck_semantic_end_line"),
+        UniqueConstraint(
+            "repository_id", "file_path", "start_line", "end_line", name="uq_semantic_file_window"
+        ),
+        Index("ix_semantic_repository", "repository_id"),
+        Index("ix_semantic_repository_file", "repository_id", "file_path"),
+        Index("ix_semantic_repository_hash", "repository_id", "content_hash"),
+    )
+    id: Mapped[UUID] = mapped_column(PGUUID(as_uuid=True), primary_key=True)
+    repository_id: Mapped[UUID] = mapped_column(
+        PGUUID(as_uuid=True),
+        ForeignKey("repositories.id"),
+    )
+    file_path: Mapped[str] = mapped_column(Text)
+    language: Mapped[str] = mapped_column(Text)
+    symbol: Mapped[str | None] = mapped_column(Text)
+    start_line: Mapped[int]
+    end_line: Mapped[int]
+    content: Mapped[str] = mapped_column(Text)
+    content_hash: Mapped[str] = mapped_column(Text)
+    file_hash: Mapped[str] = mapped_column(Text)
+    embedding: Mapped[list[float]] = mapped_column(VECTOR())
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))

nexus/interfaces/__init__.py

@@ -0,0 +1,2 @@
+"""User-facing Nexus adapters."""
+

nexus/interfaces/cli/__init__.py

@@ -0,0 +1,2 @@
+"""Typer CLI adapter."""
+

nexus/interfaces/cli/__main__.py

@@ -0,0 +1,6 @@
+"""Support ``python -m nexus.interfaces.cli`` during development."""
+
+from nexus.interfaces.cli.app import main
+
+main()
+

nexus/interfaces/cli/app.py

@@ -0,0 +1,266 @@
+"""Thin CLI adapter for the approved Day 1 command surface."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from nexus.application.runtime import NexusRuntime
+from nexus.config import load_runtime_config
+from nexus.config.models import RuntimeConfig
+from nexus.domain.persistence import SessionSummary
+from nexus.domain.planning import PlanApprovalResumeInput
+from nexus.domain.runtime_events import (
+    ApprovalRequested,
+    ApprovalSubject,
+    RunInterrupted,
+    RuntimeEvent,
+)
+from nexus.domain.tooling import ApprovalDecision
+from nexus.errors import NexusError
+from nexus.evaluation.loader import EvalSuiteLoader
+from nexus.evaluation.models import EvalOutcome, EvalSuiteLoadResult
+from nexus.evaluation.report import write_report
+from nexus.infrastructure.bootstrap import bootstrap_application
+from nexus.infrastructure.bootstrap.composition import (
+    build_evaluation_runner,
+    index_repository,
+    list_repository_sessions,
+)
+from nexus.interfaces.cli.renderer import render_event
+
+app = typer.Typer(
+    name="nexus",
+    help="Transparent and extensible Nexus V1 coding-agent runtime.",
+    add_completion=False,
+    invoke_without_command=True,
+    no_args_is_help=False,
+)
+session_app = typer.Typer(help="List and resume durable Nexus sessions.")
+app.add_typer(session_app, name="session")
+
+
+@app.callback()
+def root(context: typer.Context) -> None:
+    """Show help successfully when no subcommand is supplied."""
+
+    if context.invoked_subcommand is None:
+        typer.echo(context.get_help())
+
+
+@app.command()
+def chat(
+    task: Annotated[
+        str,
+        typer.Argument(
+            help="Non-empty task to send to the configured model.",
+            metavar="TASK",
+        ),
+    ],
+    model: Annotated[
+        str | None,
+        typer.Option("--model", help="Override the configured model name."),
+    ] = None,
+    base_url: Annotated[
+        str | None,
+        typer.Option("--base-url", help="Override the OpenAI-compatible base URL."),
+    ] = None,
+) -> None:
+    """Run a coding task through the Nexus V1 runtime."""
+
+    try:
+        config = load_runtime_config(cli_model=model, cli_base_url=base_url)
+        succeeded = asyncio.run(_run_chat(config, task))
+    except NexusError as exc:
+        typer.echo(f"Error [{exc.code}]: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+    if not succeeded:
+        raise typer.Exit(code=1)
+
+
+async def _run_chat(config: RuntimeConfig, task: str) -> bool:
+    async with bootstrap_application(config) as application:
+        return await _consume_with_plan_approval(
+            application.runtime.run(task),
+            application.runtime,
+        )
+
+
+@session_app.command("list")
+def list_sessions() -> None:
+    """List sessions owned by the current canonical repository."""
+
+    try:
+        config = load_runtime_config()
+        summaries = asyncio.run(_list_sessions(config))
+    except NexusError as exc:
+        typer.echo(f"Error [{exc.code}]: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+    _render_session_summaries(summaries)
+
+
+@app.command("index")
+def index(
+    rebuild: Annotated[bool, typer.Option("--rebuild", help="Rebuild this repository's index.")]
+    = False,
+) -> None:
+    """Incrementally index the current repository for semantic retrieval."""
+    try:
+        config = load_runtime_config()
+        result = asyncio.run(index_repository(config, rebuild=rebuild))
+    except NexusError as exc:
+        typer.echo(f"Error [{exc.code}]: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+    typer.echo(
+        f"scanned files: {result.scanned_files}; indexed/changed files: {result.indexed_files}; "
+        f"unchanged files: {result.unchanged_files}; removed files: {result.removed_files}; "
+        f"skipped files: {result.skipped_files}; chunk count: {result.chunk_count}; "
+        f"embedding: {config.embedding_provider}/{config.embedding_model}"
+    )
+
+
+@app.command("eval")
+def evaluate(
+    case_id: Annotated[
+        str | None,
+        typer.Option("--case", help="Run one mandatory evaluation case."),
+    ] = None,
+) -> None:
+    """Run the deterministic Day 9 evaluation suite sequentially."""
+
+    cases_root = Path.cwd() / "evals" / "cases"
+    loader = EvalSuiteLoader()
+    if case_id is None:
+        load_result = loader.load_suite(cases_root)
+    else:
+        source = cases_root / case_id / "case.toml"
+        if not source.is_file():
+            typer.echo(f"Unknown evaluation case: {case_id}", err=True)
+            raise typer.Exit(code=1)
+        try:
+            selected = loader.load_case(source)
+            load_result = EvalSuiteLoadResult((selected,), ())
+        except Exception as exc:
+            typer.echo(f"Invalid evaluation case {case_id}: {exc}", err=True)
+            raise typer.Exit(code=1) from exc
+    try:
+        config = load_runtime_config()
+        report = asyncio.run(build_evaluation_runner(config, cases_root).run_suite(load_result))
+        report_path, baseline = write_report(
+            report,
+            Path.cwd() / "evals" / "reports",
+            write_baseline=case_id is None,
+        )
+    except NexusError as exc:
+        typer.echo(f"Error [{exc.code}]: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+    for case_report in report.cases:
+        typer.echo(f"{case_report.case_id}: {case_report.outcome.value}")
+    for error in report.suite_errors:
+        typer.echo(f"Suite error [{error.code}]: {error.message}", err=True)
+    typer.echo(f"JSON report: {report_path}")
+    if baseline is not None:
+        typer.echo(f"Initial baseline: {baseline}")
+    if report.suite_errors or any(item.outcome is not EvalOutcome.PASS for item in report.cases):
+        raise typer.Exit(code=1)
+
+
+@session_app.command()
+def resume(
+    session_id: Annotated[
+        str,
+        typer.Argument(help="Session UUID to resume.", metavar="SESSION_ID"),
+    ],
+) -> None:
+    """Resume the latest interrupted run for a current-repository session."""
+
+    try:
+        config = load_runtime_config()
+        succeeded = asyncio.run(_run_resume(config, session_id))
+    except NexusError as exc:
+        typer.echo(f"Error [{exc.code}]: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+    if not succeeded:
+        raise typer.Exit(code=1)
+
+
+async def _list_sessions(config: RuntimeConfig) -> list[SessionSummary]:
+    return await list_repository_sessions(config)
+
+
+async def _run_resume(config: RuntimeConfig, session_id: str) -> bool:
+    async with bootstrap_application(config) as application:
+        return await _consume_with_plan_approval(
+            application.runtime.resume(session_id),
+            application.runtime,
+            requested_session_id=session_id,
+        )
+
+
+async def _consume_with_plan_approval(
+    events: AsyncIterator[RuntimeEvent],
+    runtime: NexusRuntime,
+    *,
+    requested_session_id: str | None = None,
+) -> bool:
+    succeeded = True
+    current_events = events
+    session_id = requested_session_id
+    while True:
+        pending: ApprovalRequested | None = None
+        interrupted = False
+        async for event in current_events:
+            succeeded = render_event(event) and succeeded
+            if event.session_id is not None:
+                session_id = event.session_id
+            if (
+                isinstance(event, ApprovalRequested)
+                and event.subject is ApprovalSubject.PLAN
+            ):
+                pending = event
+            interrupted = interrupted or isinstance(event, RunInterrupted)
+        if pending is None:
+            return succeeded
+        if not interrupted or session_id is None:
+            raise NexusError(
+                "Plan approval was not paired with a durable interrupt.",
+                code="GRAPH_INVALID_STATE",
+            )
+        resume_input = _collect_plan_decision()
+        current_events = runtime.resume(
+            session_id,
+            resume_input=resume_input,
+        )
+
+
+def _collect_plan_decision() -> PlanApprovalResumeInput:
+    while True:
+        value = typer.prompt("Plan decision (APPROVED/DENIED)").strip().upper()
+        try:
+            decision = ApprovalDecision(value)
+            return PlanApprovalResumeInput(decision, None)
+        except ValueError:
+            typer.echo("Enter APPROVED or DENIED.", err=True)
+
+
+def _render_session_summaries(summaries: list[SessionSummary]) -> None:
+    typer.echo("session_id\tlast_active_at\tresumable")
+    for summary in summaries:
+        typer.echo(
+            f"{summary.session_id}\t{summary.last_active_at.isoformat()}\t"
+            f"{'yes' if summary.resumable else 'no'}"
+        )
+
+
+def main() -> None:
+    """Installed console-script entry point."""
+
+    app(prog_name="nexus")
+
+
+if __name__ == "__main__":
+    main()