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

avos_cli/models/diff.py

@@ -0,0 +1,117 @@
+"""Diff pipeline models for PR and commit reference resolution.
+
+Defines Pydantic models for the git diff extraction pipeline:
+parsed references, resolved references, deduplication plan items,
+and final diff results.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+from pydantic import BaseModel, ConfigDict
+
+
+class DiffReferenceType(str, Enum):
+    """Type of diff reference: PR or commit."""
+
+    PR = "pr"
+    COMMIT = "commit"
+
+
+class DedupDecision(str, Enum):
+    """Deduplication decision for a reference."""
+
+    KEEP = "keep"
+    SUPPRESS_COVERED_BY_PR = "suppress_covered_by_pr"
+
+
+class DiffStatus(str, Enum):
+    """Resolution status of a diff extraction."""
+
+    RESOLVED = "resolved"
+    UNRESOLVED = "unresolved"
+    SUPPRESSED = "suppressed"
+
+
+class ParsedReference(BaseModel):
+    """A parsed PR or commit reference from raw input.
+
+    Args:
+        reference_type: Whether this is a PR or commit reference.
+        raw_id: The raw identifier (PR number or short/full SHA).
+        repo_slug: Repository slug 'org/repo', or None if ambiguous.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    reference_type: DiffReferenceType
+    raw_id: str
+    repo_slug: str | None
+
+
+class ResolvedReference(BaseModel):
+    """A fully resolved reference with canonical identifiers.
+
+    For PRs: includes the list of commit SHAs contained in the PR.
+    For commits: includes the expanded full SHA.
+
+    Args:
+        reference_type: Whether this is a PR or commit reference.
+        canonical_id: Canonical display ID (e.g., 'PR #1245' or full SHA).
+        repo_slug: Repository slug 'org/repo'.
+        pr_number: PR number (for PR references).
+        full_sha: Full 40-char commit SHA (for commit references).
+        commit_shas: List of commit SHAs contained in this PR (for PR refs).
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    reference_type: DiffReferenceType
+    canonical_id: str
+    repo_slug: str
+    pr_number: int | None = None
+    full_sha: str | None = None
+    commit_shas: list[str] = []
+
+
+class DedupPlanItem(BaseModel):
+    """A deduplication plan item with decision and reasoning.
+
+    Args:
+        reference: The resolved reference being evaluated.
+        decision: Keep or suppress this reference.
+        covered_by_pr: PR number that covers this commit (if suppressed).
+        reason: Human-readable reason for the decision.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    reference: ResolvedReference
+    decision: DedupDecision
+    covered_by_pr: int | None = None
+    reason: str | None = None
+
+
+class DiffResult(BaseModel):
+    """Final result of diff extraction for a single reference.
+
+    Args:
+        reference_type: Whether this is a PR or commit reference.
+        canonical_id: Canonical display ID (e.g., 'PR #1245' or full SHA).
+        repo: Repository slug 'org/repo'.
+        diff_text: The unified diff text, or None if unresolved/suppressed.
+        status: Resolution status (resolved, unresolved, suppressed).
+        suppressed_reason: Reason for suppression (e.g., 'covered_by_pr:1245').
+        error_message: Error message if unresolved.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    reference_type: DiffReferenceType
+    canonical_id: str
+    repo: str
+    diff_text: str | None = None
+    status: DiffStatus
+    suppressed_reason: str | None = None
+    error_message: str | None = None

avos_cli/models/query.py

@@ -0,0 +1,234 @@
+"""Query pipeline internal contracts for Sprint 3 (AVOS-012..015).
+
+Defines frozen Pydantic models for the query synthesis pipeline:
+retrieval, sanitization, budget packing, citation grounding,
+chronology, synthesis request/response, and result envelopes.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+from pydantic import BaseModel, ConfigDict
+
+
+class QueryMode(str, Enum):
+    """Synthesis mode selector for ask vs history pipelines."""
+
+    ASK = "ask"
+    HISTORY = "history"
+
+
+class FallbackReason(str, Enum):
+    """Categorized reasons for falling back from synthesis to raw results."""
+
+    LLM_UNAVAILABLE = "llm_unavailable"
+    GROUNDING_FAILED = "grounding_failed"
+    SAFETY_BLOCK = "safety_block"
+    BUDGET_EXHAUSTED = "budget_exhausted"
+
+
+class GroundingStatus(str, Enum):
+    """Citation grounding validation outcome."""
+
+    GROUNDED = "grounded"
+    DROPPED_UNVERIFIABLE = "dropped_unverifiable"
+
+
+class ReferenceType(str, Enum):
+    """Type of evidence reference for display purposes."""
+
+    NOTE_ID = "note_id"
+    PR = "pr"
+    ISSUE = "issue"
+    COMMIT = "commit"
+
+
+class RetrievedArtifact(BaseModel):
+    """A single artifact returned from Memory API search.
+
+    Args:
+        note_id: Unique identifier from Memory API.
+        content: Full text content of the note.
+        created_at: ISO 8601 creation timestamp.
+        rank: Relevance rank (1 = best match).
+        source_type: Classified artifact type (e.g. raw_pr_thread).
+        display_ref: Optional human-friendly label (e.g. PR #101).
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    note_id: str
+    content: str
+    created_at: str
+    rank: int
+    source_type: str | None = None
+    display_ref: str | None = None
+
+
+class SanitizedArtifact(BaseModel):
+    """An artifact after sanitization/redaction processing.
+
+    Carries the same fields as RetrievedArtifact plus redaction audit metadata.
+
+    Args:
+        note_id: Unique identifier from Memory API.
+        content: Sanitized text content (secrets/PII redacted).
+        created_at: ISO 8601 creation timestamp.
+        rank: Relevance rank.
+        source_type: Classified artifact type.
+        display_ref: Optional human-friendly label.
+        redaction_applied: Whether any redaction was performed.
+        redaction_types: List of redaction categories applied.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    note_id: str
+    content: str
+    created_at: str
+    rank: int
+    source_type: str | None = None
+    display_ref: str | None = None
+    redaction_applied: bool = False
+    redaction_types: list[str] = []
+
+
+class SanitizationResult(BaseModel):
+    """Aggregate result of sanitization across all artifacts.
+
+    Args:
+        artifacts: List of sanitized artifacts.
+        redaction_applied: Whether any redaction occurred across the set.
+        redaction_types: Union of all redaction categories applied.
+        confidence_score: Sanitization confidence (0-100).
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    artifacts: list[SanitizedArtifact]
+    redaction_applied: bool
+    redaction_types: list[str]
+    confidence_score: int
+
+
+class BudgetResult(BaseModel):
+    """Result of context-budget packing.
+
+    Args:
+        included: Artifacts selected for synthesis (within budget).
+        excluded: Artifacts cut due to budget constraints.
+        truncation_flags: Map of note_id -> was_truncated.
+        included_count: Number of included artifacts.
+        excluded_count: Number of excluded artifacts.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    included: list[SanitizedArtifact]
+    excluded: list[SanitizedArtifact]
+    truncation_flags: dict[str, bool]
+    included_count: int
+    excluded_count: int
+
+
+class GroundedCitation(BaseModel):
+    """A citation validated against retrieved artifacts.
+
+    Args:
+        note_id: The artifact note_id this citation references.
+        display_label: Human-friendly label (e.g. PR #101, Issue #42).
+        reference_type: Category of the reference.
+        grounding_status: Whether the citation is grounded or dropped.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    note_id: str
+    display_label: str
+    reference_type: ReferenceType
+    grounding_status: GroundingStatus
+
+
+class TimelineEvent(BaseModel):
+    """A classified event in a chronological history timeline.
+
+    Args:
+        timestamp: ISO 8601 timestamp of the event.
+        event_class: Classification (Introduction, Expansion, Bug Fix, etc.).
+        summary: Brief description of the event.
+        supporting_refs: List of note_ids supporting this event.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    timestamp: str
+    event_class: str
+    summary: str
+    supporting_refs: list[str] = []
+
+
+class SynthesisRequest(BaseModel):
+    """Request payload for LLM synthesis.
+
+    Args:
+        mode: ask or history pipeline selector.
+        query: User's question or subject.
+        provider: LLM provider name.
+        model: LLM model identifier.
+        prompt_template_version: Version tag for prompt template.
+        artifacts: Packed, sanitized artifacts for context.
+        budget_meta: Optional budget metadata for diagnostics.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    mode: QueryMode
+    query: str
+    provider: str
+    model: str
+    prompt_template_version: str
+    artifacts: list[SanitizedArtifact]
+    budget_meta: dict[str, object] | None = None
+
+
+class SynthesisResponse(BaseModel):
+    """Response from LLM synthesis.
+
+    Args:
+        answer_text: The synthesized answer or timeline narrative.
+        evidence_refs: Grounded citation references.
+        timeline_events: Classified timeline events (history mode).
+        warnings: Any warnings (truncation, partial grounding, etc.).
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    answer_text: str
+    evidence_refs: list[GroundedCitation] = []
+    timeline_events: list[TimelineEvent] = []
+    warnings: list[str] = []
+
+
+class QueryResultEnvelope(BaseModel):
+    """Final result envelope returned to CLI layer.
+
+    Args:
+        mode: ask or history.
+        answer: Synthesized answer text (ask mode).
+        timeline: Chronological events (history mode).
+        citations: Grounded citations for evidence display.
+        fallback_used: Whether fallback was triggered.
+        warnings: Any warnings to display.
+        fallback_reason: Categorized reason if fallback was used.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    mode: QueryMode
+    answer: str | None = None
+    timeline: list[TimelineEvent] | None = None
+    citations: list[GroundedCitation]
+    fallback_used: bool
+    warnings: list[str] = []
+    fallback_reason: FallbackReason | None = None

avos_cli/parsers/__init__.py

@@ -0,0 +1,21 @@
+"""Parsers for reference extraction and normalization."""
+
+from avos_cli.parsers.artifact_ref_extractor import (
+    ArtifactRef,
+    NoteRefs,
+    collect_all_refs,
+    extract_refs,
+    extract_refs_by_note,
+    extract_refs_from_hits,
+)
+from avos_cli.parsers.reference_parser import ReferenceParser
+
+__all__ = [
+    "ArtifactRef",
+    "NoteRefs",
+    "ReferenceParser",
+    "collect_all_refs",
+    "extract_refs",
+    "extract_refs_by_note",
+    "extract_refs_from_hits",
+]

avos_cli/parsers/artifact_ref_extractor.py

@@ -0,0 +1,173 @@
+"""Extract PR numbers and commit hashes from memory search hit content.
+
+This module provides utilities to parse structured tags from artifact content
+returned by the Avos Memory API. The tags follow the format established by
+the ingest builders (pr_builder.py, commit_builder.py):
+
+    [pr: #42]
+    [hash: abc1234...]
+    [repo: org/repo]
+
+Functions:
+    extract_refs: Extract refs from a single content string.
+    extract_refs_from_hits: Map extraction over a list of SearchHit objects.
+    collect_all_refs: Aggregate unique refs across all hits.
+    extract_refs_by_note: Extract refs grouped by note_id as unified string arrays.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel, ConfigDict, Field
+
+if TYPE_CHECKING:
+    from avos_cli.models.api import SearchHit
+
+# Compiled regex patterns for tag extraction (shared across the codebase)
+_PR_RE = re.compile(r"\[pr:\s*#(\d+)\]", re.IGNORECASE)
+_HASH_RE = re.compile(r"\[hash:\s*([a-f0-9]+)\]", re.IGNORECASE)
+_REPO_RE = re.compile(r"\[repo:\s*([a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+)\]", re.IGNORECASE)
+
+
+def _build_references(pr_numbers: list[int], commit_hashes: list[str]) -> list[str]:
+    """Build unified reference strings from PR numbers and commit hashes.
+
+    Args:
+        pr_numbers: List of PR numbers.
+        commit_hashes: List of commit hashes.
+
+    Returns:
+        List of formatted reference strings like ["pr #42", "commit abc1234"].
+    """
+    refs: list[str] = []
+    for pr in pr_numbers:
+        refs.append(f"pr #{pr}")
+    for h in commit_hashes:
+        refs.append(f"commit {h}")
+    return refs
+
+
+class ArtifactRef(BaseModel):
+    """Structured references extracted from a memory artifact.
+
+    Attributes:
+        pr_numbers: List of unique PR numbers found in the content.
+        commit_hashes: List of unique commit hashes found in the content.
+        references: Unified list of reference strings (e.g., ["pr #42", "commit abc1234"]).
+        repo: Repository slug (owner/name) if found, else None.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    pr_numbers: list[int] = Field(default_factory=list)
+    commit_hashes: list[str] = Field(default_factory=list)
+    references: list[str] = Field(default_factory=list)
+    repo: str | None = None
+
+
+class NoteRefs(BaseModel):
+    """Per-note reference storage.
+
+    Attributes:
+        note_id: The note identifier from the memory artifact.
+        references: Unified list of reference strings (e.g., ["pr #42", "commit abc1234"]).
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    note_id: str
+    references: list[str] = Field(default_factory=list)
+
+
+def extract_refs(content: str) -> ArtifactRef:
+    """Extract PR numbers, commit hashes, and repo from content string.
+
+    Args:
+        content: Raw text content from a memory artifact.
+
+    Returns:
+        ArtifactRef with extracted references (deduplicated).
+    """
+    pr_matches = _PR_RE.findall(content)
+    pr_numbers = list(dict.fromkeys(int(m) for m in pr_matches))
+
+    hash_matches = _HASH_RE.findall(content)
+    commit_hashes = list(dict.fromkeys(hash_matches))
+
+    repo_match = _REPO_RE.search(content)
+    repo = repo_match.group(1) if repo_match else None
+
+    references = _build_references(pr_numbers, commit_hashes)
+
+    return ArtifactRef(
+        pr_numbers=pr_numbers,
+        commit_hashes=commit_hashes,
+        references=references,
+        repo=repo,
+    )
+
+
+def extract_refs_from_hits(
+    hits: list[SearchHit],
+) -> list[tuple[SearchHit, ArtifactRef]]:
+    """Extract refs from each SearchHit, preserving hit association.
+
+    Args:
+        hits: List of SearchHit objects from memory search.
+
+    Returns:
+        List of (SearchHit, ArtifactRef) tuples in the same order as input.
+    """
+    return [(hit, extract_refs(hit.content)) for hit in hits]
+
+
+def collect_all_refs(hits: list[SearchHit]) -> ArtifactRef:
+    """Aggregate unique refs across all search hits.
+
+    Args:
+        hits: List of SearchHit objects from memory search.
+
+    Returns:
+        Single ArtifactRef with deduplicated PRs and hashes from all hits.
+        Uses the first non-None repo found.
+    """
+    all_prs: list[int] = []
+    all_hashes: list[str] = []
+    first_repo: str | None = None
+
+    for hit in hits:
+        ref = extract_refs(hit.content)
+        all_prs.extend(ref.pr_numbers)
+        all_hashes.extend(ref.commit_hashes)
+        if first_repo is None and ref.repo is not None:
+            first_repo = ref.repo
+
+    unique_prs = list(dict.fromkeys(all_prs))
+    unique_hashes = list(dict.fromkeys(all_hashes))
+    references = _build_references(unique_prs, unique_hashes)
+
+    return ArtifactRef(
+        pr_numbers=unique_prs,
+        commit_hashes=unique_hashes,
+        references=references,
+        repo=first_repo,
+    )
+
+
+def extract_refs_by_note(hits: list[SearchHit]) -> list[NoteRefs]:
+    """Extract refs grouped by note_id as unified string arrays.
+
+    Args:
+        hits: List of SearchHit objects from memory search.
+
+    Returns:
+        List of NoteRefs, one per hit, with references as formatted strings.
+        Example: [NoteRefs(note_id="11", references=["pr #123", "commit qdsf"])]
+    """
+    result: list[NoteRefs] = []
+    for hit in hits:
+        ref = extract_refs(hit.content)
+        result.append(NoteRefs(note_id=hit.note_id, references=ref.references))
+    return result

avos_cli/parsers/reference_parser.py

@@ -0,0 +1,117 @@
+"""Reference parser for PR and commit identifiers.
+
+Provides regex-based parsing of various PR and commit reference formats
+without LLM interpretation. Fails fast on ambiguous inputs.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import ClassVar
+
+from avos_cli.models.diff import DiffReferenceType, ParsedReference
+
+
+class ReferenceParser:
+    """Parses raw reference strings into structured ParsedReference objects.
+
+    Supports formats:
+    - PR: "PR #1245", "pr #1245", "PR#1245", "#1245", "org/repo#1245"
+    - Commit: "Commit 8c3a1b2", "commit abc123", bare SHA (7-40 hex chars)
+    - URLs: "https://github.com/org/repo/pull/123", ".../commit/abc123"
+    """
+
+    _PR_PATTERNS: ClassVar[list[re.Pattern[str]]] = [
+        # GitHub PR URL: https://github.com/org/repo/pull/123
+        re.compile(
+            r"(?:https?://)?github\.com/(?P<repo>[^/]+/[^/]+)/pull/(?P<num>\d+)",
+            re.IGNORECASE,
+        ),
+        # org/repo#123 or github.com/org/repo#123
+        re.compile(
+            r"(?:github\.com/)?(?P<repo>[a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+)#(?P<num>\d+)",
+            re.IGNORECASE,
+        ),
+        # PR #123 or PR#123 or pr #123
+        re.compile(r"\bpr\s*#\s*(?P<num>\d+)", re.IGNORECASE),
+        # Bare #123 (assumes PR in context)
+        re.compile(r"^#(?P<num>\d+)(?:\s|$)"),
+    ]
+
+    _COMMIT_PATTERNS: ClassVar[list[re.Pattern[str]]] = [
+        # GitHub commit URL: https://github.com/org/repo/commit/abc123
+        re.compile(
+            r"(?:https?://)?github\.com/(?P<repo>[^/]+/[^/]+)/commit/(?P<sha>[a-f0-9]{7,40})",
+            re.IGNORECASE,
+        ),
+        # Commit abc123 or commit: abc123
+        re.compile(r"\bcommit:?\s*(?P<sha>[a-f0-9]{7,40})", re.IGNORECASE),
+        # Bare SHA (7-40 hex chars, must be whole token)
+        re.compile(r"^(?P<sha>[a-f0-9]{7,40})$", re.IGNORECASE),
+    ]
+
+    def parse(self, raw: str, default_repo: str | None) -> ParsedReference | None:
+        """Parse a single raw reference string.
+
+        Args:
+            raw: The raw reference string to parse.
+            default_repo: Default repository slug if not specified in reference.
+                After ``avos connect``, use :func:`~avos_cli.config.manager.connected_repo_slug`.
+
+        Returns:
+            ParsedReference if successfully parsed, None otherwise.
+        """
+        if not raw or not raw.strip():
+            return None
+
+        text = raw.strip()
+
+        # Try PR patterns first
+        for pattern in self._PR_PATTERNS:
+            match = pattern.search(text)
+            if match:
+                num_str = match.group("num")
+                num = int(num_str)
+                if num <= 0:
+                    return None
+
+                repo = match.groupdict().get("repo") or default_repo
+                return ParsedReference(
+                    reference_type=DiffReferenceType.PR,
+                    raw_id=num_str,
+                    repo_slug=repo,
+                )
+
+        # Try commit patterns
+        for pattern in self._COMMIT_PATTERNS:
+            match = pattern.search(text)
+            if match:
+                sha = match.group("sha").lower()
+                repo = match.groupdict().get("repo") or default_repo
+                return ParsedReference(
+                    reference_type=DiffReferenceType.COMMIT,
+                    raw_id=sha,
+                    repo_slug=repo,
+                )
+
+        return None
+
+    def parse_all(
+        self, raw_list: list[str], default_repo: str | None
+    ) -> list[ParsedReference]:
+        """Parse multiple raw reference strings.
+
+        Args:
+            raw_list: List of raw reference strings to parse.
+            default_repo: Default repository slug if not specified.
+                After ``avos connect``, use :func:`~avos_cli.config.manager.connected_repo_slug`.
+
+        Returns:
+            List of successfully parsed references (invalid ones are skipped).
+        """
+        results: list[ParsedReference] = []
+        for raw in raw_list:
+            ref = self.parse(raw, default_repo)
+            if ref is not None:
+                results.append(ref)
+        return results

avos_cli/services/__init__.py

@@ -0,0 +1 @@
+"""Shared service modules for AVOS CLI."""