pari-cli 0.1.0__py3-none-any.whl

pari/edit/indenter.py

@@ -0,0 +1,12 @@
+"""PARI Layer 5: Relative Indentation Normalizer.
+
+Architectural Purpose:
+    LLMs frequently emit replacement blocks whose leading indentation is offset by
+    2 or 4 spaces relative to the target site.
+    The RelativeIndenter calculates the delta between the indentation of the first line
+    of the search block and the replacement block, normalizing subsequent lines.
+"""
+
+def normalize_relative_indentation(search_block: str, replace_block: str) -> str:
+    """Normalize indentation of replacement block to match search block site."""
+    raise NotImplementedError

pari/eval/__init__.py

@@ -0,0 +1,14 @@
+"""PARI Layer 10: Evaluation & Observability Harness.
+
+Architectural Purpose:
+    Closes the universal problem of "vibe coding" (subjective prompt tweaking without objective regression tests).
+    Provides a deterministic local micro-eval suite ($3-$5 per run) and structured observability.
+
+Subsystems:
+    - runner: Micro-eval benchmark runner executing deterministic test cases
+    - judge: Cross-model verification judge (Graptile principle: never evaluate with same model family)
+    - metrics: Quantitative benchmarks (pass rates, token costs, turn counts)
+    - logging: Structured JSON logging (structlog format) for full execution telemetry
+"""
+
+# Placeholder imports will be exported once implementations are added

pari/eval/judge.py

@@ -0,0 +1,21 @@
+"""PARI Layer 10: Cross-Model Verification Judge.
+
+Architectural Purpose:
+    Implements the Graptile Principle:
+    By default, PARI-generated code is evaluated by a different model family than the one
+    that generated it (e.g. Claude generation evaluated by GPT-4o-mini).
+    Prevents self-evaluation confirmation bias.
+"""
+
+from typing import Any, Dict
+
+
+class CrossModelJudge:
+    """Evaluates patch correctness using an independent model family."""
+
+    def __init__(self, judge_model: str = "gpt-4o-mini"):
+        self.judge_model = judge_model
+
+    async def evaluate_patch(self, problem_statement: str, patch_diff: str) -> Dict[str, Any]:
+        """Ask independent judge model to evaluate if patch correctly resolves the issue."""
+        raise NotImplementedError

pari/eval/logging.py

@@ -0,0 +1,19 @@
+"""PARI Layer 10: Structured Observability Logging.
+
+Emits structured JSON events for monitoring, analysis, and debugging.
+Logs events such as tool_call, edit_applied, sandbox_exec, turn_complete.
+"""
+
+from pathlib import Path
+from typing import Any, Optional
+
+
+class StructuredLogger:
+    """Emits newline-delimited JSON logs to stdout or a designated log file."""
+
+    def __init__(self, log_file: Optional[Path] = None):
+        self.log_file = log_file
+
+    def emit(self, event_name: str, **kwargs: Any):
+        """Emit structured telemetry event."""
+        raise NotImplementedError

pari/eval/metrics.py

@@ -0,0 +1,22 @@
+"""PARI Layer 10: Quantitative Evaluation Metrics.
+
+Computes pass rate, mean cost per resolved task, mean turns, and duration.
+"""
+
+from dataclasses import dataclass
+from typing import Any, Dict, List
+
+
+@dataclass
+class EvalMetrics:
+    total_tasks: int
+    passed_tasks: int
+    pass_rate: float
+    total_cost_usd: float
+    mean_cost_per_task: float
+    mean_turns: float
+
+
+def calculate_eval_metrics(results: List[Dict[str, Any]]) -> EvalMetrics:
+    """Compute aggregate benchmark metrics across test runs."""
+    raise NotImplementedError

pari/eval/runner.py

