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

avos_cli/config/state.py

@@ -0,0 +1,90 @@
+"""Atomic file I/O and corruption handling for .avos state files.
+
+Provides safe write (temp + fsync + rename) and safe read (with
+corruption detection and quarantine) for JSON state files.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import tempfile
+import time
+from pathlib import Path
+
+from avos_cli.utils.logger import get_logger
+
+_log = get_logger("config.state")
+
+
+def atomic_write(path: Path, content: str, permissions: int = 0o600) -> None:
+    """Write content to a file atomically using temp+fsync+rename.
+
+    Args:
+        path: Target file path.
+        content: String content to write.
+        permissions: File permission mode (default 0o600 for secrets).
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp_path = tempfile.mkstemp(
+        dir=str(path.parent),
+        prefix=f".{path.name}.",
+        suffix=".tmp",
+    )
+    try:
+        os.write(fd, content.encode("utf-8"))
+        os.fsync(fd)
+        os.close(fd)
+        os.chmod(tmp_path, permissions)
+        os.replace(tmp_path, str(path))
+    except BaseException:
+        os.close(fd) if not _is_fd_closed(fd) else None
+        with contextlib.suppress(OSError):
+            os.unlink(tmp_path)
+        raise
+
+
+def _is_fd_closed(fd: int) -> bool:
+    """Check if a file descriptor is already closed."""
+    try:
+        os.fstat(fd)
+        return False
+    except OSError:
+        return True
+
+
+def read_json_safe(path: Path) -> dict[str, object] | None:
+    """Read and parse a JSON file, quarantining corrupt files.
+
+    If the file doesn't exist, returns None.
+    If the file contains invalid JSON, it is renamed to
+    `<name>.corrupt.<timestamp>` and None is returned.
+
+    Args:
+        path: Path to the JSON file.
+
+    Returns:
+        Parsed dict or None if missing/corrupt.
+    """
+    if not path.exists():
+        return None
+
+    try:
+        content = path.read_text(encoding="utf-8")
+        data: dict[str, object] = json.loads(content)
+        return data
+    except (json.JSONDecodeError, UnicodeDecodeError):
+        _quarantine(path)
+        return None
+
+
+def _quarantine(path: Path) -> None:
+    """Move a corrupt file to a .corrupt.<timestamp> backup."""
+    ts = int(time.time())
+    corrupt_path = path.with_suffix(f"{path.suffix}.corrupt.{ts}")
+    try:
+        path.rename(corrupt_path)
+        _log.warning("Quarantined corrupt file: %s -> %s", path, corrupt_path)
+    except OSError as e:
+        _log.error("Failed to quarantine corrupt file %s: %s", path, e)

avos_cli/exceptions.py

