Skip to content

Commit be01111

Browse files
acailicclaude
andcommitted
Finalize ADR resolutions, add CLI entry point, and restore failure_memory tests (#127)
- Update 6 ADRs with accepted/superseded status and resolutions - Add peaky-peek CLI script entry point to pyproject.toml - Fix lint errors in cli.py (unused parser variables) - Restore test_feature_2_failure_memory.py with 17 passing tests Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent b093496 commit be01111

9 files changed

Lines changed: 520 additions & 6 deletions

agent_debugger_sdk/cli.py

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
#!/usr/bin/env python3
2+
"""Peaky Peek CLI - zero-friction onboarding and demo commands."""
3+
4+
from __future__ import annotations
5+
6+
import argparse
7+
import os
8+
import subprocess
9+
import sys
10+
from pathlib import Path
11+
12+
13+
def run_seed() -> int:
14+
"""Run the demo seed script."""
15+
script_path = Path(__file__).parent.parent / "scripts" / "seed_demo_sessions.py"
16+
if not script_path.exists():
17+
print(f"Error: seed script not found at {script_path}", file=sys.stderr)
18+
return 1
19+
20+
print("Seeding demo sessions...")
21+
result = subprocess.run([sys.executable, str(script_path)])
22+
return result.returncode
23+
24+
25+
def run_serve() -> int:
26+
"""Start the development server."""
27+
print("Starting server on http://localhost:8000")
28+
print("Press Ctrl+C to stop")
29+
try:
30+
subprocess.run(
31+
[sys.executable, "-m", "uvicorn", "api.main:app", "--reload", "--port", "8000"],
32+
check=True,
33+
)
34+
except KeyboardInterrupt:
35+
print("\nServer stopped")
36+
return 0
37+
except subprocess.CalledProcessError as e:
38+
print(f"Error starting server: {e}", file=sys.stderr)
39+
return 1
40+
except FileNotFoundError:
41+
print("Error: uvicorn not found. Install with: pip install uvicorn", file=sys.stderr)
42+
return 1
43+
44+
45+
def run_demo() -> int:
46+
"""Seed demo data and start server + frontend."""
47+
# Step 1: Seed the data
48+
seed_result = run_seed()
49+
if seed_result != 0:
50+
return seed_result
51+
52+
# Step 2: Start server in background
53+
print("\nStarting server in background...")
54+
try:
55+
server_process = subprocess.Popen(
56+
[sys.executable, "-m", "uvicorn", "api.main:app", "--reload", "--port", "8000"],
57+
stdout=subprocess.DEVNULL,
58+
stderr=subprocess.DEVNULL,
59+
)
60+
except (FileNotFoundError, OSError) as e:
61+
print(f"Error starting server: {e}", file=sys.stderr)
62+
return 1
63+
64+
# Step 3: Start frontend in background
65+
print("Starting frontend in background...")
66+
frontend_dir = Path(__file__).parent.parent / "frontend"
67+
try:
68+
frontend_process = subprocess.Popen(
69+
["npm", "run", "dev"],
70+
cwd=str(frontend_dir),
71+
env={**os.environ, "API_PORT": "8000"},
72+
stdout=subprocess.DEVNULL,
73+
stderr=subprocess.DEVNULL,
74+
)
75+
except (FileNotFoundError, OSError) as e:
76+
print(f"Error starting frontend: {e}", file=sys.stderr)
77+
server_process.terminate()
78+
return 1
79+
80+
# Step 4: Print instructions
81+
print("\n" + "=" * 60)
82+
print(" Peaky Peek demo is running!")
83+
print("=" * 60)
84+
print("\n Server: http://localhost:8000")
85+
print(" Frontend: http://localhost:5173")
86+
print("\n Press Ctrl+C to stop both processes")
87+
print("\n Open http://localhost:5173 to explore demo sessions")
88+
print("=" * 60 + "\n")
89+
90+
# Wait for interrupt
91+
try:
92+
server_process.wait()
93+
frontend_process.wait()
94+
except KeyboardInterrupt:
95+
print("\nStopping server and frontend...")
96+
server_process.terminate()
97+
frontend_process.terminate()
98+
server_process.wait()
99+
frontend_process.wait()
100+
print("Done")
101+
102+
return 0
103+
104+
105+
def main() -> int:
106+
"""CLI entry point."""
107+
parser = argparse.ArgumentParser(
108+
prog="peaky-peek",
109+
description="Peaky Peek - AI agent debugger CLI",
110+
)
111+
subparsers = parser.add_subparsers(dest="command", help="Available commands")
112+
113+
subparsers.add_parser("demo", help="Seed demo data and launch server + frontend")
114+
subparsers.add_parser("seed", help="Seed benchmark demo sessions")
115+
subparsers.add_parser("serve", help="Start the development server")
116+
117+
args = parser.parse_args()
118+
119+
if args.command == "demo":
120+
return run_demo()
121+
elif args.command == "seed":
122+
return run_seed()
123+
elif args.command == "serve":
124+
return run_serve()
125+
else:
126+
parser.print_help()
127+
return 0
128+
129+
130+
if __name__ == "__main__":
131+
sys.exit(main())

docs/decisions/ADR-001-product-positioning.md

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# ADR-001: Product Positioning
22

3-
**Status:** Under Review
3+
**Status:** Accepted
44
**Date:** 2026-03-23
55

66
## Open Challenge
@@ -9,6 +9,10 @@
99

1010
**Action:** Test 2-3 positioning variants with early beta users before finalizing.
1111

12+
## Resolution
13+
14+
Position as "local-first AI agent debugger" with two hero features: (1) "See WHY your agent did that" — decision provenance that answers the #1 pain point of understanding agent behavior, and (2) "Replay from any checkpoint" — time-travel debugging that lets developers explore alternate paths. This positioning is immediately demonstrable and easy to explain in under 10 seconds.
15+
1216
---
1317

1418
## Original Decision (Deferred)

docs/decisions/ADR-003-pricing-strategy.md

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# ADR-003: Pricing Strategy
22

3-
**Status:** Under Review
3+
**Status:** Superseded
44
**Date:** 2026-03-23
55

66
## Open Challenge
@@ -12,6 +12,10 @@ $29/mo may be too high for indie developers building agents. Consider:
1212

1313
**Action:** Launch with generous free tier on cloud. Collect usage data before finalizing paid pricing.
1414

15+
## Resolution
16+
17+
Local-first product — pricing strategy deferred until/unless a hosted offering is considered. See ADR-012 for updated user targets. The cloud pricing tiers proposed here are not applicable to the current local-first direction.
18+
1519
---
1620

1721
## Original Proposal (Deferred)

docs/decisions/ADR-007-replay-fidelity.md

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# ADR-007: Replay Fidelity Strategy
22

3-
**Status:** Under Review
3+
**Status:** Accepted
44
**Date:** 2026-03-23
55

66
## Open Challenge
@@ -9,6 +9,10 @@ Positioning replay as "not deterministic" may frustrate users who expect time-tr
99

1010
**Action:** Test with users. Frame as "replay + what-if" rather than "structural replay." The feature should feel powerful, not limited. If users want cached-response deterministic replay for specific sessions, consider it as an opt-in mode (record and replay exact LLM responses).
1111

12+
## Resolution
13+
14+
Frame replay as "replay + what-if" — a powerful tool for exploring alternate paths rather than a limited structural replay. The three existing modes (event, focused, re-execution) remain the foundation. Cached replay for deterministic behavior can be added as an opt-in feature for users who need exact response reproduction, likely with higher storage costs.
15+
1216
---
1317

1418
## Original Decision (Deferred)

docs/decisions/ADR-009-frontend-strategy.md

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# ADR-009: Frontend Strategy
22

3-
**Status:** Under Review
3+
**Status:** Accepted
44
**Date:** 2026-03-23
55

66
## Open Challenge
@@ -9,6 +9,10 @@ Skipping VS Code extension may leave a major adoption channel on the table. VS C
99

1010
**Action:** Evaluate a minimal VS Code extension for Phase 2 or 3 — not a full debugger, but a sidebar that shows active sessions and links to the web UI. Low effort, high visibility.
1111

12+
## Resolution
13+
14+
Approved: React + Vite + TypeScript stack, three-panel layout, dark theme, Tailwind + shadcn/ui components. VS Code extension deferred to future consideration — not part of Phase 1. The standalone web UI is the priority for initial launch.
15+
1216
---
1317

1418
## Original Decision (Partially Deferred)

docs/decisions/ADR-010-competitive-differentiation.md

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# ADR-010: Competitive Differentiation
22

3-
**Status:** Under Review
3+
**Status:** Accepted
44
**Date:** 2026-03-23
55

66
## Open Challenge
@@ -13,6 +13,10 @@ Six differentiators is too many. Dilutes the message. Should pick 1-2 hero featu
1313

1414
Everything else (safety, multi-agent, anomaly detection) is a supporting feature, not a headline.
1515

16+
## Resolution
17+
18+
Two hero features: (1) "See WHY your agent did that" — decision provenance as the #1 differentiator that answers the primary pain point, and (2) "Replay from any checkpoint" — time-travel debugging as the #2 visceral, demo-friendly capability. All other features (safety, multi-agent, anomaly detection) support these core messages.
19+
1620
---
1721

1822
## Original Proposal (Deferred)

docs/decisions/ADR-012-assumptions-constraints.md

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# ADR-012: Key Assumptions & Constraints
22

3-
**Status:** Under Review
3+
**Status:** Accepted
44
**Date:** 2026-03-23
55

66
## Open Challenge
@@ -13,6 +13,10 @@
1313
- Month 6: 50+ active users, 20-50 paying
1414
- Revenue target adjusted: $1k-5k MRR at month 6, $5k-20k MRR at month 12
1515

16+
## Resolution
17+
18+
Revised milestones adopted: 20-50 paying users at month 6 with $1k-5k MRR. More realistic than original 100-200 paying users. All other approved assumptions (volume, technical, constraints) remain valid. Infrastructure and effort planning should target the revised scale first, then grow.
19+
1620
---
1721

1822
## Approved Assumptions (Still Valid)
@@ -32,3 +36,9 @@
3236
- Bootstrapped / early revenue
3337
- 10-week build to first beta users
3438
- Must work with Python 3.10+, LangChain 0.2+
39+
40+
### User & Revenue Targets (Revised)
41+
- Month 1-2: 10 beta users (free)
42+
- Month 3: 20-30 active users, 5-10 paying
43+
- Month 6: 50+ active users, 20-50 paying
44+
- Revenue target: $1k-5k MRR at month 6, $5k-20k MRR at month 12

pyproject.toml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,9 @@ dev = [
4949
"ruff>=0.1",
5050
]
5151

52+
[project.scripts]
53+
peaky-peek = "agent_debugger_sdk.cli:main"
54+
5255
[project.urls]
5356
Homepage = "https://github.com/acailic/agent_debugger"
5457
Repository = "https://github.com/acailic/agent_debugger"

0 commit comments

Comments
 (0)