@@ -0,0 +1,34 @@
+"""PARI Layer 10: Micro-Eval Benchmark Runner.
+
+Runs a local micro-benchmark suite ($3-$5 per run) against isolated git worktrees
+and executes deterministic pytest suites to compute exact pass rates.
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class TestCase:
+    id: str
+    issue_description: str
+    test_command: str
+    base_commit: Optional[str] = None
+
+
+@dataclass
+class EvalReport:
+    metrics: Any
+    case_results: List[Dict[str, Any]]
+
+
+class MicroEvalRunner:
+    """Executes evaluation benchmarks across test cases."""
+
+    def __init__(self, workspace: Path):
+        self.workspace = workspace.resolve()
+
+    def run_suite(self, test_cases: List[TestCase]) -> EvalReport:
+        """Run benchmark suite and compile report."""
+        raise NotImplementedError

pari/fs/__init__.py

@@ -0,0 +1,16 @@
+"""PARI Layer 6: Concurrency and File Safety Engine.
+
+Architectural Purpose:
+    Closes Claude Code F3 (File write race conditions tearing files during parallel operations)
+    and path traversal / prefix collision vulnerabilities.
+
+Subsystems:
+    - path: Canonical path resolution via Path.resolve().relative_to()
+    - atomic: Atomic write using temporary file + os.replace() + directory os.fsync()
+    - queue: FileMutationQueue maintaining per-canonical-realpath asyncio locks
+"""
+
+from pari.fs.path import resolve_safe_path
+from pari.fs.atomic import atomic_write, read_file
+
+__all__ = ["resolve_safe_path", "atomic_write", "read_file"]

pari/fs/atomic.py

@@ -0,0 +1,53 @@
+"""PARI Layer 6: Atomic File Write and Sync Protocol.
+
+Architectural Purpose:
+    Closes Claude Code F1 & F3.
+    Writes content to a temporary file in the same directory (guaranteeing same filesystem device),
+    calls os.fsync() on the file descriptor, atomically replaces the target via os.replace(),
+    and flushes the parent directory entry with fsync on POSIX.
+"""
+
+import os
+import tempfile
+from pathlib import Path
+
+
+def atomic_write(target_path: Path, content: str) -> None:
+    """Atomically write content to target_path, preventing partial/torn writes."""
+    target = target_path.resolve()
+    target.parent.mkdir(parents=True, exist_ok=True)
+
+    # Write to a temporary file in the same directory (same filesystem device)
+    fd, temp_path = tempfile.mkstemp(dir=target.parent, prefix=".pari_tmp_")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            f.write(content)
+            f.flush()
+            os.fsync(f.fileno())
+
+        # Atomic replacement
+        os.replace(temp_path, target)
+
+        # Sync parent directory on POSIX
+        if os.name == "posix":
+            try:
+                parent_fd = os.open(str(target.parent), os.O_RDONLY | os.O_DIRECTORY)
+                try:
+                    os.fsync(parent_fd)
+                finally:
+                    os.close(parent_fd)
+            except (OSError, PermissionError):
+                pass
+    except Exception:
+        if os.path.exists(temp_path):
+            try:
+                os.remove(temp_path)
+            except OSError:
+                pass
+        raise
+
+
+def read_file(file_path: Path) -> str:
+    """Read full text content of a file."""
+    return file_path.resolve().read_text(encoding="utf-8")
+

pari/fs/path.py

@@ -0,0 +1,28 @@
+"""PARI Layer 6: Safe Canonical Path Resolution.
+
+Architectural Purpose:
+    Prevents path traversal attacks (e.g. ../../etc/shadow) and path prefix collisions
+    (e.g., /workspace_evil matching /workspace in string-prefix checks).
+    Enforces that resolved canonical paths reside strictly within authorized workspace roots.
+"""
+
+from pathlib import Path
+from typing import Union
+
+
+def resolve_safe_path(workspace_root: Union[str, Path], target_path: Union[str, Path]) -> Path:
+    """Resolve a target path safely relative to the workspace root."""
+    root = Path(workspace_root).resolve()
+    target = Path(target_path)
+    if not target.is_absolute():
+        resolved = (root / target).resolve()
+    else:
+        resolved = target.resolve()
+
+    try:
+        resolved.relative_to(root)
+    except ValueError:
+        raise PermissionError(f"Path traversal rejected: '{target_path}' is outside workspace '{workspace_root}'")
+
+    return resolved
+

pari/fs/queue.py

@@ -0,0 +1,22 @@
+"""PARI Layer 6: File Mutation Queue.
+
+Architectural Purpose:
+    Harvested from Pi's file-mutation-queue.ts.
+    Maintains a registry of asyncio.Lock primitives keyed by canonical realpath.
+    Serializes concurrent writes to the same physical file while allowing parallel
+    writes to distinct files.
+"""
+
+import asyncio
+from pathlib import Path
+
+
+class FileMutationQueue:
+    """Serializes concurrent write mutations per canonical filesystem path."""
+
+    def __init__(self):
+        pass
+
+    async def get_lock(self, file_path: Path) -> asyncio.Lock:
+        """Get canonical per-path lock."""
+        raise NotImplementedError

pari/intelligence/__init__.py

@@ -0,0 +1,15 @@
+"""PARI Layer 3: Codebase Intelligence & Navigation Layer.
+
+Architectural Purpose:
+    Closes Pi F3 (Blind file traversal loops requiring 8+ grep turns) and
+    Aider F4 (Personalized PageRank hub distortion from generic utility sinks).
+
+Subsystems:
+    - search: Fast file globbing & ripgrep substring search (v1 primary navigation)
+    - ast: Tree-sitter AST symbol extractor across Python, TypeScript, Go, Rust
+    - ppr: Personalized PageRank graph ranking with hub suppression (>50 inbound refs dampened)
+    - repomap: 2,048-token binary-search packing for the static context repo map
+    - cache: Worktree-scoped SQLite symbol cache preventing lock collisions
+"""
+
+# Placeholder imports will be exported once implementations are added

pari/intelligence/ast.py

@@ -0,0 +1,25 @@
+"""PARI Layer 3: Tree-sitter AST Symbol Extractor.
+
+Architectural Purpose:
+    Extracts high-signal structural definitions (classes, functions, methods, imports)
+    from source code without reading full file bodies into prompt context.
+    Degrades gracefully to regex/heuristic parsing when tree-sitter bindings are not installed.
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List
+
+
+@dataclass
+class SymbolInfo:
+    file_path: str
+    symbol_name: str
+    kind: str  # "class", "function", "method", "variable"
+    line_number: int
+    signature: str
+
+
+def extract_symbols(file_path: Path, content: str) -> List[SymbolInfo]:
+    """Extract symbols from source code."""
+    raise NotImplementedError

