src/agent_harness/components.py

"""Shared component contracts used to compose harness treatments."""

from __future__ import annotations

from dataclasses import dataclass
from pathlib import Path
from typing import Any, Protocol, Sequence


@dataclass(frozen=True, slots=True)
class Candidate:
    path: str
    line_start: int
    line_end: int
    text: str
    source: str
    score: float | None = None
    symbol: str | None = None
    metadata: dict[str, Any] | None = None


class Retriever(Protocol):
    def retrieve(self, query: str, limit: int) -> Sequence[Candidate]: ...


class GraphExpander(Protocol):
    def expand(self, candidates: Sequence[Candidate], hops: int) -> Sequence[Candidate]: ...


class ContextPacker(Protocol):
    def pack(self, candidates: Sequence[Candidate], token_budget: int) -> str: ...


class QueryPolicy(Protocol):
    def next_query(self, issue: str, observations: Sequence[str]) -> str | None: ...


class RepositoryEditor(Protocol):
    def apply_patch(self, repository: Path, patch: str) -> dict[str, Any]: ...


class Validator(Protocol):
    def validate(self, repository: Path) -> dict[str, Any]: ...