@@ -0,0 +1,272 @@
+"""Exception hierarchy and error codes for the AVOS CLI.
+
+All exceptions inherit from AvosError. Each exception carries a machine-readable
+error code, a human-readable message, and an optional action hint for the user.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class ErrorCode(str, Enum):
+    """Machine-readable error codes for structured error handling."""
+
+    CONFIG_NOT_INITIALIZED = "CONFIG_NOT_INITIALIZED"
+    CONFIG_VALIDATION_ERROR = "CONFIG_VALIDATION_ERROR"
+    REPOSITORY_CONTEXT_ERROR = "REPOSITORY_CONTEXT_ERROR"
+    AUTH_ERROR = "AUTH_ERROR"
+    RATE_LIMIT_ERROR = "RATE_LIMIT_ERROR"
+    UPSTREAM_UNAVAILABLE = "UPSTREAM_UNAVAILABLE"
+    REQUEST_CONTRACT_ERROR = "REQUEST_CONTRACT_ERROR"
+    DEPENDENCY_UNAVAILABLE = "DEPENDENCY_UNAVAILABLE"
+    SERVICE_PARSE_ERROR = "SERVICE_PARSE_ERROR"
+    ARTIFACT_BUILD_ERROR = "ARTIFACT_BUILD_ERROR"
+    RESOURCE_NOT_FOUND = "RESOURCE_NOT_FOUND"
+    STATE_FILE_CONFLICT = "STATE_FILE_CONFLICT"
+    INGEST_LOCK_CONFLICT = "INGEST_LOCK_CONFLICT"
+    SANITIZATION_FAILED = "SANITIZATION_FAILED"
+    GROUNDING_FAILED = "GROUNDING_FAILED"
+    LLM_SYNTHESIS_ERROR = "LLM_SYNTHESIS_ERROR"
+    CONTEXT_BUDGET_ERROR = "CONTEXT_BUDGET_ERROR"
+    QUERY_EMPTY_RESULT = "QUERY_EMPTY_RESULT"
+
+
+class AvosError(Exception):
+    """Base exception for all AVOS CLI errors.
+
+    Args:
+        message: Human-readable error description.
+        code: Machine-readable error code from ErrorCode enum.
+        hint: Optional action hint for the user.
+        retryable: Whether the operation can be retried.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        code: ErrorCode,
+        hint: str | None = None,
+        retryable: bool = False,
+    ) -> None:
+        self.code = code
+        self.hint = hint
+        self.retryable = retryable
+        super().__init__(message)
+
+
+class ConfigurationNotInitializedError(AvosError):
+    """Raised when .avos/config.json is missing or memory_id is not set."""
+
+    def __init__(self, message: str | None = None) -> None:
+        super().__init__(
+            message=message or "Repository not connected. No .avos/config.json found.",
+            code=ErrorCode.CONFIG_NOT_INITIALIZED,
+            hint="Run 'avos connect <org/repo>' to initialize this repository.",
+        )
+
+
+class ConfigurationValidationError(AvosError):
+    """Raised when config file exists but contains invalid data."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(
+            message=message,
+            code=ErrorCode.CONFIG_VALIDATION_ERROR,
+            hint="Inspect and fix .avos/config.json, or re-run 'avos connect'.",
+        )
+
+
+class RepositoryContextError(AvosError):
+    """Raised when the current directory is not inside a valid Git repository."""
+
+    def __init__(self, message: str | None = None) -> None:
+        super().__init__(
+            message=message or "Not inside a Git repository.",
+            code=ErrorCode.REPOSITORY_CONTEXT_ERROR,
+            hint="Run this command from within a Git repository.",
+        )
+
+
+class AuthError(AvosError):
+    """Raised when API authentication fails."""
+
+    def __init__(self, message: str, service: str = "API") -> None:
+        super().__init__(
+            message=message,
+            code=ErrorCode.AUTH_ERROR,
+            hint=f"Verify your {service} credentials are correct and have required permissions.",
+        )
+
+
+class RateLimitError(AvosError):
+    """Raised when API rate limit is exhausted."""
+
+    def __init__(self, message: str, retry_after: float | None = None) -> None:
+        hint = "Rate limit exceeded."
+        if retry_after is not None:
+            hint = f"Rate limit exceeded. Retry after {retry_after:.0f} seconds."
+        super().__init__(
+            message=message,
+            code=ErrorCode.RATE_LIMIT_ERROR,
+            hint=hint,
+            retryable=True,
+        )
+        self.retry_after = retry_after
+
+
+class UpstreamUnavailableError(AvosError):
+    """Raised when an external service is unreachable after retries."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(
+            message=message,
+            code=ErrorCode.UPSTREAM_UNAVAILABLE,
+            hint="The service may be temporarily unavailable. Try again later.",
+            retryable=True,
+        )
+
+
+class RequestContractError(AvosError):
+    """Raised when a request violates the API contract."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(
+            message=message,
+            code=ErrorCode.REQUEST_CONTRACT_ERROR,
+        )
+
+
+class ResourceNotFoundError(AvosError):
+    """Raised when a requested resource does not exist (404)."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(
+            message=message,
+            code=ErrorCode.RESOURCE_NOT_FOUND,
+        )
+
+
+class DependencyUnavailableError(AvosError):
+    """Raised when a required local dependency is missing."""
+
+    def __init__(self, dependency: str) -> None:
+        super().__init__(
+            message=f"Required dependency not found: {dependency}",
+            code=ErrorCode.DEPENDENCY_UNAVAILABLE,
+            hint=f"Install or configure '{dependency}' and ensure it is on your PATH.",
+        )
+
+
+class ServiceParseError(AvosError):
+    """Raised when service output cannot be parsed."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(
+            message=message,
+            code=ErrorCode.SERVICE_PARSE_ERROR,
+            hint="This may indicate an upstream format change or a parser defect.",
+        )
+
+
+class ArtifactBuildError(AvosError):
+    """Raised when an artifact cannot be built from its input model."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(
+            message=message,
+            code=ErrorCode.ARTIFACT_BUILD_ERROR,
+        )
+
+
+class StateFileConflictError(AvosError):
+    """Raised when a local state file has a concurrent ownership conflict."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(
+            message=message,
+            code=ErrorCode.STATE_FILE_CONFLICT,
+            hint="Another process may be writing to this file. Wait and retry.",
+            retryable=True,
+        )
+
+
+class IngestLockError(AvosError):
+    """Raised when the ingest lock cannot be acquired."""
+
+    def __init__(self, message: str | None = None, holder_pid: int | None = None) -> None:
+        self.holder_pid = holder_pid
+        super().__init__(
+            message=message or "Another ingest process is running.",
+            code=ErrorCode.INGEST_LOCK_CONFLICT,
+            hint="Wait for the other ingest to finish, or remove .avos/ingest.lock if stale.",
+        )
+
+
+class SanitizationError(AvosError):
+    """Raised when sanitization confidence is below threshold.
+
+    Args:
+        message: Description of the sanitization failure.
+        confidence_score: The computed confidence score that triggered the failure.
+    """
+
+    def __init__(self, message: str, confidence_score: int | None = None) -> None:
+        self.confidence_score = confidence_score
+        super().__init__(
+            message=message,
+            code=ErrorCode.SANITIZATION_FAILED,
+            hint="Sanitization confidence too low for safe synthesis. Falling back to raw results.",
+        )
+
+
+class GroundingError(AvosError):
+    """Raised when citation grounding fails minimum threshold.
+
+    Args:
+        message: Description of the grounding failure.
+        grounded_count: Number of successfully grounded citations.
+        total_count: Total number of citations attempted.
+    """
+
+    def __init__(
+        self, message: str, grounded_count: int = 0, total_count: int = 0
+    ) -> None:
+        self.grounded_count = grounded_count
+        self.total_count = total_count
+        super().__init__(
+            message=message,
+            code=ErrorCode.GROUNDING_FAILED,
+            hint="Synthesis citations could not be verified against retrieved artifacts.",
+        )
+
+
+class LLMSynthesisError(AvosError):
+    """Raised when LLM synthesis fails.
+
+    Args:
+        message: Description of the synthesis failure.
+        failure_class: 'transient' (retryable) or 'non_transient' or 'unknown'.
+    """
+
+    def __init__(self, message: str, failure_class: str = "unknown") -> None:
+        self.failure_class = failure_class
+        retryable = failure_class == "transient"
+        super().__init__(
+            message=message,
+            code=ErrorCode.LLM_SYNTHESIS_ERROR,
+            hint="LLM synthesis failed. Falling back to raw search results.",
+            retryable=retryable,
+        )
+
+
+class ContextBudgetError(AvosError):
+    """Raised when context budget cannot meet minimum evidence floor."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(
+            message=message,
+            code=ErrorCode.CONTEXT_BUDGET_ERROR,
+            hint="Insufficient evidence artifacts for synthesis. Using fallback output.",
+        )
+