pari/intelligence/cache.py

@@ -0,0 +1,21 @@
+"""PARI Layer 3: Worktree-Scoped Symbol Cache.
+
+Architectural Purpose:
+    Closes Aider F6 (Diskcache SQLite lock collisions across git worktrees).
+    Scans and caches AST tags with SQLite database files scoped explicitly to the
+    unique worktree root path, eliminating multi-session database locking errors.
+"""
+
+from pathlib import Path
+from typing import Optional
+
+
+class WorktreeSymbolCache:
+    """Manages cached symbol index keyed specifically to workspace path and file mtimes."""
+
+    def __init__(self, workspace: Path, cache_dir: Optional[Path] = None):
+        self.workspace = workspace.resolve()
+
+    def get_db_path(self) -> Path:
+        """Return path to workspace-isolated SQLite cache file."""
+        raise NotImplementedError

pari/intelligence/ppr.py

@@ -0,0 +1,21 @@
+"""PARI Layer 3: Personalized PageRank with Hub Suppression.
+
+Architectural Purpose:
+    Closes Aider F4 (PageRank hub distortion).
+    In naive PageRank, generic utilities like `utils.py` or `helpers.py` accumulate
+    hundreds of inbound edges and crowd out crucial business logic in a 2,048-token budget.
+    PARI applies a hub suppression dampener: any node with >50 inbound references
+    has its rank dynamically dampened, prioritizing domain-specific classes and interfaces.
+"""
+
+from typing import Dict, List, Set, Tuple
+
+
+def compute_personalized_pagerank(
+    graph_edges: List[Tuple[str, str]],
+    personalized_targets: Set[str],
+    damping_factor: float = 0.85,
+    hub_threshold: int = 50,
+) -> Dict[str, float]:
+    """Compute personalized PageRank scores with dampening for high-indegree utility hubs."""
+    raise NotImplementedError

