git-aware-coding-agent 1.0.0__py3-none-any.whl

avos_cli/services/chronology_service.py

@@ -0,0 +1,68 @@
+"""Chronology service for deterministic timeline ordering.
+
+Parses ISO 8601 timestamps, normalizes to UTC, and sorts artifacts
+using a stable deterministic comparator for the history command pipeline.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from avos_cli.models.query import RetrievedArtifact
+from avos_cli.utils.logger import get_logger
+
+_log = get_logger("chronology")
+
+_MAX_DATETIME = datetime(9999, 12, 31, 23, 59, 59, tzinfo=timezone.utc)
+
+
+class ChronologyService:
+    """Sorts artifacts chronologically with deterministic tie-breakers.
+
+    Sort contract: timestamp ASC, rank ASC, note_id ASC.
+    Invalid/null timestamps are sorted last.
+    """
+
+    def sort(self, artifacts: list[RetrievedArtifact]) -> list[RetrievedArtifact]:
+        """Sort artifacts in chronological order.
+
+        Args:
+            artifacts: Artifacts to sort (not mutated).
+
+        Returns:
+            New list sorted by (timestamp ASC, rank ASC, note_id ASC).
+        """
+        return sorted(artifacts, key=self._sort_key)
+
+    def _sort_key(self, art: RetrievedArtifact) -> tuple[datetime, int, str]:
+        """Build deterministic sort key for an artifact."""
+        ts = self._parse_timestamp(art.created_at)
+        return (ts, art.rank, art.note_id)
+
+    def _parse_timestamp(self, value: str) -> datetime:
+        """Parse ISO 8601 timestamp to UTC datetime.
+
+        Invalid or empty values return _MAX_DATETIME (sorted last).
+        Naive datetimes are assumed UTC.
+        """
+        if not value or not value.strip():
+            return _MAX_DATETIME
+
+        cleaned = value.strip()
+
+        for fmt in (
+            "%Y-%m-%dT%H:%M:%S%z",
+            "%Y-%m-%dT%H:%M:%SZ",
+            "%Y-%m-%dT%H:%M:%S",
+            "%Y-%m-%d",
+        ):
+            try:
+                dt = datetime.strptime(cleaned, fmt)
+                if dt.tzinfo is None:
+                    dt = dt.replace(tzinfo=timezone.utc)
+                return dt.astimezone(timezone.utc)
+            except ValueError:
+                continue
+
+        _log.warning("Unparseable timestamp '%s', sorting last", value)
+        return _MAX_DATETIME

avos_cli/services/citation_validator.py

@@ -0,0 +1,134 @@
+"""Citation validator for query pipeline grounding enforcement.
+
+Extracts citations from LLM synthesis responses and validates each
+against retrieved artifact note_ids. Ungrounded citations are dropped
+with warnings. Supports structured JSON and inline [note_id] fallback.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+
+from avos_cli.models.query import (
+    GroundedCitation,
+    GroundingStatus,
+    ReferenceType,
+    SanitizedArtifact,
+)
+from avos_cli.utils.logger import get_logger
+
+_log = get_logger("citation_validator")
+
+_INLINE_CITATION_PATTERN = re.compile(r"\[([a-zA-Z0-9_\-]+)\]")
+
+_MIN_GROUNDED_THRESHOLD = 2
+
+
+class CitationValidator:
+    """Validates LLM synthesis citations against retrieved artifacts.
+
+    Grounding rule: exact note_id match only. No fuzzy matching.
+    Minimum threshold: 2 grounded citations for synthesis acceptance.
+    """
+
+    def validate(
+        self,
+        response_text: str,
+        artifacts: list[SanitizedArtifact],
+    ) -> tuple[list[GroundedCitation], list[GroundedCitation], list[str]]:
+        """Validate citations in LLM response against retrieved artifacts.
+
+        Args:
+            response_text: Raw LLM response text (may contain JSON or inline refs).
+            artifacts: The sanitized artifacts that were sent to the LLM.
+
+        Returns:
+            Tuple of (grounded_citations, dropped_citations, warnings).
+        """
+        valid_ids = {art.note_id for art in artifacts}
+        raw_citations = self._extract_citations(response_text)
+
+        seen: set[str] = set()
+        grounded: list[GroundedCitation] = []
+        dropped: list[GroundedCitation] = []
+        warnings: list[str] = []
+
+        for note_id, display_label in raw_citations:
+            if note_id in seen:
+                continue
+            seen.add(note_id)
+
+            if note_id in valid_ids:
+                grounded.append(
+                    GroundedCitation(
+                        note_id=note_id,
+                        display_label=display_label or note_id,
+                        reference_type=ReferenceType.NOTE_ID,
+                        grounding_status=GroundingStatus.GROUNDED,
+                    )
+                )
+            else:
+                dropped.append(
+                    GroundedCitation(
+                        note_id=note_id,
+                        display_label=display_label or note_id,
+                        reference_type=ReferenceType.NOTE_ID,
+                        grounding_status=GroundingStatus.DROPPED_UNVERIFIABLE,
+                    )
+                )
+
+        if dropped:
+            warnings.append(
+                f"{len(dropped)} citation(s) dropped as unverifiable: "
+                f"{', '.join(c.note_id for c in dropped)}"
+            )
+
+        return grounded, dropped, warnings
+
+    def _extract_citations(
+        self, response_text: str
+    ) -> list[tuple[str, str | None]]:
+        """Extract citation note_ids from response, preferring structured JSON.
+
+        Returns:
+            List of (note_id, display_label_or_none) tuples.
+        """
+        structured = self._try_structured_extraction(response_text)
+        if structured is not None:
+            return structured
+        return self._inline_extraction(response_text)
+
+    def _try_structured_extraction(
+        self, response_text: str
+    ) -> list[tuple[str, str | None]] | None:
+        """Try to parse citations from JSON structure in response."""
+        cleaned = re.sub(r"^```(?:json)?\s*\n?", "", response_text.strip())
+        cleaned = re.sub(r"\n?```\s*$", "", cleaned)
+        try:
+            data = json.loads(cleaned)
+        except (json.JSONDecodeError, TypeError):
+            return None
+
+        if not isinstance(data, dict):
+            return None
+
+        citations_raw = data.get("citations")
+        if not isinstance(citations_raw, list):
+            return None
+
+        results: list[tuple[str, str | None]] = []
+        for item in citations_raw:
+            if isinstance(item, dict) and "note_id" in item:
+                note_id = str(item["note_id"])
+                display_label = item.get("display_label")
+                results.append((note_id, display_label))
+
+        return results if results else None
+
+    def _inline_extraction(
+        self, response_text: str
+    ) -> list[tuple[str, str | None]]:
+        """Fallback: extract [note_id] patterns from plain text."""
+        matches = _INLINE_CITATION_PATTERN.findall(response_text)
+        return [(m, None) for m in matches]