avos_cli/models/__init__.py

@@ -0,0 +1,58 @@
+"""Public model re-exports for avos_cli.models.
+
+Import key types from here for convenience:
+    from avos_cli.models import RepoConfig, PRArtifact, SearchResult
+"""
+
+from avos_cli.models.api import NoteResponse, SearchHit, SearchRequest, SearchResult
+from avos_cli.models.artifacts import (
+    CommitArtifact,
+    DocArtifact,
+    IssueArtifact,
+    PRArtifact,
+)
+from avos_cli.models.config import (
+    LLMConfig,
+    RepoConfig,
+)
+from avos_cli.models.query import (
+    BudgetResult,
+    FallbackReason,
+    GroundedCitation,
+    GroundingStatus,
+    QueryMode,
+    QueryResultEnvelope,
+    ReferenceType,
+    RetrievedArtifact,
+    SanitizationResult,
+    SanitizedArtifact,
+    SynthesisRequest,
+    SynthesisResponse,
+    TimelineEvent,
+)
+
+__all__ = [
+    "BudgetResult",
+    "CommitArtifact",
+    "DocArtifact",
+    "FallbackReason",
+    "GroundedCitation",
+    "GroundingStatus",
+    "IssueArtifact",
+    "LLMConfig",
+    "NoteResponse",
+    "PRArtifact",
+    "QueryMode",
+    "QueryResultEnvelope",
+    "ReferenceType",
+    "RepoConfig",
+    "RetrievedArtifact",
+    "SanitizationResult",
+    "SanitizedArtifact",
+    "SearchHit",
+    "SearchRequest",
+    "SearchResult",
+    "SynthesisRequest",
+    "SynthesisResponse",
+    "TimelineEvent",
+]

avos_cli/models/api.py

