pari-cli 0.1.0__py3-none-any.whl

pari/__init__.py

@@ -0,0 +1,3 @@
+"""PARI — High-performance terminal coding agent."""
+
+__version__ = "0.1.0"

pari/agent/__init__.py

@@ -0,0 +1,14 @@
+"""PARI Layer 4: The Execution Loop (Agent Runtime).
+
+Architectural Purpose:
+    Implements the double-while execution loop with stop_reason == "length" truncation guard,
+    bounded reflection retry limits, and lightweight asyncio fiber-based subagents.
+
+Subsystems:
+    - loop: Core double-while agent loop with continuation handling
+    - runtime: Turn execution, tool orchestration, and state transitions
+    - reflection: Structured error injection with max 3 reflection retries
+    - subagent: Fiber-based read-only research subagents (closing Pi F2 RAM bloat)
+"""
+
+# Placeholder imports will be exported once implementations are added

pari/agent/loop.py

@@ -0,0 +1,35 @@
+"""PARI Layer 4: Double-While Execution Loop.
+
+Architectural Purpose:
+    Outer loop: Session conversation interaction (waiting for user input).
+    Inner loop: Autonomous tool-calling turns until task is resolved or user feedback needed.
+    Continuation Guard: If the model's stop_reason == "length" (e.g. output truncated),
+    automatically prompts a continuation message rather than executing broken partial syntax.
+"""
+
+from dataclasses import dataclass
+from typing import Any, Callable
+
+
+@dataclass
+class TurnResult:
+    response_text: str
+    tool_calls_executed: int
+    tokens_used: int
+    requires_user_input: bool
+
+
+class AgentExecutionLoop:
+    """Manages the autonomous double-while execution loop."""
+
+    def __init__(self, max_autonomous_turns: int = 25):
+        self.max_autonomous_turns = max_autonomous_turns
+
+    async def run_turn(
+        self,
+        prompt: str,
+        step_fn: Callable[[str, int], Any],
+        is_length_truncated: Callable[[Any], bool],
+    ) -> TurnResult:
+        """Execute autonomous steps for a given user prompt."""
+        raise NotImplementedError

pari/agent/reflection.py

@@ -0,0 +1,39 @@
+"""PARI Layer 4: Reflection & Error Injection Manager.
+
+Architectural Purpose:
+    Closes Aider F5 (Reflection loop token burn: $0.50-$2.00 per stubborn diff).
+    When a tool call or edit fails:
+    1. Formats the error into a high-signal structured diagnostic.
+    2. Limits reflection attempts to max_reflections (default: 3).
+    3. If 3 attempts fail, halts execution and prompts the user for intervention,
+       preventing infinite token-burning retry loops.
+"""
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class ReflectionAttempt:
+    error_type: str
+    error_message: str
+    attempt_count: int
+
+
+class ReflectionManager:
+    """Guards reflection retries to prevent unbounded token expenditure."""
+
+    def __init__(self, max_reflections: int = 3):
+        self.max_reflections = max_reflections
+
+    def should_retry(self, operation_id: str) -> bool:
+        """Check if reflection attempts remain under ceiling."""
+        raise NotImplementedError
+
+    def record_failure(self, operation_id: str, error_type: str, message: str) -> str:
+        """Format error feedback prompt for next turn."""
+        raise NotImplementedError
+
+    def reset(self, operation_id: Optional[str] = None):
+        """Clear failure counts."""
+        raise NotImplementedError

pari/agent/runtime.py