pari/intelligence/repomap.py

@@ -0,0 +1,21 @@
+"""PARI Layer 3: Repo Map Generator & Token Packer.
+
+Architectural Purpose:
+    Packs codebase structural symbols into a strict token budget (default 2,048 tokens)
+    using binary-search selection based on PPR rankings.
+"""
+
+from pathlib import Path
+from typing import List, Optional
+
+
+class RepoMapGenerator:
+    """Generates condensed repository map from parsed source symbols."""
+
+    def __init__(self, workspace: Path, max_tokens: int = 2048):
+        self.workspace = workspace.resolve()
+        self.max_tokens = max_tokens
+
+    def generate(self, focus_files: Optional[List[str]] = None) -> str:
+        """Scan workspace, extract symbols, and format condensed outline."""
+        raise NotImplementedError

pari/intelligence/search.py

@@ -0,0 +1,33 @@
+"""PARI Layer 3: Substring & Globbing Search Engine (v1 Baseline Navigation).
+
+Architectural Purpose:
+    Provides fast, deterministic code search without requiring C-extension compilation.
+    Enforces ignore boundaries (.git, .venv, node_modules, build artifacts).
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional
+
+
+@dataclass
+class GrepMatch:
+    file_path: str
+    line_number: int
+    line_content: str
+
+
+def find_files(workspace_root: Path, pattern: str = "*", max_results: int = 100) -> List[str]:
+    """Find files in workspace matching a glob pattern, respecting ignore rules."""
+    raise NotImplementedError
+
+
+def grep_search(
+    workspace_root: Path,
+    query: str,
+    is_regex: bool = False,
+    path_filter: str = "*",
+    max_matches: int = 50,
+) -> List[GrepMatch]:
+    """Search for query across files in workspace, returning matches with line numbers."""
+    raise NotImplementedError

pari/output/__init__.py

@@ -0,0 +1,14 @@
+"""PARI Layer 7: Output Handling and Context Hygiene.
+
+Architectural Purpose:
+    Closes the #1 failure mode in the Failure Mode Atlas: Unbounded stdout poisoning.
+    Prevents large tool outputs (e.g. cat massive.log, npm install, pytest) from flooding
+    the model's context window and displacing core instructions.
+
+Subsystems:
+    - spooler: 50KB / 2k-line disk spooler storing raw outputs in sidecar files
+    - truncation: Head/tail extraction preserving stack traces and return headers
+    - parser: Structured test failure extractors (pytest, jest, cargo)
+"""
+
+# Placeholder imports will be exported once implementations are added

pari/output/parser.py

@@ -0,0 +1,14 @@
+"""PARI Layer 7: Structured Test Output Parser.
+
+Architectural Purpose:
+    Extracts high-signal test failure summaries from raw test output (pytest, jest, cargo),
+    allowing the model to immediately grasp failing assertions without digesting
+    100s of lines of framework internals.
+"""
+
+from typing import List
+
+
+def parse_test_failures(raw_output: str) -> List[str]:
+    """Parse failure lines from test runner output."""
+    raise NotImplementedError

pari/output/spooler.py

@@ -0,0 +1,33 @@
+"""PARI Layer 7: Managed Output Disk Spooler.
+
+Architectural Purpose:
+    Closes Codex F4 (RSS bloat on large outputs) & OpenCode 50KB output cap.
+    Streams subprocess output into a temporary disk sidecar file.
+    If output exceeds max_bytes (default 50KB) or max_lines (default 2,000 lines),
+    it generates a sanitized head/tail summary for prompt injection while preserving
+    the full output on disk for on-demand inspection via /spool command.
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+
+@dataclass
+class SpoolResult:
+    context_text: str
+    sidecar_path: Path
+    total_bytes: int
+    total_lines: int
+    was_truncated: bool
+
+
+class ManagedOutputSpooler:
+    """Spools process output to disk sidecars and extracts safe context summaries."""
+
+    def __init__(self, spool_dir: Optional[Path] = None, max_bytes: int = 50 * 1024):
+        self.max_bytes = max_bytes
+
+    def spool(self, raw_output: str, command_tag: str = "cmd") -> SpoolResult:
+        """Spool output to disk sidecar and return truncated context text if large."""
+        raise NotImplementedError