@@ -0,0 +1,75 @@
+"""API request and response models for the Avos Memory API.
+
+These models define the typed contracts for communication with the
+closed-source Avos Memory API (search, add_memory, delete_note).
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class SearchRequest(BaseModel):
+    """Search request payload for the Avos Memory API.
+
+    Args:
+        query: Natural language search query (min 1 char).
+        k: Number of results to return (1-50, default 5).
+        mode: Search strategy -- 'semantic', 'keyword', or 'hybrid'.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    query: str = Field(..., min_length=1)
+    k: int = Field(default=5, ge=1, le=50)
+    mode: Literal["semantic", "keyword", "hybrid"] = "semantic"
+
+
+class SearchHit(BaseModel):
+    """A single search result from the Avos Memory API.
+
+    Args:
+        note_id: Unique identifier for the matched note.
+        content: Full text content of the note.
+        created_at: ISO 8601 creation timestamp.
+        rank: Relevance rank (1 = best match).
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    note_id: str
+    content: str
+    created_at: str
+    rank: int
+
+
+class SearchResult(BaseModel):
+    """Search response from the Avos Memory API.
+
+    Args:
+        results: List of search hits ordered by relevance.
+        total_count: Total number of notes in the memory.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    results: list[SearchHit]
+    total_count: int
+
+
+class NoteResponse(BaseModel):
+    """Response from add_memory (note creation) in the Avos Memory API.
+
+    Args:
+        note_id: Unique identifier for the created note.
+        content: Text content of the note (or auto-generated description for media).
+        created_at: ISO 8601 server-side creation timestamp.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    note_id: str
+    content: str
+    created_at: str

avos_cli/models/artifacts.py

@@ -0,0 +1,99 @@
+"""Artifact models for AVOS CLI.
+
+These Pydantic models define the input shape for each artifact builder.
+They carry no behavior -- builders consume them to produce structured text.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+class PRArtifact(BaseModel):
+    """Pull request data for the PRThreadBuilder.
+
+    Args:
+        repo: Repository slug 'org/repo'.
+        pr_number: Pull request number.
+        title: PR title.
+        author: PR author username.
+        merged_date: Date the PR was merged (ISO format string, optional).
+        files: List of file paths changed in the PR.
+        description: PR body/description text.
+        discussion: Aggregated comments and review discussion.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    repo: str
+    pr_number: int
+    title: str
+    author: str
+    merged_date: str | None = None
+    files: list[str] = []
+    description: str | None = None
+    discussion: str | None = None
+
+
+class IssueArtifact(BaseModel):
+    """Issue data for the IssueBuilder.
+
+    Args:
+        repo: Repository slug 'org/repo'.
+        issue_number: Issue number.
+        title: Issue title.
+        labels: List of label strings.
+        body: Issue body text.
+        comments: List of comment strings.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    repo: str
+    issue_number: int
+    title: str
+    labels: list[str] = []
+    body: str | None = None
+    comments: list[str] = []
+
+
+class CommitArtifact(BaseModel):
+    """Commit data for the CommitBuilder.
+
+    Args:
+        repo: Repository slug 'org/repo'.
+        hash: Commit hash (short or full).
+        message: Commit message.
+        author: Commit author name.
+        date: Commit date (ISO format string).
+        files_changed: List of file paths changed.
+        diff_stats: Summary of lines added/removed.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    repo: str
+    hash: str
+    message: str
+    author: str
+    date: str
+    files_changed: list[str] = []
+    diff_stats: str | None = None
+
+
+class DocArtifact(BaseModel):
+    """Documentation data for the DocBuilder.
+
+    Args:
+        repo: Repository slug 'org/repo'.
+        path: File path of the document within the repo.
+        content_type: Type of document (e.g. 'readme', 'adr', 'design_doc').
+        content: Full text content of the document.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    repo: str
+    path: str
+    content_type: str
+    content: str

avos_cli/models/config.py

@@ -0,0 +1,56 @@
+"""Configuration and state models for AVOS CLI.
+
+Defines RepoConfig (repository-scoped runtime configuration)
+and LLMConfig (LLM provider settings).
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, SecretStr
+
+
+class LLMConfig(BaseModel):
+    """LLM provider configuration.
+
+    Args:
+        provider: LLM provider name (e.g. 'openai', 'anthropic').
+        model: Model identifier string.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    provider: str = "openai"
+    model: str = "gpt-4o"
+
+
+class RepoConfig(BaseModel):
+    """Repository-scoped runtime configuration.
+
+    Loaded from .avos/config.json with env var overlay.
+    Sensitive fields use SecretStr to prevent accidental exposure.
+
+    Args:
+        repo: Repository slug in 'org/repo' format.
+        memory_id: Memory identifier - 'repo:org/repo' for PR history, commits, issues, docs.
+        api_url: Base URL for the Avos Memory API.
+        api_key: API key for Avos Memory (secret).
+        github_token: GitHub personal access token (secret, optional).
+        developer: Developer display name (defaults to git user.name).
+        llm: LLM provider configuration.
+        connected_at: UTC timestamp when the repo was first connected.
+        schema_version: Config schema version for forward compatibility.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    repo: str
+    memory_id: str
+    api_url: str
+    api_key: SecretStr
+    github_token: SecretStr | None = None
+    developer: str | None = None
+    llm: LLMConfig = LLMConfig()
+    connected_at: datetime | None = None
+    schema_version: str = "1"