avos_cli/services/context_budget_service.py

@@ -0,0 +1,104 @@
+"""Context budget service for query pipeline artifact packing.
+
+Applies deterministic ranking, truncation, and hard caps to sanitized
+artifacts before LLM synthesis. Ensures stable ordering across runs
+and preserves citation metadata for downstream grounding.
+"""
+
+from __future__ import annotations
+
+from avos_cli.models.query import BudgetResult, SanitizedArtifact
+from avos_cli.utils.logger import get_logger
+
+_log = get_logger("context_budget")
+
+_ASK_MAX_ARTIFACTS = 6
+_ASK_EXCERPT_CAP = 800
+_HISTORY_MAX_ARTIFACTS = 10
+_HISTORY_EXCERPT_CAP = 600
+
+_EPOCH = "1970-01-01T00:00:00Z"
+_MAX_RANK = 999999999
+
+
+class ContextBudgetService:
+    """Packs sanitized artifacts within model context budget.
+
+    Sorting contract: rank ASC, created_at DESC, note_id ASC.
+    Null rank -> max int (sorted last). Empty created_at -> epoch (sorted last for DESC).
+    """
+
+    def pack(
+        self,
+        artifacts: list[SanitizedArtifact],
+        mode: str,
+    ) -> BudgetResult:
+        """Rank, sort, truncate, and cap artifacts for synthesis.
+
+        Args:
+            artifacts: Sanitized artifacts to pack.
+            mode: 'ask' or 'history' -- determines caps and excerpt limits.
+
+        Returns:
+            BudgetResult with included/excluded artifacts and metadata.
+        """
+        if mode == "ask":
+            max_count = _ASK_MAX_ARTIFACTS
+            excerpt_cap = _ASK_EXCERPT_CAP
+        else:
+            max_count = _HISTORY_MAX_ARTIFACTS
+            excerpt_cap = _HISTORY_EXCERPT_CAP
+
+        sorted_arts = sorted(artifacts, key=self._sort_key)
+
+        included_raw = sorted_arts[:max_count]
+        excluded_raw = sorted_arts[max_count:]
+
+        included: list[SanitizedArtifact] = []
+        truncation_flags: dict[str, bool] = {}
+
+        for art in included_raw:
+            truncated_content, was_truncated = self._truncate(art.content, excerpt_cap)
+            truncation_flags[art.note_id] = was_truncated
+            if was_truncated:
+                included.append(
+                    SanitizedArtifact(
+                        note_id=art.note_id,
+                        content=truncated_content,
+                        created_at=art.created_at,
+                        rank=art.rank,
+                        source_type=art.source_type,
+                        display_ref=art.display_ref,
+                        redaction_applied=art.redaction_applied,
+                        redaction_types=art.redaction_types,
+                    )
+                )
+            else:
+                truncation_flags[art.note_id] = False
+                included.append(art)
+
+        return BudgetResult(
+            included=included,
+            excluded=list(excluded_raw),
+            truncation_flags=truncation_flags,
+            included_count=len(included),
+            excluded_count=len(excluded_raw),
+        )
+
+    def _sort_key(self, art: SanitizedArtifact) -> tuple[int, str, str]:
+        """Deterministic sort key: rank ASC, created_at DESC, note_id ASC.
+
+        For DESC on created_at, we negate by using a complement string trick:
+        reverse the sort by prepending a character that inverts ordering.
+        """
+        rank = art.rank if art.rank < _MAX_RANK else _MAX_RANK
+        created_at = art.created_at if art.created_at else _EPOCH
+        # For descending created_at: invert by negating character ordinals
+        inverted_date = "".join(chr(0xFFFF - ord(c)) for c in created_at)
+        return (rank, inverted_date, art.note_id)
+
+    def _truncate(self, content: str, cap: int) -> tuple[str, bool]:
+        """Truncate content to cap with '...' marker if needed."""
+        if len(content) <= cap:
+            return content, False
+        return content[:cap] + "...", True