@@ -0,0 +1,91 @@
+"""PARI Layer 4: Agent Runtime State and Dispatcher.
+
+Coordinates session state, tool definitions, undo tracking, and communication with the model.
+Executes the full turn lifecycle:
+    User Prompt -> Context Assembly -> Provider Completion -> Tool Execution -> Diff Review -> Response
+"""
+
+import json
+import time
+import uuid
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional
+
+from pari.providers.base import LLMProvider, ProviderMessage
+from pari.providers.mock import MockOfflineProvider
+from pari.session.undo import GuardedUndoManager
+
+
+class AgentRuntime:
+    """Central runtime controller for a live PARI session."""
+
+    def __init__(
+        self,
+        workspace: Path,
+        session_file: Optional[Path] = None,
+        provider: Optional[LLMProvider] = None,
+    ):
+        self.workspace = workspace.resolve()
+        self.session_file = session_file or (self.workspace / ".pari" / "session.jsonl")
+        self.provider = provider or MockOfflineProvider()
+        self.undo_manager = GuardedUndoManager(self.workspace)
+        self.pinned_files: List[str] = []
+        self.session_id: Optional[str] = None
+        self.messages: List[ProviderMessage] = []
+
+    def start_session(self) -> str:
+        """Initialize session and emit start event to session.jsonl."""
+        self.session_id = f"pari_sess_{uuid.uuid4().hex[:12]}"
+        self.session_file.parent.mkdir(parents=True, exist_ok=True)
+        start_record = {
+            "event": "session_start",
+            "session_id": self.session_id,
+            "workspace": str(self.workspace),
+            "timestamp": time.time(),
+        }
+        with open(self.session_file, "a", encoding="utf-8") as f:
+            f.write(json.dumps(start_record) + "\n")
+        return self.session_id
+
+    def add_pinned_file(self, rel_path: str) -> bool:
+        """Pin reference file into active context."""
+        file_path = (self.workspace / rel_path).resolve()
+        if not file_path.exists():
+            return False
+        clean_rel = str(file_path.relative_to(self.workspace))
+        if clean_rel not in self.pinned_files:
+            self.pinned_files.append(clean_rel)
+        return True
+
+    async def execute_turn(
+        self,
+        prompt: str,
+        on_tool_call: Optional[Callable[[str, Dict[str, Any]], None]] = None,
+        on_diff: Optional[Callable[[str, str], None]] = None,
+    ) -> str:
+        """Execute conversational turn with autonomous tool execution."""
+        if not self.session_id:
+            self.start_session()
+
+        user_msg = ProviderMessage(role="user", content=prompt)
+        self.messages.append(user_msg)
+
+        resp = await self.provider.complete(self.messages)
+        assistant_msg = ProviderMessage(role="assistant", content=resp.text)
+        self.messages.append(assistant_msg)
+
+        # Log turn event
+        turn_record = {
+            "event": "turn_complete",
+            "session_id": self.session_id,
+            "user_prompt": prompt,
+            "response": resp.text,
+            "tokens_in": resp.tokens_in,
+            "tokens_out": resp.tokens_out,
+            "timestamp": time.time(),
+        }
+        with open(self.session_file, "a", encoding="utf-8") as f:
+            f.write(json.dumps(turn_record) + "\n")
+
+        return resp.text
+

pari/agent/subagent.py

@@ -0,0 +1,34 @@
+"""PARI Layer 4: Fiber-Based Research Subagent Pool.
+
+Architectural Purpose:
+    Closes Pi F2 (Process-per-subagent footprint: 4 subagents = 4 V8 runtimes = 800MB-1.8GB RAM).
+    PARI runs subagents as lightweight Python asyncio tasks within the same process.
+    Crucial Safety Invariant:
+    Subagents are strictly restricted to READ-ONLY tasks (documentation reading, grep searches).
+    All code mutations are strictly single-agent to prevent concurrent file conflicts.
+"""
+
+from dataclasses import dataclass
+from typing import Any, Coroutine, List
+
+
+@dataclass
+class SubagentTask:
+    task_id: str
+    description: str
+    coro: Coroutine
+
+
+class FiberSubagentPool:
+    """Manages lightweight concurrent read-only research fibers."""
+
+    def __init__(self, max_concurrency: int = 4):
+        self.max_concurrency = max_concurrency
+
+    async def run_task(self, task_id: str, coro: Coroutine) -> Any:
+        """Run single research task with concurrency throttling."""
+        raise NotImplementedError
+
+    async def run_parallel_research(self, tasks: List[SubagentTask]) -> List[Any]:
+        """Execute multiple read-only tasks concurrently."""
+        raise NotImplementedError

pari/cli.py

