ghosttrace 0.1.0__tar.gz

ghosttrace-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ahmed Allam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ghosttrace-0.1.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: ghosttrace
+Version: 0.1.0
+Summary: Record AI agent decisions, including phantom branches.
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: typer[all]>=0.9.0
+Requires-Dist: rich>=13.0.0
+Dynamic: license-file

ghosttrace-0.1.0/README.md

@@ -0,0 +1,110 @@
+<div align="center">
+
+# 👻 GhostTrace
+
+### See what your AI agent *almost* did.
+
+Record AI agent decisions — including **Phantom Branches**:
+the actions your agent considered but rejected.
+
+<p align="center">
+  <a href="https://github.com/AhmedAllam0/ghosttrace/stargazers">
+    <img src="https://img.shields.io/github/stars/AhmedAllam0/ghosttrace?style=for-the-badge&logo=github&color=yellow" alt="Stars" />
+  </a>
+  <a href="https://pypi.org/project/ghosttrace/">
+    <img src="https://img.shields.io/pypi/v/ghosttrace?style=for-the-badge&logo=pypi&color=blue" alt="PyPI Version" />
+  </a>
+  <a href="https://github.com/AhmedAllam0/ghosttrace">
+    <img src="https://img.shields.io/badge/python-3.10+-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python" />
+  </a>
+  <a href="https://github.com/AhmedAllam0/ghosttrace/blob/main/LICENSE">
+    <img src="https://img.shields.io/github/license/AhmedAllam0/ghosttrace?style=for-the-badge&color=green" alt="License" />
+  </a>
+</p>
+
+</div>
+
+---
+
+## The Problem
+
+Your AI agent made a bad call. But you only see *what it did* — never *what it almost did*. The reasoning behind rejected alternatives is lost forever.
+
+**GhostTrace fixes that.**
+
+---
+
+## What is GhostTrace?
+
+| What you get today | What GhostTrace adds |
+|---|---|
+| ✅ Agent took action X | ✅ Agent took action X |
+| ❌ Nothing else | 👻 Agent **rejected** action Y because... |
+| | 👻 Agent **rejected** action Z because... |
+| | 📄 Full trace saved to `.ghost.json` |
+
+Think of it as **`git log` for your agent's brain** — including the commits it decided *not* to make.
+
+---
+
+## Installation
+
+```bash
+pip install ghosttrace
+```
+
+---
+
+## Quick Start
+
+```bash
+# Record an agent run
+ghosttrace record
+
+# Replay chosen actions only
+ghosttrace replay gt_abc123.ghost.json
+
+# Replay WITH phantom branches 👻
+ghosttrace replay gt_abc123.ghost.json --show-phantoms
+```
+
+---
+
+## What Are Phantom Branches?
+
+At every decision point, an AI agent evaluates multiple possible actions. It picks one. The rest disappear — unless you're running GhostTrace.
+
+Each phantom branch records:
+- **What** the agent considered doing
+- **Why** it seemed like a good idea  
+- **Why it was rejected** ← *this is the most valuable part*
+
+---
+
+## Roadmap
+
+- [x] `.ghost.json` schema v0.1
+- [x] `ghosttrace record`
+- [x] `ghosttrace replay` with rich terminal UI
+- [x] `--show-phantoms` flag
+- [ ] LangChain / CrewAI / OpenAI Agents SDK hooks
+- [ ] `ghosttrace diff` — compare two traces
+- [ ] Assertion engine — `--must-reject "delete_database"`
+- [ ] Web UI for trace exploration
+- [ ] VS Code extension
+
+---
+
+## License
+
+MIT
+
+---
+
+<div align="center">
+
+*See what your AI agent almost did.* 👻
+
+⭐ Star this repo if GhostTrace helped you!
+
+</div>

ghosttrace-0.1.0/ghosttrace/__init__.py

@@ -0,0 +1,2 @@
+"""GhostTrace — Record the roads your AI agent didn't take."""
+__version__ = "0.1.0"

ghosttrace-0.1.0/ghosttrace/cli.py