avos_cli/services/diff_resolver.py

@@ -0,0 +1,398 @@
+"""Diff resolver for PR and commit references.
+
+Implements the PR-Wins deduplication strategy: commits that are part of
+a referenced PR are suppressed to avoid duplicate content. Extracts
+unified diffs from the GitHub REST API for both PRs and commits.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from avos_cli.exceptions import AvosError
+from avos_cli.models.diff import (
+    DedupDecision,
+    DedupPlanItem,
+    DiffReferenceType,
+    DiffResult,
+    DiffStatus,
+    ParsedReference,
+    ResolvedReference,
+)
+from avos_cli.utils.logger import get_logger
+
+if TYPE_CHECKING:
+    from avos_cli.services.github_client import GitHubClient
+
+_log = get_logger("diff_resolver")
+
+
+class DiffResolver:
+    """Resolves PR and commit references to unified diffs via GitHub API.
+
+    Implements the PR-Wins deduplication strategy:
+    1. Build coverage index: map each commit SHA to PRs containing it
+    2. For each commit reference, check if it's covered by any PR
+    3. Suppress covered commits, keep independent commits
+    4. Extract diffs for all kept references
+
+    Args:
+        github_client: GitHub REST API client for PR and commit endpoints.
+    """
+
+    def __init__(self, github_client: GitHubClient) -> None:
+        self._github = github_client
+
+    def resolve(self, references: list[ParsedReference]) -> list[DiffResult]:
+        """Resolve references to diffs with PR-Wins deduplication.
+
+        Args:
+            references: List of parsed PR/commit references.
+
+        Returns:
+            List of DiffResult objects with extracted diffs or status info.
+        """
+        if not references:
+            return []
+
+        pr_refs = [r for r in references if r.reference_type == DiffReferenceType.PR]
+        coverage_index = self._build_coverage_index(pr_refs)
+        dedup_plan = self._apply_dedup(references, coverage_index)
+
+        results: list[DiffResult] = []
+        for plan_item in dedup_plan:
+            result = self._extract_diff(plan_item)
+            results.append(result)
+
+        return results
+
+    def _build_coverage_index(
+        self, pr_refs: list[ParsedReference]
+    ) -> dict[str, set[int]]:
+        """Build index mapping commit SHAs to PR numbers that contain them.
+
+        Args:
+            pr_refs: List of PR references to index.
+
+        Returns:
+            Dict mapping full commit SHA to set of PR numbers.
+        """
+        index: dict[str, set[int]] = {}
+
+        for pr_ref in pr_refs:
+            if pr_ref.repo_slug is None:
+                continue
+
+            pr_number = int(pr_ref.raw_id)
+            owner, repo = pr_ref.repo_slug.split("/", 1)
+
+            try:
+                commit_shas = self._github.list_pr_commits(owner, repo, pr_number)
+                for sha in commit_shas:
+                    if sha not in index:
+                        index[sha] = set()
+                    index[sha].add(pr_number)
+            except AvosError as e:
+                _log.warning("Failed to fetch commits for PR #%d: %s", pr_number, e)
+
+        return index
+
+    def _apply_dedup(
+        self,
+        references: list[ParsedReference],
+        coverage_index: dict[str, set[int]],
+    ) -> list[DedupPlanItem]:
+        """Apply PR-Wins deduplication rule to all references.
+
+        Args:
+            references: All parsed references.
+            coverage_index: Mapping of commit SHA to covering PR numbers.
+
+        Returns:
+            List of DedupPlanItem with keep/suppress decisions.
+        """
+        plan: list[DedupPlanItem] = []
+
+        for ref in references:
+            if ref.reference_type == DiffReferenceType.PR:
+                resolved = self._resolve_pr_reference(ref)
+                if resolved is None:
+                    plan.append(self._make_unresolved_plan_item(ref, "PR resolution failed"))
+                else:
+                    plan.append(
+                        DedupPlanItem(reference=resolved, decision=DedupDecision.KEEP)
+                    )
+            else:
+                resolved, commit_detail = self._resolve_commit_reference(ref)
+                if resolved is None:
+                    plan.append(
+                        self._make_unresolved_plan_item(
+                            ref,
+                            commit_detail or "Commit SHA expansion failed",
+                        )
+                    )
+                    continue
+
+                full_sha = resolved.full_sha
+                if full_sha and full_sha in coverage_index:
+                    covering_prs = coverage_index[full_sha]
+                    first_pr = min(covering_prs)
+                    plan.append(
+                        DedupPlanItem(
+                            reference=resolved,
+                            decision=DedupDecision.SUPPRESS_COVERED_BY_PR,
+                            covered_by_pr=first_pr,
+                            reason=f"Covered by PR #{first_pr}",
+                        )
+                    )
+                else:
+                    plan.append(
+                        DedupPlanItem(reference=resolved, decision=DedupDecision.KEEP)
+                    )
+
+        return plan
+
+    def _resolve_pr_reference(self, ref: ParsedReference) -> ResolvedReference | None:
+        """Resolve a PR reference to canonical form.
+
+        Args:
+            ref: Parsed PR reference.
+
+        Returns:
+            ResolvedReference or None if resolution fails.
+        """
+        if ref.repo_slug is None:
+            return None
+
+        pr_number = int(ref.raw_id)
+        owner, repo = ref.repo_slug.split("/", 1)
+
+        try:
+            commit_shas = self._github.list_pr_commits(owner, repo, pr_number)
+        except AvosError:
+            commit_shas = []
+
+        return ResolvedReference(
+            reference_type=DiffReferenceType.PR,
+            canonical_id=f"PR #{pr_number}",
+            repo_slug=ref.repo_slug,
+            pr_number=pr_number,
+            commit_shas=commit_shas,
+        )
+
+    def _resolve_commit_reference(
+        self, ref: ParsedReference
+    ) -> tuple[ResolvedReference | None, str | None]:
+        """Resolve a commit reference to canonical form with full SHA.
+
+        Uses the GitHub commits API (same as the hosted repo).
+
+        Args:
+            ref: Parsed commit reference.
+
+        Returns:
+            (resolved, None) on success, or (None, detail) where detail is a
+            short error string (e.g. GitHub API message) when resolution fails.
+        """
+        if ref.repo_slug is None:
+            return None, None
+
+        owner, repo = ref.repo_slug.split("/", 1)
+
+        try:
+            payload = self._github.get_commit(owner, repo, ref.raw_id)
+        except AvosError as e:
+            return None, str(e)
+        full_sha = str(payload.get("sha", ""))
+        if len(full_sha) != 40:
+            return None, "Commit response missing full SHA"
+        return (
+            ResolvedReference(
+                reference_type=DiffReferenceType.COMMIT,
+                canonical_id=full_sha,
+                repo_slug=ref.repo_slug,
+                full_sha=full_sha,
+            ),
+            None,
+        )
+
+    def _make_unresolved_plan_item(
+        self, ref: ParsedReference, reason: str
+    ) -> DedupPlanItem:
+        """Create a plan item for an unresolved reference.
+
+        Args:
+            ref: The unresolved reference.
+            reason: Reason for failure.
+
+        Returns:
+            DedupPlanItem with KEEP decision (will produce UNRESOLVED result).
+        """
+        resolved = ResolvedReference(
+            reference_type=ref.reference_type,
+            canonical_id=ref.raw_id,
+            repo_slug=ref.repo_slug or "unknown",
+            pr_number=int(ref.raw_id) if ref.reference_type == DiffReferenceType.PR else None,
+            full_sha=ref.raw_id if ref.reference_type == DiffReferenceType.COMMIT else None,
+        )
+        return DedupPlanItem(
+            reference=resolved,
+            decision=DedupDecision.KEEP,
+            reason=reason,
+        )
+
+    def _extract_diff(self, plan_item: DedupPlanItem) -> DiffResult:
+        """Extract diff for a single plan item.
+
+        Args:
+            plan_item: Dedup plan item with reference and decision.
+
+        Returns:
+            DiffResult with diff text or status info.
+        """
+        ref = plan_item.reference
+
+        if plan_item.decision == DedupDecision.SUPPRESS_COVERED_BY_PR:
+            return DiffResult(
+                reference_type=ref.reference_type,
+                canonical_id=ref.canonical_id,
+                repo=ref.repo_slug,
+                status=DiffStatus.SUPPRESSED,
+                suppressed_reason=f"covered_by_pr:{plan_item.covered_by_pr}",
+            )
+
+        if ref.repo_slug is None or ref.repo_slug == "unknown":
+            return DiffResult(
+                reference_type=ref.reference_type,
+                canonical_id=ref.canonical_id,
+                repo=ref.repo_slug or "unknown",
+                status=DiffStatus.UNRESOLVED,
+                error_message="Repository context unknown",
+            )
+
+        if plan_item.decision == DedupDecision.KEEP and plan_item.reason:
+            return DiffResult(
+                reference_type=ref.reference_type,
+                canonical_id=ref.canonical_id,
+                repo=ref.repo_slug,
+                status=DiffStatus.UNRESOLVED,
+                error_message=plan_item.reason,
+            )
+
+        if ref.reference_type == DiffReferenceType.PR:
+            return self._extract_pr_diff(ref)
+        return self._extract_commit_diff(ref)
+
+    def _extract_pr_diff(self, ref: ResolvedReference) -> DiffResult:
+        """Extract diff for a PR reference.
+
+        Args:
+            ref: Resolved PR reference.
+
+        Returns:
+            DiffResult with PR diff or error.
+        """
+        if ref.pr_number is None or ref.repo_slug is None:
+            return DiffResult(
+                reference_type=ref.reference_type,
+                canonical_id=ref.canonical_id,
+                repo=ref.repo_slug or "unknown",
+                status=DiffStatus.UNRESOLVED,
+                error_message="Invalid PR reference",
+            )
+
+        owner, repo = ref.repo_slug.split("/", 1)
+
+        try:
+            diff_text = self._github.get_pr_diff(owner, repo, ref.pr_number)
+            return DiffResult(
+                reference_type=ref.reference_type,
+                canonical_id=ref.canonical_id,
+                repo=ref.repo_slug,
+                diff_text=diff_text,
+                status=DiffStatus.RESOLVED,
+            )
+        except AvosError as e:
+            return DiffResult(
+                reference_type=ref.reference_type,
+                canonical_id=ref.canonical_id,
+                repo=ref.repo_slug,
+                status=DiffStatus.UNRESOLVED,
+                error_message=str(e),
+            )
+
+    def _extract_commit_diff(self, ref: ResolvedReference) -> DiffResult:
+        """Extract diff for a commit reference via GitHub commits API.
+
+        Args:
+            ref: Resolved commit reference.
+
+        Returns:
+            DiffResult with commit diff or error.
+        """
+        if ref.full_sha is None:
+            return DiffResult(
+                reference_type=ref.reference_type,
+                canonical_id=ref.canonical_id,
+                repo=ref.repo_slug,
+                status=DiffStatus.UNRESOLVED,
+                error_message="Commit SHA not resolved",
+            )
+
+        owner, repo = ref.repo_slug.split("/", 1)
+
+        try:
+            diff_text = self._github.get_commit_diff(owner, repo, ref.full_sha)
+            if not diff_text:
+                return DiffResult(
+                    reference_type=ref.reference_type,
+                    canonical_id=ref.canonical_id,
+                    repo=ref.repo_slug,
+                    status=DiffStatus.UNRESOLVED,
+                    error_message="Commit has no diff (empty response)",
+                )
+            return DiffResult(
+                reference_type=ref.reference_type,
+                canonical_id=ref.canonical_id,
+                repo=ref.repo_slug,
+                diff_text=diff_text,
+                status=DiffStatus.RESOLVED,
+            )
+        except AvosError as e:
+            return DiffResult(
+                reference_type=ref.reference_type,
+                canonical_id=ref.canonical_id,
+                repo=ref.repo_slug,
+                status=DiffStatus.UNRESOLVED,
+                error_message=str(e),
+            )
+
+    def format_output(self, results: list[DiffResult]) -> str:
+        """Format diff results as grouped output text.
+
+        Args:
+            results: List of DiffResult objects.
+
+        Returns:
+            Formatted string with headers and diff content.
+        """
+        lines: list[str] = []
+
+        for result in results:
+            if result.reference_type == DiffReferenceType.PR:
+                header = f"=== PR #{result.canonical_id.replace('PR #', '')} ==="
+            else:
+                header = f"=== COMMIT {result.canonical_id} ==="
+
+            lines.append(header)
+
+            if result.status == DiffStatus.RESOLVED:
+                lines.append(result.diff_text or "")
+            elif result.status == DiffStatus.SUPPRESSED:
+                lines.append(f"[suppressed: {result.suppressed_reason}]")
+            else:
+                lines.append(f"[unresolved: {result.error_message}]")
+
+            lines.append("")
+
+        return "\n".join(lines)