flowindex 0.1.0__tar.gz

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

@@ -0,0 +1,14 @@
+name: CI
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: mypy flowindex
+      - run: pytest

flowindex-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,22 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

flowindex-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+dist/
+build/
+.flowindex/

flowindex-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FlowIndex Contributors
+
+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.

flowindex-0.1.0/PKG-INFO

@@ -0,0 +1,267 @@
+Metadata-Version: 2.4
+Name: flowindex
+Version: 0.1.0
+Summary: Behavior-first repository indexing for AI coding agents
+Project-URL: Homepage, https://github.com/adu3110/flowIndex
+Project-URL: Repository, https://github.com/adu3110/flowIndex
+Project-URL: Documentation, https://github.com/adu3110/flowIndex/tree/main/docs
+Project-URL: Issues, https://github.com/adu3110/flowIndex/issues
+Author: Aditi Chatterji
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,code-analysis,developer-tools,mcp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: gitpython>=3.1
+Requires-Dist: pydantic>=2.6
+Requires-Dist: rich>=13.7
+Requires-Dist: sqlmodel>=0.0.22
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: types-toml>=0.10; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# FlowIndex
+
+[![CI](https://github.com/adu3110/flowIndex/actions/workflows/ci.yml/badge.svg)](https://github.com/adu3110/flowIndex/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/flowindex)](https://pypi.org/project/flowindex/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Behavior-first repository indexing for AI coding agents.
+
+FlowIndex maps how a codebase behaves: entrypoints, call paths, tests, runtime traces, and git history. It helps AI coding agents understand impact before editing code.
+
+Most coding-agent tools index files, chunks, symbols, or embeddings. FlowIndex indexes behavior.
+
+It answers questions like:
+
+- What code path handles this feature?
+- What will break if I change this function?
+- Which tests should run for this patch?
+- Which previous bug fixes touched this area?
+- What minimal context should an agent receive before editing?
+
+## Why behavior-first?
+
+File trees and embedding search tell you what *exists*. They do not tell you what *runs*, what *breaks*, or what *matters* when you change a shared module.
+
+FlowIndex builds a local, deterministic behavior graph:
+
+- **Entrypoints** — API routes, webhooks, pages, CLI commands
+- **Call paths** — function-to-function relationships from static analysis
+- **Tests** — pytest, Jest/Vitest detection linked to symbols
+- **Git history** — co-change patterns and bug-fix commit signals
+- **Impact** — transparent risk scoring before you edit
+
+No vector database. No LLM calls. No SaaS. Inspectable SQLite.
+
+## How it differs
+
+| Approach | FlowIndex |
+|----------|-----------|
+| Repo maps / file trees | Behavior graph with entrypoints and call edges |
+| Embeddings / RAG | Deterministic lexical + graph ranking |
+| Agent frameworks | Developer tool that feeds agents context |
+| Generic static analysis | Agent-oriented impact, tests-for, context packs |
+
+## Installation
+
+```bash
+pip install flowindex
+```
+
+MCP support for Cursor / Claude Code:
+
+```bash
+pip install "flowindex[mcp]"
+```
+
+From source:
+
+```bash
+git clone https://github.com/adu3110/flowIndex.git
+cd flowIndex
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+```bash
+cd your-project
+flowindex init          # use --here inside nested example dirs
+flowindex scan
+flowindex overview
+flowindex explain "POST /api/payments"
+flowindex impact src/services/ledger.py
+flowindex tests-for update_ledger
+flowindex context "fix duplicate payments when webhook retries"
+```
+
+### Demo
+
+```bash
+cd examples/python_fastapi_app
+flowindex init --here
+flowindex scan
+flowindex context "fix duplicate payments when webhook retries"
+```
+
+Record a GIF locally: `brew install vhs && ./scripts/record-demo.sh`
+
+See [docs/demo-output.txt](docs/demo-output.txt) for captured terminal output.
+
+## CLI examples
+
+```bash
+# Initialize index in current repo
+flowindex init
+
+# Scan and build behavior graph
+flowindex scan
+
+# Explain an entrypoint flow
+flowindex explain "POST /payments"
+
+# Analyze change impact
+flowindex impact services/ledger.py
+
+# Suggest tests for a change
+flowindex tests-for services/ledger.py
+
+# Generate agent context pack
+flowindex context "fix webhook retry duplicate ledger entries"
+```
+
+## MCP usage (Cursor)
+
+Add to Cursor MCP settings (`~/.cursor/mcp.json` or project settings):
+
+```json
+{
+  "mcpServers": {
+    "flowindex": {
+      "command": "flowindex",
+      "args": ["mcp"],
+      "cwd": "/absolute/path/to/your/repo"
+    }
+  }
+}
+```
+
+Run `flowindex init && flowindex scan` in that repo first.
+
+Start the server manually:
+
+```bash
+flowindex mcp
+```
+
+Tools: `get_repo_overview`, `explain_entrypoint`, `get_change_impact`, `suggest_tests`, `make_context_pack`, and more — see [docs/mcp.md](docs/mcp.md).
+
+## Architecture
+
+```mermaid
+flowchart LR
+  subgraph ingest [Ingest]
+    Scan[File Scanner]
+    Py[Python Parser]
+    TS[TS/JS Parser]
+    Git[Git Analyzer]
+  end
+
+  subgraph index [Local Index]
+    DB[(SQLite)]
+    Graph[Behavior Graph]
+  end
+
+  subgraph out [Outputs]
+    CLI[CLI Commands]
+    MCP[MCP Server]
+    Pack[Context Packs]
+  end
+
+  Scan --> Py
+  Scan --> TS
+  Py --> Graph
+  TS --> Graph
+  Git --> Graph
+  Graph --> DB
+  DB --> CLI
+  DB --> MCP
+  DB --> Pack
+```
+
+## Example context pack
+
+```bash
+flowindex context "fix duplicate payments when webhook retries"
+```
+
+```md
+# FlowIndex Context Pack
+
+## Task
+fix duplicate payments when webhook retries
+
+## Likely Relevant Entrypoints
+- POST /payments
+- POST /stripe/webhook
+
+## Likely Relevant Files
+- main.py
+- services/ledger.py
+- services/payments.py
+
+## High-Risk Symbols
+- update_ledger()
+- handle_stripe_webhook()
+
+## Tests to Run
+- tests/test_payments.py
+
+## Caution
+- services/ledger.py has high change risk.
+- update_ledger() is shared by refunds and payments.
+```
+
+## Roadmap
+
+- [ ] Tree-sitter parsers for TS/JS and richer call resolution
+- [ ] Runtime trace ingestion (OpenTelemetry, test coverage)
+- [ ] Cross-repo dependency indexing
+- [ ] Patch-aware incremental scan
+- [ ] Language servers: Go, Rust, Java
+
+## Research questions
+
+- How much agent error reduction comes from behavior graphs vs embeddings?
+- What is the minimal context pack size that preserves patch correctness?
+- Can co-change graphs predict test selection better than import graphs alone?
+- Which entrypoint classes correlate most with production incidents?
+
+## Contributing
+
+1. Fork and clone the repository
+2. `pip install -e ".[dev]"`
+3. Make changes with tests
+4. `ruff check . && mypy flowindex && pytest`
+5. Open a pull request
+
+See [docs/](docs/) for concepts, CLI reference, and examples.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

flowindex-0.1.0/README.md

@@ -0,0 +1,231 @@
+# FlowIndex
+
+[![CI](https://github.com/adu3110/flowIndex/actions/workflows/ci.yml/badge.svg)](https://github.com/adu3110/flowIndex/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/flowindex)](https://pypi.org/project/flowindex/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Behavior-first repository indexing for AI coding agents.
+
+FlowIndex maps how a codebase behaves: entrypoints, call paths, tests, runtime traces, and git history. It helps AI coding agents understand impact before editing code.
+
+Most coding-agent tools index files, chunks, symbols, or embeddings. FlowIndex indexes behavior.
+
+It answers questions like:
+
+- What code path handles this feature?
+- What will break if I change this function?
+- Which tests should run for this patch?
+- Which previous bug fixes touched this area?
+- What minimal context should an agent receive before editing?
+
+## Why behavior-first?
+
+File trees and embedding search tell you what *exists*. They do not tell you what *runs*, what *breaks*, or what *matters* when you change a shared module.
+
+FlowIndex builds a local, deterministic behavior graph:
+
+- **Entrypoints** — API routes, webhooks, pages, CLI commands
+- **Call paths** — function-to-function relationships from static analysis
+- **Tests** — pytest, Jest/Vitest detection linked to symbols
+- **Git history** — co-change patterns and bug-fix commit signals
+- **Impact** — transparent risk scoring before you edit
+
+No vector database. No LLM calls. No SaaS. Inspectable SQLite.
+
+## How it differs
+
+| Approach | FlowIndex |
+|----------|-----------|
+| Repo maps / file trees | Behavior graph with entrypoints and call edges |
+| Embeddings / RAG | Deterministic lexical + graph ranking |
+| Agent frameworks | Developer tool that feeds agents context |
+| Generic static analysis | Agent-oriented impact, tests-for, context packs |
+
+## Installation
+
+```bash
+pip install flowindex
+```
+
+MCP support for Cursor / Claude Code:
+
+```bash
+pip install "flowindex[mcp]"
+```
+
+From source:
+
+```bash
+git clone https://github.com/adu3110/flowIndex.git
+cd flowIndex
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+```bash
+cd your-project
+flowindex init          # use --here inside nested example dirs
+flowindex scan
+flowindex overview
+flowindex explain "POST /api/payments"
+flowindex impact src/services/ledger.py
+flowindex tests-for update_ledger
+flowindex context "fix duplicate payments when webhook retries"
+```
+
+### Demo
+
+```bash
+cd examples/python_fastapi_app
+flowindex init --here
+flowindex scan
+flowindex context "fix duplicate payments when webhook retries"
+```
+
+Record a GIF locally: `brew install vhs && ./scripts/record-demo.sh`
+
+See [docs/demo-output.txt](docs/demo-output.txt) for captured terminal output.
+
+## CLI examples
+
+```bash
+# Initialize index in current repo
+flowindex init
+
+# Scan and build behavior graph
+flowindex scan
+
+# Explain an entrypoint flow
+flowindex explain "POST /payments"
+
+# Analyze change impact
+flowindex impact services/ledger.py
+
+# Suggest tests for a change
+flowindex tests-for services/ledger.py
+
+# Generate agent context pack
+flowindex context "fix webhook retry duplicate ledger entries"
+```
+
+## MCP usage (Cursor)
+
+Add to Cursor MCP settings (`~/.cursor/mcp.json` or project settings):
+
+```json
+{
+  "mcpServers": {
+    "flowindex": {
+      "command": "flowindex",
+      "args": ["mcp"],
+      "cwd": "/absolute/path/to/your/repo"
+    }
+  }
+}
+```
+
+Run `flowindex init && flowindex scan` in that repo first.
+
+Start the server manually:
+
+```bash
+flowindex mcp
+```
+
+Tools: `get_repo_overview`, `explain_entrypoint`, `get_change_impact`, `suggest_tests`, `make_context_pack`, and more — see [docs/mcp.md](docs/mcp.md).
+
+## Architecture
+
+```mermaid
+flowchart LR
+  subgraph ingest [Ingest]
+    Scan[File Scanner]
+    Py[Python Parser]
+    TS[TS/JS Parser]
+    Git[Git Analyzer]
+  end
+
+  subgraph index [Local Index]
+    DB[(SQLite)]
+    Graph[Behavior Graph]
+  end
+
+  subgraph out [Outputs]
+    CLI[CLI Commands]
+    MCP[MCP Server]
+    Pack[Context Packs]
+  end
+
+  Scan --> Py
+  Scan --> TS
+  Py --> Graph
+  TS --> Graph
+  Git --> Graph
+  Graph --> DB
+  DB --> CLI
+  DB --> MCP
+  DB --> Pack
+```
+
+## Example context pack
+
+```bash
+flowindex context "fix duplicate payments when webhook retries"
+```
+
+```md
+# FlowIndex Context Pack
+
+## Task
+fix duplicate payments when webhook retries
+
+## Likely Relevant Entrypoints
+- POST /payments
+- POST /stripe/webhook
+
+## Likely Relevant Files
+- main.py
+- services/ledger.py
+- services/payments.py
+
+## High-Risk Symbols
+- update_ledger()
+- handle_stripe_webhook()
+
+## Tests to Run
+- tests/test_payments.py
+
+## Caution
+- services/ledger.py has high change risk.
+- update_ledger() is shared by refunds and payments.
+```
+
+## Roadmap
+
+- [ ] Tree-sitter parsers for TS/JS and richer call resolution
+- [ ] Runtime trace ingestion (OpenTelemetry, test coverage)
+- [ ] Cross-repo dependency indexing
+- [ ] Patch-aware incremental scan
+- [ ] Language servers: Go, Rust, Java
+
+## Research questions
+
+- How much agent error reduction comes from behavior graphs vs embeddings?
+- What is the minimal context pack size that preserves patch correctness?
+- Can co-change graphs predict test selection better than import graphs alone?
+- Which entrypoint classes correlate most with production incidents?
+
+## Contributing
+
+1. Fork and clone the repository
+2. `pip install -e ".[dev]"`
+3. Make changes with tests
+4. `ruff check . && mypy flowindex && pytest`
+5. Open a pull request
+
+See [docs/](docs/) for concepts, CLI reference, and examples.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

flowindex-0.1.0/docs/LAUNCH.md

@@ -0,0 +1,64 @@
+# FlowIndex Launch Checklist
+
+Goal: maximize GitHub Trending visibility and developer adoption — not a guaranteed "#1 repo of the day," but a structured launch.
+
+## Before launch day
+
+### Product polish
+- [ ] `pip install flowindex` works from PyPI (not just editable install)
+- [ ] README demo GIF: `init --here` → `scan` → `context`
+- [ ] Cursor MCP config snippet copy-pasteable in README
+- [ ] GitHub repo description + topics: `ai`, `agents`, `mcp`, `developer-tools`, `code-analysis`
+- [ ] Pin repo on https://github.com/adu3110
+- [ ] CI badge green on main
+
+### Narrative
+- [ ] One-line pitch: "Behavior-first repo indexing for AI coding agents"
+- [ ] Show HN title drafted: "Show HN: FlowIndex – index how code behaves, not just files"
+- [ ] 60-second demo video or terminal recording
+- [ ] Blog post or site link from aditichatterji.com/research
+
+### Distribution list
+- [ ] Hacker News (Show HN)
+- [ ] X/Twitter thread with demo GIF
+- [ ] r/LocalLLaMA, r/programming
+- [ ] Cursor / MCP Discord servers
+- [ ] LinkedIn post (research-builder angle, not hype)
+
+## Launch day (Tuesday–Thursday, 9–11am PT)
+
+1. Publish PyPI if not already live
+2. Post Show HN within 5 minutes of tweet
+3. Link from personal site `/research#lab-notebooks`
+4. Ask 5–10 peers to engage organically on HN (comments, not bot stars)
+5. Monitor issues — respond within 1 hour
+
+## Week 1 follow-through
+- [ ] `v0.1.1` patch release (bug fixes from early users)
+- [ ] Add ledger.py to context ranking (known gap)
+- [ ] One example post: "FlowIndex on a FastAPI payments app"
+- [ ] Thank-you comment on HN with roadmap
+
+## What drives Trending
+
+GitHub Trending ranks repos by **stars in a ~24h window** relative to project size. You need:
+
+| Factor | Action |
+|--------|--------|
+| Spike traffic | HN front page or viral tweet |
+| Clear value in 10s | GIF + comparison table in README |
+| Easy install | PyPI one-liner |
+| Shareability | MCP + Cursor angle |
+| Credibility | Tests, CI, serious docs |
+
+Realistic targets:
+- **50–200 stars** — good launch with your network
+- **500–2k stars** — HN front page or influencer RT
+- **#1 global Trending** — rare; competes with major org releases
+
+## Do not
+
+- Buy stars or use star-for-star rings (GitHub detects abuse)
+- Force-push over contributors
+- Launch on Friday evening US time
+- Over-promise "production-ready" — say "dev tool, alpha, local-first"

flowindex-0.1.0/docs/PYPI.md

@@ -0,0 +1,32 @@
+# Publishing to PyPI
+
+FlowIndex uses [PyPI trusted publishing](https://docs.pypi.org/trusted-publishers/) via GitHub Actions.
+
+## One-time setup
+
+1. Create an account at [pypi.org](https://pypi.org/account/register/) if needed.
+2. On PyPI → **Your projects** → **Add new project** → name: `flowindex`
+3. PyPI → **Account settings** → **Publishing** → **Add a new pending publisher**:
+   - PyPI project name: `flowindex`
+   - Owner: `adu3110`
+   - Repository: `flowIndex`
+   - Workflow: `publish.yml`
+   - Environment: `pypi` (optional but recommended)
+4. On GitHub → repo **Settings** → **Environments** → create `pypi` (no secrets required for trusted publishing).
+
+## Publish a release
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+gh release create v0.1.0 --title "v0.1.0" --notes "Initial public release."
+```
+
+The `Publish to PyPI` workflow runs on release publish.
+
+Verify:
+
+```bash
+pip install flowindex
+flowindex --help
+```