@@ -0,0 +1,65 @@
+"""GhostTrace CLI — Record and replay AI agent decisions."""
+
+import typer
+from rich.console import Console
+
+from ghosttrace.mock_agent import run_mock_agent
+from ghosttrace.recorder import save_trace
+from ghosttrace.replayer import replay
+
+app = typer.Typer(
+    name="ghosttrace",
+    help="👻 GhostTrace — Record AI agent decisions, including phantom branches.",
+    add_completion=False,
+)
+console = Console()
+
+
+@app.command()
+def record(
+    goal: str = typer.Option(
+        "Refactor the auth module to use OAuth2",
+        "--goal", "-g",
+        help="The goal/task for the mock agent.",
+    ),
+    output: str = typer.Option(
+        None,
+        "--output", "-o",
+        help="Output file path. Defaults to <session_id>.ghost.json",
+    ),
+) -> None:
+    """Run a mock agent and record its decisions to a .ghost.json file."""
+    console.print("\n👻 [bold cyan]GhostTrace[/bold cyan] — Recording agent run...\n")
+
+    trace = run_mock_agent(goal=goal)
+    path = save_trace(trace, output_path=output)
+
+    steps = trace["summary"]["total_steps"]
+    phantoms = trace["summary"]["total_phantoms"]
+
+    console.print(f"  ✅ Recorded [bold]{steps}[/bold] decisions with "
+                  f"[bold red]{phantoms}[/bold red] phantom branches.")
+    console.print(f"  📄 Saved to [bold green]{path}[/bold green]\n")
+    console.print(f"  [dim]Replay with:[/dim]  ghosttrace replay {path}")
+    console.print(f"  [dim]See ghosts:[/dim]   ghosttrace replay {path} --show-phantoms\n")
+
+
+@app.command()
+def replay_cmd(
+    file: str = typer.Argument(..., help="Path to a .ghost.json file."),
+    show_phantoms: bool = typer.Option(
+        False,
+        "--show-phantoms",
+        help="Show phantom branches (rejected alternatives).",
+    ),
+) -> None:
+    """Replay a recorded agent trace from a .ghost.json file."""
+    replay(file, show_phantoms=show_phantoms)
+
+
+# Typer registers commands by function name, so we alias for a clean CLI
+app.command(name="replay")(replay_cmd)
+
+
+if __name__ == "__main__":
+    app()

ghosttrace-0.1.0/ghosttrace/mock_agent.py