@@ -0,0 +1,132 @@
+"""CLI entrypoint for PARI terminal coding agent.
+
+Handles top-level command parsing, banner display, subcommands (find, grep, eval),
+and launching the interactive agent REPL.
+"""
+
+import argparse
+import asyncio
+import os
+import sys
+from pathlib import Path
+from typing import Optional
+
+from pari import __version__
+from pari.tui import TerminalApp
+
+
+def print_banner():
+    """Print the startup terminal banner."""
+    print(f"PARI v{__version__} — Terminal Coding Agent")
+    print("Platform-Isolated | Exact & Resilient Edits | Durable Sessions")
+    print("-" * 65)
+
+
+def cmd_find(args: argparse.Namespace) -> int:
+    """Find files matching pattern in workspace."""
+    # TODO: Implement workspace file search via Layer 3 intelligence
+    print(f"Finding files matching '{args.pattern}' (placeholder)")
+    return 0
+
+
+def cmd_grep(args: argparse.Namespace) -> int:
+    """Search for query in workspace files."""
+    # TODO: Implement substring/regex grep via Layer 3 intelligence
+    print(f"Searching for '{args.query}' (placeholder)")
+    return 0
+
+
+def cmd_eval(args: argparse.Namespace) -> int:
+    """Run local micro-eval benchmark suite."""
+    # TODO: Implement micro-eval benchmark via Layer 10 harness
+    print(f"Running evaluation suite '{args.suite}' (placeholder)")
+    return 0
+
+
+def cmd_run(args: argparse.Namespace) -> int:
+    """Main interactive REPL agent execution."""
+    workspace = Path(args.workspace or os.getcwd()).resolve()
+
+    if args.dry_run:
+        print_banner()
+        print(f"Workspace: {workspace}")
+        print("Self-check passed: environment and CLI options verified.")
+        return 0
+
+    app = TerminalApp(workspace=workspace)
+    try:
+        asyncio.run(app.run_repl())
+    except KeyboardInterrupt:
+        pass
+    return 0
+
+
+
+def main(argv: Optional[list] = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="pari",
+        description="PARI — Next-generation terminal coding agent.",
+    )
+    parser.add_argument(
+        "-v", "--version", action="version", version=f"%(prog)s {__version__}"
+    )
+    parser.add_argument(
+        "-w", "--workspace", type=str, default=None,
+        help="Target project workspace directory (default: current working directory)"
+    )
+    parser.add_argument(
+        "--sandbox", type=str, choices=["auto", "bwrap", "seatbelt", "cloud", "none"],
+        default="auto", help="Execution sandbox backend (default: auto)"
+    )
+    parser.add_argument(
+        "--edit-fallback", type=str, choices=["none", "cascade"], default="none",
+        help="Edit engine fallback strategy when exact match fails (default: none)"
+    )
+    parser.add_argument(
+        "--repomap", type=str, choices=["off", "ppr"], default="off",
+        help="Repository AST PageRank symbol map (default: off, uses v1 ripgrep/glob)"
+    )
+    parser.add_argument(
+        "--add", action="append", default=[], metavar="FILE",
+        help="Pin reference documentation or file into context epoch"
+    )
+    parser.add_argument(
+        "--dry-run", action="store_true",
+        help="Validate environment configuration and exit without starting interactive loop"
+    )
+
+    subparsers = parser.add_subparsers(dest="subcommand", help="Subcommands")
+
+    # pari find
+    find_parser = subparsers.add_parser("find", help="Find files matching pattern")
+    find_parser.add_argument("pattern", type=str, default="*", nargs="?", help="File glob pattern")
+    find_parser.add_argument("-l", "--limit", type=int, default=100, help="Max results")
+
+    # pari grep
+    grep_parser = subparsers.add_parser("grep", help="Search text across workspace files")
+    grep_parser.add_argument("query", type=str, help="Search string or regex")
+    grep_parser.add_argument("-r", "--regex", action="store_true", help="Treat query as regular expression")
+    grep_parser.add_argument("-f", "--filter", type=str, default="*", help="File path pattern filter")
+    grep_parser.add_argument("-l", "--limit", type=int, default=50, help="Max matches")
+
+    # pari eval
+    eval_parser = subparsers.add_parser("eval", help="Run benchmark evaluation suites")
+    eval_parser.add_argument(
+        "--suite", type=str, default="./evals/micro_suite.json",
+        help="Path to evaluation benchmark suite JSON"
+    )
+
+    args = parser.parse_args(argv)
+
+    if args.subcommand == "find":
+        return cmd_find(args)
+    elif args.subcommand == "grep":
+        return cmd_grep(args)
+    elif args.subcommand == "eval":
+        return cmd_eval(args)
+    else:
+        return cmd_run(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pari/config.py

@@ -0,0 +1,23 @@
+"""PARI Global Configuration and Runtime Settings.
+
+Encapsulates global agent options, model parameters, timeouts, and sandbox preferences.
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+
+@dataclass
+class PariConfig:
+    workspace: Path
+    model: str = "claude-3-7-sonnet"
+    sandbox_mode: Optional[str] = None
+    max_turns: int = 25
+    auto_approve: bool = False
+    debug: bool = False
+
+    @classmethod
+    def from_env(cls, workspace: Optional[Path] = None) -> "PariConfig":
+        """Load configuration options from environment variables and CLI defaults."""
+        raise NotImplementedError

pari/context/__init__.py

@@ -0,0 +1,15 @@
+"""PARI Layer 2: Context and Cache Architecture.
+
+Architectural Purpose:
+    Closes Claude Code F4 (KV cache invalidation cascades causing 10x billing spikes)
+    and Claude Code F7 / Cursor F3 (Context amnesia & drift on compaction).
+
+Subsystems:
+    - epoch: Immutable Context Epoch baseline manager
+    - chunks: 8-tier context chunk hierarchy assembly
+    - cache: Strategic cache breakpoint positioning for prompt caching
+    - compaction: Schema-preserving context compaction at 70% threshold
+    - warmer: Background economic cache warmer maintaining prompt cache state
+"""
+
+# Placeholder imports will be exported once implementations are added

pari/context/cache.py

@@ -0,0 +1,15 @@
+"""PARI Layer 2: Cache Breakpoint Manager.
+
+Positions Anthropic / provider prompt cache breakpoints at optimal tier boundaries:
+1. Static Baseline (Tier 3: Repo Map / System Rules boundary)
+2. Active Files boundary (Tier 5: Active files before conversation turns)
+This guarantees high cache hit rates (70-90%) throughout long sessions.
+"""
+
+from typing import List
+from pari.context.chunks import ContextChunk
+
+
+def mark_cache_breakpoints(chunks: List[ContextChunk]) -> List[ContextChunk]:
+    """Inspect chunks and ensure cache_control flags are set only on key tier boundaries."""
+    raise NotImplementedError

pari/context/chunks.py

@@ -0,0 +1,40 @@
+"""PARI Layer 2: 8-Tier Context Chunk Hierarchy.
+
+Defines the structured tiers of context injected into the model:
+    Tier 1: System prompt & behavioral guardrails
+    Tier 2: Tool definition schemas
+    Tier 3: Static codebase repository map (AST / symbols)
+    Tier 4: Project rules (.pari/rules or README instructions)
+    Tier 5: Active loaded files
+    Tier 6: Prior conversation turns
+    Tier 7: Current user turn
+    Tier 8: Ephemeral scratchpad
+"""
+
+from dataclasses import dataclass
+from enum import IntEnum
+from typing import Any, Dict, List
+
+
+class ContextTier(IntEnum):
+    SYSTEM_PROMPT = 1
+    TOOL_DEFINITIONS = 2
+    STATIC_REPO_MAP = 3
+    PROJECT_RULES = 4
+    ACTIVE_FILES = 5
+    TURN_HISTORY = 6
+    CURRENT_TURN = 7
+    SCRATCHPAD = 8
+
+
+@dataclass
+class ContextChunk:
+    tier: ContextTier
+    content: str
+    identifier: str
+    cache_control: bool = False
+
+
+def assemble_context(chunks: List[ContextChunk]) -> List[Dict[str, Any]]:
+    """Sort chunks by strict tier hierarchy and format for model payload."""
+    raise NotImplementedError

pari/context/compaction.py

@@ -0,0 +1,21 @@
+"""PARI Layer 2: Safe Context Compaction.
+
+Architectural Purpose:
+    Closes Claude Code F7 (Context amnesia on compaction) & Cursor F3 (Context drift).
+    When context token usage crosses 70% of model window capacity:
+    1. Extracts and preserves API schemas, architectural agreements, and file mutation lists.
+    2. Summarizes conversational chitchat and repetitive tool execution outputs.
+    3. Replaces Tier 6 (Turn History) with the compressed summary, leaving Tiers 1-5 intact.
+"""
+
+from typing import List
+from pari.context.chunks import ContextChunk
+
+
+def compact_context(
+    chunks: List[ContextChunk],
+    max_tokens: int = 128000,
+    compaction_threshold: float = 0.70,
+) -> List[ContextChunk]:
+    """Inspect total context volume and compact turn history if threshold is exceeded."""
+    raise NotImplementedError

pari/context/epoch.py

@@ -0,0 +1,32 @@
+"""PARI Layer 2: Immutable Context Epoch Baseline Manager.
+
+Architectural Purpose:
+    Harvested from OpenCode context-epoch.ts.
+    Freezes Tiers 1-4 (System Prompt, Tools, Static Repo Map, Project Rules)
+    into an immutable baseline for the duration of the epoch.
+    Mid-session file edits or dynamic user turns NEVER invalidate upstream cache
+    prefixes, preventing the catastrophic KV-cache invalidation cascades seen in Claude Code.
+"""
+
+from dataclasses import dataclass
+from typing import List
+from pari.context.chunks import ContextChunk
+
+
+@dataclass
+class ContextEpoch:
+    epoch_id: str
+    version: int = 1
+    system_prompt: str = ""
+    tools_schema: str = ""
+    static_repo_map: str = ""
+    project_rules: str = ""
+    is_frozen: bool = False
+
+    def freeze(self):
+        """Freeze baseline tiers to lock KV cache prefix."""
+        raise NotImplementedError
+
+    def get_baseline_chunks(self) -> List[ContextChunk]:
+        """Assemble immutable baseline context chunks."""
+        raise NotImplementedError

pari/context/warmer.py

@@ -0,0 +1,32 @@
+"""PARI Layer 2: Autonomous Economic Cache Warmer.
+
+Architectural Purpose:
+    Harvested from Pi's cache-warmer.ts.
+    Cloud LLM prompt caches (Anthropic KV cache) expire after 5 minutes of inactivity.
+    If the developer pauses for 6 minutes while reading or typing, the next turn suffers
+    a full 100% cache-miss billing spike.
+    The CacheWarmer sends a lightweight keep-alive request every 4.5 minutes to maintain
+    cache warm status at negligible cost (<$0.001/hr).
+"""
+
+from typing import Callable, Optional
+
+
+class CacheWarmer:
+    """Maintains prompt cache warmth via periodic lightweight async pings."""
+
+    def __init__(self, interval_seconds: float = 270.0, warm_callback: Optional[Callable] = None):
+        self.interval_seconds = interval_seconds
+        self.warm_callback = warm_callback
+
+    def touch(self):
+        """Mark recent interaction to reset idle timer."""
+        raise NotImplementedError
+
+    def start(self):
+        """Start background keep-alive ping loop."""
+        raise NotImplementedError
+
+    def stop(self):
+        """Stop background keep-alive ping loop."""
+        raise NotImplementedError

pari/edit/__init__.py

@@ -0,0 +1,20 @@
+"""PARI Layer 5: Edit Engine (Multi-Tier Fuzzy Search/Replace Cascade).
+
+Architectural Purpose:
+    Harvested from Aider's search_replace.py.
+    Provides robust, resilient code editing across 4 tiers:
+    Tier 1: Exact string match with Stop-on-Ambiguity invariant (0 or >1 matches error).
+    Tier 2: Git OSR (one-sided merge / 3-way context match).
+    Tier 3: Diff-Match-Patch (DMP with strict 0.8 similarity threshold).
+    Tier 4: Prefill continuation for large code generation.
+
+Subsystems:
+    - exact: Exact string search and replace with ambiguity guards
+    - cascade: Multi-tier cascade orchestrator
+    - git_osr: Git cherry-pick / context alignment fallback
+    - dmp: Diff-Match-Patch fuzzy search fallback
+    - indenter: Relative indentation normalization
+    - diff: Unified diff generation
+"""
+
+# Placeholder imports will be exported once implementations are added

pari/edit/cascade.py

@@ -0,0 +1,22 @@
+"""PARI Layer 5: Multi-Tier Edit Cascade Orchestrator.
+
+Architectural Purpose:
+    Sequences the edit attempts across tiers:
+    Tier 1: Exact Match (Stop-on-Ambiguity)
+    Tier 2: Git OSR (One-Sided-Merge / line alignment)
+    Tier 3: Diff-Match-Patch (Fuzzy threshold 0.8)
+    Tier 4: Prefill continuation
+"""
+
+from typing import Tuple
+
+
+class EditCascade:
+    """Orchestrates multi-tier edit fallbacks."""
+
+    def __init__(self, allow_fallbacks: bool = True):
+        self.allow_fallbacks = allow_fallbacks
+
+    def apply(self, original: str, search: str, replace: str) -> Tuple[str, str]:
+        """Apply edit using cascade. Returns (new_content, tier_used)."""
+        raise NotImplementedError

pari/edit/diff.py

@@ -0,0 +1,8 @@
+"""PARI Layer 5: Unified Diff Generation.
+
+Formats edits into standard unified diffs for terminal preview and inspection.
+"""
+
+def generate_unified_diff(original: str, modified: str, filename: str = "target") -> str:
+    """Generate a clean unified diff between original and modified text."""
+    raise NotImplementedError

pari/edit/dmp.py

@@ -0,0 +1,15 @@
+"""PARI Layer 5: Diff-Match-Patch (DMP) Fuzzy Search Fallback.
+
+Architectural Purpose:
+    Uses approximate string matching when exact match and line-based Git OSR fail.
+    Strict Invariant:
+    Threshold is capped at 0.8 minimum similarity. If best match similarity is < 0.8,
+    the edit is rejected to prevent silent code corruption.
+"""
+
+from typing import Optional
+
+
+def apply_dmp_fuzzy(original: str, search: str, replace: str, threshold: float = 0.8) -> Optional[str]:
+    """Find the best fuzzy match for search block and apply replacement if above threshold."""
+    raise NotImplementedError

pari/edit/exact.py

@@ -0,0 +1,37 @@
+"""PARI Layer 5: Exact String Search & Replace with Ambiguity Guard.
+
+Architectural Invariant:
+    Stop-on-Ambiguity:
+    - If search pattern occurs 0 times: Raise PatternNotFoundError.
+    - If search pattern occurs > 1 times: Raise AmbiguousMatchError.
+    - An edit is ONLY applied if the search pattern matches EXACTLY once.
+"""
+
+from typing import Tuple
+
+
+class PatternNotFoundError(Exception):
+    """Raised when the search string does not exist in target content."""
+    pass
+
+
+class AmbiguousMatchError(Exception):
+    """Raised when the search string occurs multiple times in target content."""
+    def __init__(self, count: int, search_str: str, filename: str = "<unknown>"):
+        super().__init__(
+            f"Ambiguous search target in '{filename}': found {count} identical matches. "
+            "Please provide additional surrounding context to identify a unique block."
+        )
+        self.count = count
+        self.search_str = search_str
+        self.filename = filename
+
+
+def apply_exact_edit(original: str, search: str, replace: str, filename: str = "<unknown>") -> str:
+    """Applies search/replace to text, strictly requiring a single unique match."""
+    raise NotImplementedError
+
+
+def preview_edit(original: str, search: str, replace: str, filename: str = "<unknown>") -> Tuple[str, str]:
+    """Applies exact edit and returns both modified content and unified diff."""
+    raise NotImplementedError

pari/edit/git_osr.py

@@ -0,0 +1,14 @@
+"""PARI Layer 5: Git One-Sided Merge (OSR) Fallback.
+
+Architectural Purpose:
+    Harvested from Aider's git cherry-pick / 3-way merge strategy.
+    When an exact match fails due to minor surrounding line drift, Git OSR treats
+    the search block as a base revision and attempts a 3-way context alignment.
+"""
+
+from typing import Optional
+
+
+def apply_git_osr(original: str, search: str, replace: str) -> Optional[str]:
+    """Attempt 3-way context alignment using line-based diff matching."""
+    raise NotImplementedError