pari/output/truncation.py

@@ -0,0 +1,20 @@
+"""PARI Layer 7: Head/Tail Truncation with Context Preservation.
+
+Architectural Purpose:
+    When output exceeds the context budget:
+    1. Keeps the first N lines (command launch, build headers).
+    2. Keeps the last M lines (stack traces, exit assertions, summary errors).
+    3. Injects a clear omission notice linking to the disk sidecar containing full raw output.
+"""
+
+from typing import Tuple
+
+
+def extract_head_tail(
+    text: str,
+    head_lines: int = 50,
+    tail_lines: int = 100,
+    sidecar_path: str = "",
+) -> Tuple[str, bool]:
+    """Truncate text by extracting head and tail sections if line count is high."""
+    raise NotImplementedError

pari/providers/__init__.py

@@ -0,0 +1,24 @@
+"""PARI Multi-Provider LLM Integration Layer.
+
+Architectural Purpose:
+    Closes Antigravity F5 (Hard Google API lock-in) and Claude Code Anthropic exclusivity.
+    Provides unified model abstraction across Anthropic Claude, OpenAI, DeepSeek, local Ollama,
+    and an offline fallback provider for local testing.
+"""
+
+from typing import Optional
+from pari.providers.base import LLMProvider, ProviderMessage, ModelResponse, ToolCall
+
+
+def get_provider(model_name: Optional[str] = None) -> LLMProvider:
+    """Instantiate the best available LLM provider based on model name and environment."""
+    raise NotImplementedError
+
+
+__all__ = [
+    "LLMProvider",
+    "ProviderMessage",
+    "ModelResponse",
+    "ToolCall",
+    "get_provider",
+]

pari/providers/anthropic.py

@@ -0,0 +1,23 @@
+"""PARI Providers: Anthropic Claude Adapter.
+
+Supports Claude 3.7 Sonnet, Claude 3.5 Sonnet, and Claude 3.5 Haiku with prompt caching.
+"""
+
+from typing import Any, Dict, List, Optional
+from pari.providers.base import LLMProvider, ModelResponse, ProviderMessage
+
+
+class AnthropicProvider(LLMProvider):
+    """Adapter for Anthropic Messages API."""
+
+    def __init__(self, model_name: str = "claude-3-7-sonnet-20250219", api_key: Optional[str] = None):
+        super().__init__(model_name, api_key)
+
+    async def complete(
+        self,
+        messages: List[ProviderMessage],
+        tools: Optional[List[Dict[str, Any]]] = None,
+        temperature: float = 0.0,
+    ) -> ModelResponse:
+        """Call Anthropic Messages API with prompt caching."""
+        raise NotImplementedError

pari/providers/base.py