@@ -0,0 +1,128 @@
+"""
+A dummy agent that simulates decision-making with phantom branches.
+Swap this out for a real agent later.
+"""
+
+import random
+import uuid
+from datetime import datetime, timezone
+
+
+MOCK_DECISIONS = [
+    {
+        "context": "Agent is deciding how to approach the auth refactor.",
+        "chosen": {
+            "action": "read_file",
+            "target": "src/auth.py",
+            "reasoning": "Need to understand current auth implementation first.",
+        },
+        "phantoms": [
+            {
+                "action": "search_codebase",
+                "target": "grep 'auth' --recursive",
+                "reasoning": "Scan the whole codebase for auth references.",
+                "rejection_reason": "Too broad; better to start with the known entry point.",
+            },
+            {
+                "action": "write_file",
+                "target": "src/auth_oauth2.py",
+                "reasoning": "Start writing the new OAuth2 module immediately.",
+                "rejection_reason": "Premature — haven't read existing code yet.",
+            },
+        ],
+    },
+    {
+        "context": "Agent has read auth.py. Deciding next step.",
+        "chosen": {
+            "action": "write_file",
+            "target": "src/auth_oauth2.py",
+            "reasoning": "Create new OAuth2 module based on understood structure.",
+        },
+        "phantoms": [
+            {
+                "action": "edit_file",
+                "target": "src/auth.py",
+                "reasoning": "Modify existing file in-place.",
+                "rejection_reason": "Risky — better to create new file and migrate.",
+            },
+        ],
+    },
+    {
+        "context": "New OAuth2 module written. Deciding how to handle migration.",
+        "chosen": {
+            "action": "edit_file",
+            "target": "src/routes.py",
+            "reasoning": "Update route imports to point to new auth module.",
+        },
+        "phantoms": [
+            {
+                "action": "delete_file",
+                "target": "src/auth.py",
+                "reasoning": "Remove old auth module immediately.",
+                "rejection_reason": "Too aggressive — need to update consumers first.",
+            },
+            {
+                "action": "run_command",
+                "target": "python -m pytest",
+                "reasoning": "Run tests before changing imports.",
+                "rejection_reason": "Tests will fail anyway since new module isn't wired up yet.",
+            },
+        ],
+    },
+    {
+        "context": "Routes updated. Final verification step.",
+        "chosen": {
+            "action": "run_command",
+            "target": "python -m pytest tests/",
+            "reasoning": "Verify everything works end-to-end after migration.",
+        },
+        "phantoms": [
+            {
+                "action": "run_command",
+                "target": "python -m pytest tests/test_auth.py",
+                "reasoning": "Run only auth tests for speed.",
+                "rejection_reason": "Migration could break non-auth routes too; full suite is safer.",
+            },
+        ],
+    },
+]
+
+
+def run_mock_agent(goal: str = "Refactor the auth module to use OAuth2") -> dict:
+    """Simulate an agent run and return a ghost trace dict."""
+    session_id = f"gt_{uuid.uuid4().hex[:8]}"
+    now = datetime.now(timezone.utc)
+
+    decisions = []
+    for i, mock in enumerate(MOCK_DECISIONS, start=1):
+        decisions.append(
+            {
+                "step": i,
+                "timestamp": (now).isoformat(),
+                "context": mock["context"],
+                "chosen": mock["chosen"],
+                "phantoms": mock["phantoms"],
+            }
+        )
+
+    total_phantoms = sum(len(d["phantoms"]) for d in decisions)
+
+    return {
+        "version": "0.1",
+        "session": {
+            "id": session_id,
+            "timestamp": now.isoformat(),
+            "agent": {
+                "name": "mock-agent",
+                "model": "gpt-4o-mock",
+                "version": "0.1.0",
+            },
+            "goal": goal,
+        },
+        "decisions": decisions,
+        "summary": {
+            "total_steps": len(decisions),
+            "total_phantoms": total_phantoms,
+            "outcome": "success",
+        },
+    }

ghosttrace-0.1.0/ghosttrace/recorder.py

@@ -0,0 +1,15 @@
+"""Handles writing .ghost.json files."""
+
+import json
+from pathlib import Path
+
+
+def save_trace(trace: dict, output_path: str | None = None) -> Path:
+    """Save a ghost trace dict to a .ghost.json file."""
+    if output_path is None:
+        session_id = trace["session"]["id"]
+        output_path = f"{session_id}.ghost.json"
+
+    path = Path(output_path)
+    path.write_text(json.dumps(trace, indent=2), encoding="utf-8")
+    return path

ghosttrace-0.1.0/ghosttrace/replayer.py

