inscript 0.5.0__tar.gz → 0.7.0__tar.gz

{inscript-0.5.0 → inscript-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: inscript
-Version: 0.5.0
+Version: 0.7.0
 Summary: Universal agent activity ledger. Records what AI agents do.
 Author: Andrew Park
 License-Expression: MIT

{inscript-0.5.0 → inscript-0.7.0}/inscript.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: inscript
-Version: 0.5.0
+Version: 0.7.0
 Summary: Universal agent activity ledger. Records what AI agents do.
 Author: Andrew Park
 License-Expression: MIT

{inscript-0.5.0 → inscript-0.7.0}/inscript.egg-info/SOURCES.txt

@@ -7,4 +7,5 @@ inscript.egg-info/dependency_links.txt
 inscript.egg-info/entry_points.txt
 inscript.egg-info/top_level.txt
 inscript_pkg/__init__.py
-inscript_pkg/hook.py
+inscript_pkg/hook.py
+inscript_pkg/reflect.py

{inscript-0.5.0 → inscript-0.7.0}/inscript_pkg/__init__.py

@@ -17,7 +17,7 @@ import time
 from datetime import datetime, timezone
 from pathlib import Path
 
-__version__ = "0.5.0"
+__version__ = "0.7.0"
 
 INSCRIPT_DIR = Path.home() / ".inscript"
 ACTIVE_PROJECT_FILE = INSCRIPT_DIR / "active_project"

inscript-0.7.0/inscript_pkg/reflect.py

@@ -0,0 +1,377 @@
+"""inscript reflect — identify what your codebase is becoming.
+
+Reads inscript session history (diffs, prompts, touches) and optionally
+tamachi structural analysis, feeds them to Claude, and returns:
+1. What archetype the codebase is converging toward
+2. The trajectory from recent diffs
+3. Predicted pain points based on archetype + trajectory
+4. What the codebase could become
+
+Based on research from IntentDiff v4:
+- Structure carries intent (architecture IS the domain)
+- Invariants accumulate and converge toward known archetypes
+- Bugfixes reveal hidden invariants
+- Early commits predict the end state
+
+Usage:
+    inscript reflect              # reflect on current project
+    inscript reflect --sessions 5 # use last 5 sessions
+    inscript reflect --deep       # include tamachi structural analysis
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+from . import (
+    INSCRIPT_DIR,
+    SESSIONS_DIR,
+    active_project,
+    active_session,
+    list_sessions,
+    session_dir,
+)
+
+
+# The 10 function archetypes (from IntentDiff v4 research)
+ARCHETYPES = {
+    "coordinator": "Orchestrates other calls, manages control flow, dispatches work",
+    "handler": "Handles events, requests, callbacks — reacts to external input",
+    "factory": "Creates instances, builds objects, spawns processes",
+    "accessor": "Returns state, reads fields, property getters",
+    "transformer": "Pure function, transforms input to output",
+    "validator": "Returns bool, checks conditions, enforces constraints",
+    "state_mutator": "Modifies self state, writes fields",
+    "serializer": "Format conversion (JSON, dict, etc.)",
+    "initializer": "__init__ and setup methods",
+    "test": "Test functions",
+}
+
+# Known archetype convergence patterns (from invariant_convergence.md)
+ARCHETYPE_PAIN_POINTS = {
+    "coordinator": [
+        "No graceful degradation — when one subsystem fails, the coordinator has no fallback",
+        "State management — coordinating multiple actors creates implicit shared state",
+        "The coordinator becomes a god object — too many responsibilities in one place",
+        "Missing health checks — no way to know if delegated work is actually progressing",
+        "Backpressure — no mechanism to slow down when workers are overloaded",
+    ],
+    "handler": [
+        "Handler explosion — too many handlers with overlapping concerns",
+        "Missing middleware — cross-cutting logic (auth, logging) duplicated across handlers",
+        "No error propagation strategy — handlers swallow errors silently",
+        "Missing validation at boundaries — handlers trust input too much",
+    ],
+    "factory": [
+        "Factory sprawl — too many factory methods creating slight variations",
+        "Missing cleanup — factories create but nothing tracks lifecycle or disposal",
+        "Configuration explosion — factories need more and more parameters",
+    ],
+    "state_mutator": [
+        "Mutation without notification — state changes don't trigger dependent updates",
+        "Missing invariant enforcement — state can reach invalid combinations",
+        "Concurrency hazards — multiple writers with no synchronization",
+        "No undo/rollback capability",
+    ],
+    "event_driven": [
+        "Event ordering — no guarantee events arrive in the right order",
+        "Missing dead letter queue — failed events are lost",
+        "Event schema evolution — changing event shapes breaks consumers",
+        "Debugging is hard — tracing causality through async event chains",
+    ],
+    "pipeline": [
+        "Pipeline stage coupling — stages know too much about each other",
+        "No partial failure handling — one stage fails, entire pipeline stalls",
+        "Observability gaps — hard to know where data is in the pipeline",
+        "Backpressure propagation — slow stages cause memory buildup",
+    ],
+}
+
+
+def _gather_session_data(project_path: str | None, max_sessions: int = 10) -> dict:
+    """Gather recent session data for a project."""
+    all_sessions = list_sessions()
+
+    # Filter to project if specified
+    if project_path:
+        all_sessions = [s for s in all_sessions if s.get("project") == project_path]
+
+    # Take most recent N
+    sessions = all_sessions[:max_sessions]
+
+    result = {
+        "session_count": len(sessions),
+        "prompts": [],
+        "diffs": [],
+        "files_touched": {},
+        "total_edits": 0,
+        "total_tokens": 0,
+    }
+
+    for s in sessions:
+        sid = s.get("session_id", "")
+        sdir = session_dir(sid)
+
+        # Load prompts
+        prompts_file = sdir / "prompts.jsonl"
+        if prompts_file.exists():
+            for line in prompts_file.open():
+                try:
+                    p = json.loads(line)
+                    p["session"] = sid[:8]
+                    result["prompts"].append(p)
+                except json.JSONDecodeError:
+                    pass
+
+        # Load diffs (just file + type, not full content for context window)
+        diffs_file = sdir / "diffs.jsonl"
+        if diffs_file.exists():
+            for line in diffs_file.open():
+                try:
+                    d = json.loads(line)
+                    result["diffs"].append({
+                        "file": d.get("file", ""),
+                        "tool": d.get("tool", ""),
+                        "session": sid[:8],
+                        "has_old_new": "old_string" in d,
+                        "is_new_file": d.get("is_new", False),
+                    })
+                except json.JSONDecodeError:
+                    pass
+
+        # Load touches for file frequency
+        touches_file = sdir / "touches.jsonl"
+        if touches_file.exists():
+            for line in touches_file.open():
+                try:
+                    t = json.loads(line)
+                    f = t.get("file", "")
+                    action = t.get("action", "")
+                    if f:
+                        if f not in result["files_touched"]:
+                            result["files_touched"][f] = {"reads": 0, "edits": 0}
+                        if action == "read":
+                            result["files_touched"][f]["reads"] += 1
+                        elif action in ("edit", "write"):
+                            result["files_touched"][f]["edits"] += 1
+                            result["total_edits"] += 1
+                except json.JSONDecodeError:
+                    pass
+
+        # Token usage from summary
+        summary_file = sdir / "summary.json"
+        if summary_file.exists():
+            try:
+                summary = json.loads(summary_file.read_text())
+                tokens = summary.get("tokens", {})
+                result["total_tokens"] += tokens.get("total_tokens", 0)
+            except (json.JSONDecodeError, OSError):
+                pass
+
+    return result
+
+
+def _load_tamachi_analysis(project_path: str) -> dict | None:
+    """Try to load tamachi structural analysis for the project."""
+    project = Path(project_path)
+
+    # Check .tamachi/ directory
+    for candidate in [
+        project / ".tamachi" / "tamachi.json",
+        project / ".tamachi",
+    ]:
+        if candidate.is_file():
+            try:
+                data = json.loads(candidate.read_text())
+                tami = data.get("tami", data)
+                return {
+                    "classes": len(tami.get("classes", [])),
+                    "mutations": len(tami.get("mutation_sites", [])),
+                    "reads": len(tami.get("method_read_sites", [])),
+                    "state_machines": [
+                        {"class": sm.get("class_name"), "field": sm.get("field_name"),
+                         "states": sm.get("states", [])}
+                        for sm in tami.get("state_machines", [])
+                    ],
+                    "boolean_lifecycles": len(tami.get("boolean_lifecycle_invariants", [])),
+                    "writer_set_groups": len(tami.get("writer_set_groups", [])),
+                    "behavioral_clusters": len(tami.get("behavioral_clusters", [])),
+                }
+            except (json.JSONDecodeError, OSError):
+                pass
+        elif candidate.is_dir():
+            for f in candidate.glob("*_analysis.json"):
+                try:
+                    data = json.loads(f.read_text())
+                    tami = data.get("tami", data)
+                    return {
+                        "classes": len(tami.get("classes", [])),
+                        "mutations": len(tami.get("mutation_sites", [])),
+                        "reads": len(tami.get("method_read_sites", [])),
+                        "state_machines": [
+                            {"class": sm.get("class_name"), "field": sm.get("field_name"),
+                             "states": sm.get("states", [])}
+                            for sm in tami.get("state_machines", [])
+                        ],
+                        "boolean_lifecycles": len(tami.get("boolean_lifecycle_invariants", [])),
+                        "writer_set_groups": len(tami.get("writer_set_groups", [])),
+                        "behavioral_clusters": len(tami.get("behavioral_clusters", [])),
+                    }
+                except (json.JSONDecodeError, OSError):
+                    pass
+
+    return None
+
+
+def _build_reflect_prompt(session_data: dict, tamachi_data: dict | None, project_name: str) -> str:
+    """Build the LLM prompt for reflection."""
+
+    # Top edited files
+    top_files = sorted(
+        session_data["files_touched"].items(),
+        key=lambda x: x[1]["edits"],
+        reverse=True,
+    )[:15]
+
+    # Recent prompts (last 20)
+    recent_prompts = session_data["prompts"][-20:]
+
+    # Diff summary
+    new_files = [d for d in session_data["diffs"] if d.get("is_new_file")]
+    edited_files = [d for d in session_data["diffs"] if d.get("has_old_new")]
+
+    prompt = f"""You are analyzing a codebase's development trajectory to identify what it's becoming.
+
+## Project: {project_name}
+
+## Recent Activity ({session_data['session_count']} sessions, {session_data['total_edits']} edits)
+
+### Most Edited Files
+"""
+    for f, counts in top_files:
+        prompt += f"- `{f}` — {counts['edits']} edits, {counts['reads']} reads\n"
+
+    prompt += f"\n### New Files Created ({len(new_files)})\n"
+    for d in new_files[:10]:
+        prompt += f"- `{d['file']}`\n"
+
+    prompt += f"\n### Recent Prompts (what the developer asked for)\n"
+    for p in recent_prompts:
+        tag = f" [{p['tag']}]" if p.get("tag") else ""
+        prompt += f"- \"{p.get('prompt', '')}\"{tag}\n"
+
+    if tamachi_data:
+        prompt += f"""
+### Structural Analysis (from tamachi)
+- {tamachi_data['classes']} classes, {tamachi_data['mutations']} mutation sites, {tamachi_data['reads']} read sites
+- {len(tamachi_data['state_machines'])} state machines: {', '.join(f"{sm['class']}.{sm['field']}" for sm in tamachi_data['state_machines'][:5])}
+- {tamachi_data['boolean_lifecycles']} boolean lifecycle invariants
+- {tamachi_data['writer_set_groups']} writer set groups
+- {tamachi_data['behavioral_clusters']} behavioral clusters
+"""
+
+    prompt += f"""
+## Known Archetypes
+These are the known system archetypes that codebases converge toward:
+- **Coordinator/Supervisor**: Orchestrates workers, manages lifecycle, fault tolerance (Erlang OTP pattern)
+- **Event-Driven Pipeline**: Events flow through handlers, async processing, pub/sub
+- **Request-Response Server**: Handlers process requests, middleware chains, routing
+- **Data Pipeline**: ETL, transformation stages, batch processing
+- **State Machine Engine**: Manages entities through lifecycle states
+- **Analysis Engine**: Reads data, computes insights, produces reports
+- **CLI/Tool**: Command dispatch, argument parsing, output formatting
+
+## Your Task
+
+Based on the development activity, structural analysis, and file patterns:
+
+1. **What it is**: Identify the primary archetype this codebase is converging toward. Name it precisely. Explain what structural patterns reveal this.
+
+2. **Trajectory**: What direction is the project moving based on recent prompts and edits? What's being built right now vs what was built before?
+
+3. **Predicted pain points**: Based on the archetype, what infrastructure problems will this project hit next? Be specific — name the files or patterns that will break. Reference the archetype's known failure modes.
+
+4. **What it could become**: Project the trajectory forward. If the current development direction continues, what will this system look like in 1 month? What architectural decisions are being implicitly made right now?
+
+5. **Hidden invariants**: What invariants exist in this codebase that aren't explicitly enforced? What "rules" does the code follow that a new contributor wouldn't know?
+
+Respond in this format:
+
+## Archetype
+[Name and explanation]
+
+## Trajectory
+[Direction from recent activity]
+
+## Predicted Pain Points
+1. [Specific prediction with file/pattern reference]
+2. [...]
+3. [...]
+
+## What It Could Become
+[1-month projection]
+
+## Hidden Invariants
+[Rules the code follows implicitly]
+"""
+
+    return prompt
+
+
+def reflect(max_sessions: int = 10, deep: bool = False) -> str:
+    """Run the reflect analysis. Returns the LLM's analysis as a string."""
+    import anthropic
+
+    project = active_project()
+    project_path = str(project) if project else None
+    project_name = project.name if project else "unknown"
+
+    # Gather data
+    session_data = _gather_session_data(project_path, max_sessions)
+
+    if session_data["session_count"] == 0:
+        return "No session data found. Use inscript for a few sessions first."
+
+    # Load tamachi if --deep or if it exists
+    tamachi_data = None
+    if project_path:
+        tamachi_data = _load_tamachi_analysis(project_path)
+
+    # Build prompt
+    prompt = _build_reflect_prompt(session_data, tamachi_data, project_name)
+
+    # Call Claude
+    api_key = os.environ.get("ANTHROPIC_API_KEY")
+    if not api_key:
+        return "ANTHROPIC_API_KEY not set. inscript reflect needs Claude API access."
+
+    client = anthropic.Anthropic(api_key=api_key)
+
+    print(f"Reflecting on {project_name} ({session_data['session_count']} sessions, {session_data['total_edits']} edits)...\n", file=sys.stderr)
+
+    message = client.messages.create(
+        model="claude-sonnet-4-20250514",
+        max_tokens=4096,
+        messages=[{"role": "user", "content": prompt}],
+    )
+
+    return message.content[0].text
+
+
+def main():
+    """CLI entry point for inscript reflect."""
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Reflect on your codebase's trajectory")
+    parser.add_argument("--sessions", type=int, default=10, help="Number of recent sessions to analyze")
+    parser.add_argument("--deep", action="store_true", help="Include tamachi structural analysis")
+    args = parser.parse_args()
+
+    result = reflect(max_sessions=args.sessions, deep=args.deep)
+    print(result)
+
+
+if __name__ == "__main__":
+    main()

{inscript-0.5.0 → inscript-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "inscript"
-version = "0.5.0"
+version = "0.7.0"
 description = "Universal agent activity ledger. Records what AI agents do."
 readme = "README.md"
 license = "MIT"