looplens 0.1.0__tar.gz

looplens-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: pytest (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install (server + dev deps)
+        run: pip install -e ".[dev]"
+      - name: Run tests
+        run: pytest -q
+
+  ui-build:
+    name: UI build check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+          cache-dependency-path: ui/package-lock.json
+      - name: Install UI deps
+        run: npm --prefix ui ci
+      - name: Build UI bundle
+        run: npm --prefix ui run build
+      - name: Assert bundle was produced
+        run: test -f looplens/server/_ui/index.html

looplens-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,53 @@
+name: Release
+
+# Publishes to PyPI when you push a version tag, e.g. `git tag v0.1.0 && git push --tags`.
+# The UI is built first and force-included into the wheel (see pyproject `artifacts`),
+# so the published package installs with zero Node.
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    name: Build wheel + sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+          cache-dependency-path: ui/package-lock.json
+      - name: Build UI bundle into looplens/server/_ui
+        run: |
+          npm --prefix ui ci
+          npm --prefix ui run build
+          test -f looplens/server/_ui/index.html
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Verify the wheel bundles the UI
+        run: |
+          python -m zipfile -l dist/*.whl | grep -q "looplens/server/_ui/index.html"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # trusted publishing (OIDC) — no API token stored
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

looplens-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.env
+
+# LoopLens local data
+*.db
+*.db-wal
+*.db-shm
+.looplens/
+looplens.env
+looplens-traces/
+
+# Node / UI
+node_modules/
+ui/dist/
+ui/.vite/
+# Built dashboard bundled into the wheel (regenerated by `npm --prefix ui run build`)
+looplens/server/_ui/
+
+# Editor / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db

looplens-0.1.0/CLAUDE.md

@@ -0,0 +1,65 @@
+# CLAUDE.md
+
+Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+---
+
+**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

looplens-0.1.0/LAUNCH.md

@@ -0,0 +1,170 @@
+# LoopLens — Launch Assets
+
+Copy-paste launch posts for each channel. Replace `REPO_URL` with the GitHub
+link and attach the demo GIF where noted.
+
+---
+
+## One-liner
+
+> LoopLens — Chrome DevTools for AI agent loops. See your agent run live and get
+> warned the moment it repeats itself, retries blindly, or stops making progress.
+
+## The hook (problem → product)
+
+Your agent "works." The terminal scrolls. It looks busy. Then it burns 5 LLM
+calls searching the same thing 5 times and gives up — and you only find out from
+the final error. LoopLens makes the loop visible *while it runs* and tells you,
+in plain language, that the agent is stuck and where.
+
+---
+
+## GitHub release notes (v0.1.0)
+
+**LoopLens v0.1.0 — local-first loop debugger for AI agents.**
+
+- 🪄 **Zero-friction install:** `pip install "looplens[server]"` — no Node, no
+  build step; the dashboard is bundled in the wheel.
+- 🧩 **Zero-dependency SDK:** pure-stdlib `trace()` / `event()` / `@observe`.
+  Drops into LangGraph, CrewAI, OpenAI Agents SDK, or a plain `while` loop
+  without pinning anything or touching your agent's deps.
+- 📺 **Live timeline** over SSE: LLM calls, tool calls, retries, handoffs, state.
+- 🚨 **Six transparent loop detectors:** repeated tool call, similar-input
+  repeat, no-progress loop, retry storm, long-running step, cost spike.
+- 🩺 **Health score** (0–100 → Healthy / Warning / Likely stuck / Failed).
+- 💾 **Local-first:** SQLite, no auth, no cloud, no API key. JSONL import/export.
+- 🛟 **Fail-silent:** if the dashboard is down, the SDK buffers to JSONL and
+  never crashes your agent.
+
+```bash
+pip install "looplens[server]"
+looplens dev
+looplens demo   # watch it trip a loop warning live
+```
+
+MIT. Feedback and framework-adapter requests welcome.
+
+---
+
+## Hacker News (Show HN)
+
+**Title:** Show HN: LoopLens – a local-first loop debugger for AI agents
+
+**Body:**
+
+I kept shipping agents that *looked* like they were working — the logs scrolled,
+tools fired — but they were quietly stuck calling the same tool over and over,
+burning tokens, and failing at the end. Generic tracing tools show me spans;
+they don't tell me the loop is unhealthy.
+
+LoopLens is a small local tool focused on exactly that. You add a tiny zero-dep
+SDK to the agent you already have, run a local dashboard, and watch the loop live.
+It raises rule-based warnings — repeated tool call, no-progress loop, retry
+storm, cost spike — with a plain-English "what happened / why it matters / where /
+how to fix."
+
+It's deliberately *not* another observability platform: no auth, no cloud, no
+eval datasets, no graph-first UI. Just timeline + warnings + metrics, local-first.
+
+The detectors are transparent rules (no black-box scoring), the SDK is pure
+stdlib so it won't fight your agent's dependencies, and the `[server]` install
+ships the prebuilt UI so there's no Node/npm step.
+
+```bash
+pip install "looplens[server]" && looplens dev && looplens demo
+```
+
+Repo: REPO_URL — would love feedback, especially on which framework adapter
+(LangGraph / CrewAI / OpenAI Agents SDK) to build first.
+
+---
+
+## X / Twitter (thread)
+
+1/ Your agent isn't "thinking." It's calling `search_docs("refund policy")` for
+the 5th time and about to give up. You'll find out from the final error.
+
+I built **LoopLens** to make that visible *while it runs.* 🧵
+
+2/ It's Chrome DevTools, but for agent loops. Add a tiny zero-dep SDK, open a
+local dashboard, watch every LLM call / tool call / retry stream in live.
+
+3/ The point isn't logs — it's *opinions*. LoopLens warns you:
+• repeated tool call
+• no-progress loop
+• retry storm
+• cost spike
+…each with what happened, why, where, and how to fix.
+
+4/ Local-first: SQLite, no auth, no cloud, no API key. The SDK is pure stdlib so
+it won't conflict with LangGraph / CrewAI / OpenAI Agents SDK / your custom loop.
+If the dashboard's down it buffers to JSONL and never crashes your agent.
+
+5/ Install is one line — the dashboard ships prebuilt, no Node:
+`pip install "looplens[server]" && looplens dev && looplens demo`
+[attach GIF]
+Repo + roadmap 👇 REPO_URL
+
+---
+
+## LinkedIn
+
+Agent development is becoming **loop engineering**. Agents don't answer once —
+they plan, call tools, retry, hand off, and loop until success or budget runs
+out. When that loop goes wrong, it's mostly invisible: the logs look busy while
+the agent repeats itself and burns tokens.
+
+I built **LoopLens** — a local-first, real-time debugger focused purely on loop
+health. Add a zero-dependency Python SDK to the agent you already have, open a
+local dashboard, and watch the run live. It raises transparent, rule-based
+warnings — repeated tool call, no-progress loop, retry storm, cost spike — each
+with a plain-English explanation and a suggested fix.
+
+It's intentionally narrow: not another observability platform — no auth, no
+cloud, no eval suite. Just the fastest way to see *why your agent got stuck.*
+
+```
+pip install "looplens[server]"
+looplens dev
+looplens demo
+```
+
+Open-source (MIT). Roadmap includes LangGraph / CrewAI / OpenAI Agents SDK
+adapters — feedback on ordering welcome. REPO_URL
+
+---
+
+## Reddit (r/LangChain, r/AI_Agents, r/LocalLLaMA)
+
+**Title:** I built a local-first "loop debugger" for AI agents — see why it got
+stuck, live
+
+Sharing a tool I built to scratch my own itch. My agents kept looking busy while
+secretly repeating the same tool call and failing at the end. LoopLens shows the
+loop live and warns you the moment it detects repeated calls, no-progress loops,
+retry storms, or cost spikes — in plain language, with a suggested fix.
+
+- zero-dependency SDK (pure stdlib — drops into LangGraph/CrewAI/OpenAI Agents
+  SDK/custom loops without dependency conflicts)
+- local-first: SQLite, no auth, no cloud, no API key
+- one-line install, dashboard bundled (no Node build step)
+- fail-silent: buffers to JSONL if the dashboard's down, never crashes your agent
+
+```bash
+pip install "looplens[server]" && looplens dev && looplens demo
+```
+
+It's an MVP and deliberately narrow (loop health, not full observability).
+Repo + roadmap: REPO_URL. What framework adapter should I build first?
+
+---
+
+## Demo script (for the GIF / video — ~30s)
+
+1. Split screen: terminal (left) running `looplens demo`, dashboard (right).
+2. Watch the timeline fill: `agent_started` → `llm_call` → `tool_call` repeating.
+3. By the 3rd `web_search`, a **warning card** appears: *"Same tool called
+   repeatedly with similar input — possible no-progress loop."*
+4. Health score ticks down from 100 → "Likely stuck."
+5. Click an event → drawer shows the raw JSON (identical inputs each call).
+6. End card: `pip install "looplens[server]"` + repo URL.

looplens-0.1.0/PKG-INFO

@@ -0,0 +1,250 @@
+Metadata-Version: 2.4
+Name: looplens
+Version: 0.1.0
+Summary: Local-first real-time debugger for AI agent loops — Chrome DevTools for agent loops.
+Project-URL: Homepage, https://github.com/ashutosh-rath02/looplens
+Project-URL: Repository, https://github.com/ashutosh-rath02/looplens
+Author: Ashutosh Rath
+License: MIT
+Keywords: agents,ai,debugging,llm,loops,observability
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.110; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pydantic>=2.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: typer>=0.9; extra == 'dev'
+Requires-Dist: uvicorn[standard]>=0.27; extra == 'dev'
+Requires-Dist: watchdog>=3.0; extra == 'dev'
+Provides-Extra: server
+Requires-Dist: fastapi>=0.110; extra == 'server'
+Requires-Dist: pydantic>=2.0; extra == 'server'
+Requires-Dist: typer>=0.9; extra == 'server'
+Requires-Dist: uvicorn[standard]>=0.27; extra == 'server'
+Requires-Dist: watchdog>=3.0; extra == 'server'
+Description-Content-Type: text/markdown
+
+# LoopLens
+
+[![CI](https://github.com/ashutosh-rath02/looplens/actions/workflows/ci.yml/badge.svg)](https://github.com/ashutosh-rath02/looplens/actions/workflows/ci.yml)
+
+**Chrome DevTools for AI agent loops.** A local-first, real-time debugger that
+shows your agent's execution live and warns when it repeats itself, burns
+tokens, retries blindly, or stops making progress.
+
+LoopLens gives you:
+
+- live timeline of agent execution
+- LLM-call and tool-call visibility
+- retry and handoff tracking
+- token and cost metrics
+- loop warnings (repeated tool, no-progress, retry storm, cost spike, …)
+- JSONL import/export
+- a local-first UI — no login, no cloud, no API key
+
+## See it in action
+
+A looping agent calls `web_search` over and over. As events stream in live, the
+metrics climb and LoopLens flags **Repeated tool call** and **No-progress loop**
+— the warning counts track the repeat count in real time, and the health score
+drops to *Warning*.
+
+![LoopLens detecting a loop live](docs/media/looplens-live-loop-detection.gif)
+
+## Drop it into any project
+
+LoopLens is **not a standalone app you rebuild your agent inside**. It's a tiny
+SDK you add to the agent you already have, plus a dashboard you open when you
+want to look.
+
+```python
+from looplens import trace, event
+
+with trace("research-agent"):
+    event("tool_call_started", tool="web_search", input={"query": "AI agents"})
+    event("tool_call_completed", tool="web_search", output={"results": 5})
+```
+
+Or wrap a function with `@observe` to capture inputs, outputs, latency, and
+errors automatically:
+
+```python
+from looplens import observe
+
+@observe(kind="tool")
+def web_search(query):
+    ...
+```
+
+The base install is **pure-stdlib with zero third-party dependencies**, so it
+won't conflict with anything in your agent's environment. Events are sent from a
+background thread (your loop never blocks). If the dashboard is running, events
+stream to it live; if not, the SDK buffers to a local JSONL file and **never
+crashes your app**.
+
+Configure via environment variables:
+
+```bash
+LOOPLENS_ENDPOINT=http://127.0.0.1:8765   # where the dashboard listens
+LOOPLENS_ENABLED=true                      # set false to make the SDK a no-op
+LOOPLENS_PROJECT=default
+LOOPLENS_CAPTURE_INPUTS=true
+LOOPLENS_CAPTURE_OUTPUTS=true
+LOOPLENS_TRACE_DIR=looplens-traces         # JSONL fallback location
+```
+
+## Install
+
+```bash
+pip install looplens             # the SDK (drop into your agent — zero deps)
+pip install "looplens[server]"   # adds the dashboard (FastAPI + prebuilt UI)
+```
+
+That's it — **no Node, no npm, no build step.** The `[server]` extra ships the
+compiled React dashboard inside the wheel, so `looplens dev` serves a ready UI on
+the first run. (`pipx install "looplens[server]"`, `uv pip install`, and
+`uv tool install` work the same way.)
+
+### Works with any agent or framework
+
+The base `looplens` SDK is **pure Python stdlib with zero third-party
+dependencies**, so it installs cleanly next to any agent stack and pins nothing:
+
+- **LangGraph / LangChain**, **CrewAI**, **AutoGen**, **OpenAI Agents SDK**,
+  **Pydantic AI**, or a hand-rolled `while` loop — if it's Python, you can
+  instrument it with `trace()` / `event()` / `@observe`.
+- No API key, no login, no network egress — events go to `127.0.0.1` only, and
+  the SDK is a no-op when `LOOPLENS_ENABLED=false`.
+- Fail-silent by design: if the dashboard isn't running it buffers to JSONL and
+  **never raises into your agent**.
+
+## Quickstart
+
+```bash
+pip install "looplens[server]"
+looplens dev      # start backend + prebuilt UI, opens http://localhost:8765
+looplens demo     # run a sample looping agent that trips a warning
+looplens doctor   # check the port, SDK->server round-trip, and JSONL fallback
+```
+
+`looplens dev` opens the dashboard in your browser automatically (pass
+`--no-open` to skip). If it doesn't, open <http://localhost:8765> yourself and
+watch the run appear live.
+
+## Architecture
+
+```
+Your agent app ──(looplens SDK)──▶ Local FastAPI server ──▶ SQLite
+                                          │
+                                          └──(live stream)──▶ React UI
+```
+
+- **SDK** (`looplens`): `trace()` + `event()`, background HTTP send, JSONL
+  fallback, fail-silent. Zero third-party deps.
+- **Server** (`looplens[server]`): FastAPI + SQLite + Pydantic, loop detectors,
+  metrics, real-time stream.
+- **UI**: React + Vite + TypeScript + Tailwind.
+
+## Examples
+
+Runnable agents under `examples/` exercise the detectors. Start the dashboard
+(`looplens dev`), then run any of them:
+
+```bash
+python examples/simple_agent.py         # a healthy run — no warnings
+python examples/looping_agent.py        # repeated tool call + no-progress loop
+python examples/retry_storm_agent.py    # retry storm
+python examples/handoff_bounce_agent.py # two agents ping-ponging handoffs
+```
+
+`looplens demo` runs the looping agent without needing the file checked out.
+
+`examples/real_research_agent_openai.py` is a **real** agent — it makes live
+OpenAI calls (function calling) against a tiny corpus that lacks the answer, so
+the model genuinely loops. Needs `pip install openai` and `OPENAI_API_KEY`
+(optionally `OPENAI_MODEL`):
+
+```bash
+OPENAI_API_KEY=sk-... PYTHONPATH=. python examples/real_research_agent_openai.py
+```
+
+## Build status
+
+This repo is being built phase by phase (see `PRD.md` section 24).
+
+- [x] **Phase 0** — repo scaffold, packaging, config
+- [x] **Phase 1** — FastAPI backend + SQLite + API routes + metrics
+- [x] **Phase 2** — Python SDK (`trace` / `event` / `@observe`, background sender, JSONL fallback)
+- [x] **Phase 3** — CLI (`init / server / ui / dev / watch / import / export / demo`)
+- [x] **Phase 6** — loop detection rules (repeated tool, similar input, no-progress, retry storm, long step, cost spike)
+- [x] **Phase 4** — React UI (runs list, run detail, live timeline, metrics bar, warnings, event drawer)
+- [x] **Phase 5** — real-time streaming (SSE: live events + metrics + warnings)
+- [x] **Phase 7** — polish, examples, demo
+
+## Running from source
+
+The published wheel ships the prebuilt dashboard, so end users never touch Node.
+Building **from a git checkout** is the only time you need npm — once, to compile
+the UI into the Python package:
+
+```bash
+pip install -e ".[server]"            # backend + CLI
+npm --prefix ui install               # one-time UI deps
+npm --prefix ui run build             # compiles the React bundle into looplens/server/_ui/
+python -m looplens.server             # or: looplens server  (serves API + UI)
+looplens demo                         # seed a looping run that trips warnings
+```
+
+Open `http://localhost:8765` for the dashboard. The backend serves the bundled UI,
+so it's a single URL. For UI development with hot reload, run `npm --prefix ui run
+dev` (Vite on :5173, proxies `/api` to the backend). Interactive API docs are at
+`http://localhost:8765/docs`.
+
+Packaging a release: run `npm --prefix ui run build` first, then `python -m build`
+— the wheel force-includes `looplens/server/_ui/` so it's installable with zero
+Node.
+
+## How loop detection works
+
+Detection is **rule-based and transparent** (PRD §17) — no black-box scoring. On
+every event the backend re-scans the run and raises (or updates) warnings:
+
+| Warning | Fires when |
+| --- | --- |
+| `repeated_tool_call` | same tool ≥3× within the last 8 **tool calls** (window slides over tool calls, not raw events, so interleaved ReAct traces still trip it) |
+| `repeated_tool_call_similar_input` | same tool ≥3× with ≥85% similar input |
+| `repeated_tool_call_exact_input` | same tool ≥3× with **byte-identical** input — highest-confidence repeat signal |
+| `no_progress` | a tool repeats with no `state_updated` / `memory_write` between calls |
+| `retry_storm` | `retry_triggered` ≥3× in the run |
+| `long_running_step` | a step over 30s |
+| `cost_spike` | one event > 50% of run cost so far (above a $0.05 floor) |
+| `handoff_bounce` | control ping-pongs between the same two agents (A→B→A→B) |
+
+Each warning carries a health penalty; the run's score (0–100) maps to
+**Healthy / Warning / Likely stuck / Failed**.
+
+## Limitations (MVP)
+
+- **Manual instrumentation only.** Framework adapters (LangGraph, OpenAI Agents
+  SDK, CrewAI) are on the V1 roadmap; today you call `trace()`/`event()`/`@observe`.
+- **Rule-based detection**, not semantic — similar-input uses string similarity,
+  not embeddings.
+- **Near-real-time, not push**: the SSE stream polls SQLite every ~0.5s.
+- **Single local user, no auth** — local-first by design, not a production service.
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest -q          # SDK resilience, all eight detectors, and the SSE stream
+```
+
+## Roadmap
+
+See [`ROADMAP.md`](ROADMAP.md) for what's next — PyPI release, CI, and framework
+adapters (LangGraph, OpenAI Agents SDK, CrewAI) to remove manual instrumentation.
+Launch copy lives in [`LAUNCH.md`](LAUNCH.md).
+
+## License
+
+MIT