@@ -0,0 +1,97 @@
+"""Handles replaying .ghost.json files with rich output."""
+
+import json
+from pathlib import Path
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.text import Text
+from rich.table import Table
+
+console = Console()
+
+
+def load_trace(filepath: str) -> dict:
+    """Load and return a ghost trace from a .ghost.json file."""
+    path = Path(filepath)
+    if not path.exists():
+        console.print(f"[red]Error:[/red] File not found: {filepath}")
+        raise SystemExit(1)
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def replay(filepath: str, show_phantoms: bool = False) -> None:
+    """Replay a ghost trace to the terminal."""
+    trace = load_trace(filepath)
+    session = trace["session"]
+    decisions = trace["decisions"]
+    summary = trace["summary"]
+
+    # Header
+    console.print()
+    console.print(
+        Panel(
+            f"[bold cyan]GhostTrace Replay[/bold cyan] 👻\n\n"
+            f"  Session:  [yellow]{session['id']}[/yellow]\n"
+            f"  Agent:    {session['agent']['name']} ({session['agent']['model']})\n"
+            f"  Goal:     [italic]{session['goal']}[/italic]\n"
+            f"  Steps:    {summary['total_steps']}   |   "
+            f"  Phantoms: {summary['total_phantoms']}",
+            title="Session Info",
+            border_style="cyan",
+        )
+    )
+
+    # Decisions
+    for decision in decisions:
+        console.print()
+        step = decision["step"]
+        ctx = decision["context"]
+        chosen = decision["chosen"]
+
+        # Step header
+        console.rule(f"[bold]Step {step}[/bold]", style="blue")
+        console.print(f"  [dim]{ctx}[/dim]\n")
+
+        # Chosen action
+        console.print(
+            Panel(
+                f"[green bold]✔ {chosen['action']}[/green bold]  →  "
+                f"[white]{chosen['target']}[/white]\n"
+                f"  [dim]{chosen['reasoning']}[/dim]",
+                title="[green]Chosen Action[/green]",
+                border_style="green",
+            )
+        )
+
+        # Phantom branches
+        if show_phantoms and decision.get("phantoms"):
+            for j, phantom in enumerate(decision["phantoms"], start=1):
+                console.print(
+                    Panel(
+                        f"[red bold]✘ {phantom['action']}[/red bold]  →  "
+                        f"[white]{phantom['target']}[/white]\n"
+                        f"  [dim italic]Considered:[/dim italic] {phantom['reasoning']}\n"
+                        f"  [red]Rejected:[/red]   {phantom['rejection_reason']}",
+                        title=f"[red]Phantom {j}[/red] 👻",
+                        border_style="red",
+                        style="dim",
+                    )
+                )
+
+    # Footer
+    console.print()
+    console.rule(style="cyan")
+    outcome_color = "green" if summary["outcome"] == "success" else "red"
+    console.print(
+        f"  Outcome: [{outcome_color} bold]{summary['outcome'].upper()}"
+        f"[/{outcome_color} bold]   |   "
+        f"{summary['total_steps']} steps, "
+        f"{summary['total_phantoms']} phantom branches"
+    )
+    if not show_phantoms and summary["total_phantoms"] > 0:
+        console.print(
+            f"\n  [dim]💡 Tip: Re-run with [bold]--show-phantoms[/bold] to see "
+            f"{summary['total_phantoms']} rejected alternatives.[/dim]"
+        )
+    console.print()

ghosttrace-0.1.0/ghosttrace.egg-info/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: ghosttrace
+Version: 0.1.0
+Summary: Record AI agent decisions, including phantom branches.
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: typer[all]>=0.9.0
+Requires-Dist: rich>=13.0.0
+Dynamic: license-file

ghosttrace-0.1.0/ghosttrace.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+ghosttrace/__init__.py
+ghosttrace/cli.py
+ghosttrace/mock_agent.py
+ghosttrace/recorder.py
+ghosttrace/replayer.py
+ghosttrace.egg-info/PKG-INFO
+ghosttrace.egg-info/SOURCES.txt
+ghosttrace.egg-info/dependency_links.txt
+ghosttrace.egg-info/entry_points.txt
+ghosttrace.egg-info/requires.txt
+ghosttrace.egg-info/top_level.txt

ghosttrace-0.1.0/ghosttrace.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ghosttrace-0.1.0/ghosttrace.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ghosttrace = ghosttrace.cli:app

ghosttrace-0.1.0/ghosttrace.egg-info/requires.txt

@@ -0,0 +1,2 @@
+typer[all]>=0.9.0
+rich>=13.0.0

ghosttrace-0.1.0/ghosttrace.egg-info/top_level.txt

@@ -0,0 +1 @@
+ghosttrace

ghosttrace-0.1.0/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "ghosttrace"
+version = "0.1.0"
+description = "Record AI agent decisions, including phantom branches."
+requires-python = ">=3.10"
+dependencies = [
+    "typer[all]>=0.9.0",
+    "rich>=13.0.0",
+]
+
+[project.scripts]
+ghosttrace = "ghosttrace.cli:app"
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"

ghosttrace-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+