@@ -0,0 +1,56 @@
+"""PARI Providers: Base LLM Interface.
+
+Defines the contract for calling LLM inference APIs with tool calling and prompt caching.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class ToolCall:
+    id: str
+    name: str
+    arguments: Dict[str, Any]
+
+
+@dataclass
+class ProviderMessage:
+    role: str  # "system", "user", "assistant", "tool"
+    content: str
+    tool_calls: Optional[List[ToolCall]] = None
+    tool_call_id: Optional[str] = None
+    cache_control: bool = False
+
+
+@dataclass
+class ModelResponse:
+    text: str
+    tool_calls: List[ToolCall] = field(default_factory=list)
+    tokens_in: int = 0
+    tokens_out: int = 0
+    cached_tokens: int = 0
+    stop_reason: Optional[str] = None
+
+    @property
+    def has_tool_calls(self) -> bool:
+        return len(self.tool_calls) > 0
+
+
+class LLMProvider(ABC):
+    """Abstract base class for all LLM backend adapters."""
+
+    def __init__(self, model_name: str, api_key: Optional[str] = None):
+        self.model_name = model_name
+        self.api_key = api_key
+
+    @abstractmethod
+    async def complete(
+        self,
+        messages: List[ProviderMessage],
+        tools: Optional[List[Dict[str, Any]]] = None,
+        temperature: float = 0.0,
+    ) -> ModelResponse:
+        """Execute a completion request."""
+        raise NotImplementedError

pari/providers/deepseek.py

@@ -0,0 +1,24 @@
+"""PARI Providers: DeepSeek Adapter.
+
+Supports DeepSeek V3 and DeepSeek R1 via OpenAI-compatible API endpoint.
+High performance, cost-effective editor tier model ($0.27/M input, $1.10/M output).
+"""
+
+from typing import Any, Dict, List, Optional
+from pari.providers.base import LLMProvider, ModelResponse, ProviderMessage
+
+
+class DeepSeekProvider(LLMProvider):
+    """Adapter for DeepSeek API using OpenAI-compatible interface."""
+
+    def __init__(self, model_name: str = "deepseek-chat", api_key: Optional[str] = None):
+        super().__init__(model_name, api_key)
+
+    async def complete(
+        self,
+        messages: List[ProviderMessage],
+        tools: Optional[List[Dict[str, Any]]] = None,
+        temperature: float = 0.0,
+    ) -> ModelResponse:
+        """Call DeepSeek chat API."""
+        raise NotImplementedError

pari/providers/mock.py

@@ -0,0 +1,46 @@
+"""PARI Providers: Offline / Mock Provider for local testing and dry-runs.
+
+Enables offline testing of the agent loop, tool execution, session recovery,
+and diff review without requiring remote cloud API tokens.
+"""
+
+from typing import Any, Dict, List, Optional
+from pari.providers.base import LLMProvider, ModelResponse, ProviderMessage
+
+
+class MockOfflineProvider(LLMProvider):
+    """Fallback provider when no cloud API keys are configured."""
+
+    def __init__(self, model_name: str = "mock-offline"):
+        super().__init__(model_name, api_key="offline")
+
+    async def complete(
+        self,
+        messages: List[ProviderMessage],
+        tools: Optional[List[Dict[str, Any]]] = None,
+        temperature: float = 0.0,
+    ) -> ModelResponse:
+        """Simulate completion for local testing."""
+        last_prompt = messages[-1].content if messages else ""
+        lower_prompt = last_prompt.lower()
+
+        # If user asks to find python files, simulate a tool call or answer
+        if "find" in lower_prompt or "python" in lower_prompt:
+            return ModelResponse(
+                text="PARI Agent: Found python files in workspace.",
+                tool_calls=[],
+                tokens_in=120,
+                tokens_out=40,
+                cached_tokens=0,
+                stop_reason="end_turn",
+            )
+
+        return ModelResponse(
+            text=f"PARI Agent response to: {last_prompt}",
+            tool_calls=[],
+            tokens_in=80,
+            tokens_out=30,
+            cached_tokens=0,
+            stop_reason="end_turn",
+        )
+