loom-tool 0.1.0__tar.gz

loom_tool-0.1.0/.env.example

@@ -0,0 +1,34 @@
+# Loom Configuration
+# Copy this file to .env and fill in your values
+
+# ============================================================================
+# Required
+# ============================================================================
+
+# Database configuration
+LOOM_DB_HOST=localhost
+LOOM_DB_PORT=6379
+
+# Embedding model (must match LOOM_EMBED_DIM)
+LOOM_EMBED_MODEL=nomic-ai/nomic-embed-text-v1.5
+LOOM_EMBED_DIM=768
+LOOM_EMBED_BATCH_SIZE=64
+
+# ============================================================================
+# Optional — enables LLM-assisted semantic linking (higher quality IMPLEMENTS edges)
+# Leave unset to use static extraction only (recommended for getting started)
+# ============================================================================
+
+# Examples:
+# LOOM_LLM_MODEL=ollama/llama3.2
+# LOOM_LLM_MODEL=openai/gpt-4o-mini
+# LOOM_LLM_MODEL=anthropic/claude-3-haiku-20240307
+LOOM_LLM_MODEL=
+
+# ============================================================================
+# Optional — Jira integration
+# ============================================================================
+
+LOOM_JIRA_URL=
+LOOM_JIRA_EMAIL=
+LOOM_JIRA_API_TOKEN=

loom_tool-0.1.0/.gitattributes

@@ -0,0 +1,22 @@
+# Enforce LF line endings to keep ruff format --check consistent across OS
+
+# Default to LF for all text
+* text=auto eol=lf
+
+# Explicit common text formats
+*.py text eol=lf
+*.pyi text eol=lf
+*.md text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf
+*.toml text eol=lf
+*.ini text eol=lf
+*.cfg text eol=lf
+*.txt text eol=lf
+*.json text eol=lf
+*.sh text eol=lf
+
+# Keep Windows scripts with CRLF if you add them later
+*.bat text eol=crlf
+*.cmd text eol=crlf
+*.ps1 text eol=crlf

loom_tool-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,25 @@
+---
+name: Bug report
+about: Report a problem in Loom
+title: "bug: "
+labels: [bug]
+---
+
+## What happened
+
+## What you expected
+
+## Steps to reproduce
+
+## Environment
+
+- OS:
+- Python version:
+- uv version:
+- FalkorDB image/tag:
+
+## Logs / output
+
+```text
+(paste relevant output here)
+```

loom_tool-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Questions / Discussions
+    url: https://github.com/ddevilz/loom/discussions
+    about: Please ask and answer questions here.

loom_tool-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,14 @@
+---
+name: Feature request
+about: Suggest an improvement
+title: "feat: "
+labels: [enhancement]
+---
+
+## Problem
+
+## Proposed solution
+
+## Alternatives considered
+
+## Additional context

loom_tool-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,7 @@
+## Summary
+
+## Changes
+
+## Testing
+
+## Notes

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

@@ -0,0 +1,58 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 10
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ['3.12']
+    
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        run: |
+          uv sync --dev
+
+      - name: Run linting
+        run: |
+          uv run ruff check .
+          uv run mypy src/
+
+      - name: Check formatting
+        run: |
+          uv run ruff format --check .
+
+      - name: Run tests
+        run: |
+          if [ "${{ matrix.os }}" = "windows-latest" ]; then
+            uv run pytest tests/unit/ -v --tb=short
+          else
+            uv run pytest -v --tb=short
+          fi
+        shell: bash
+
+      - name: Test package build
+        run: |
+          uv build --wheel
+          uv pip install dist/*.whl
+          uv run loom --version
+        shell: bash

loom_tool-0.1.0/.github/workflows/loom-full-index.yml

@@ -0,0 +1,34 @@
+name: Loom Full Index
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+
+jobs:
+  loom-full-index:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install Loom
+        run: |
+          uv sync
+
+      - name: Start FalkorDB
+        run: |
+          docker run -d -p 6379:6379 --name loom-db falkordb/falkordb
+
+      - name: Loom full index
+        run: |
+          uv run loom analyze . \
+            --graph-name "${{ github.repository }}" \
+            --force

loom_tool-0.1.0/.github/workflows/loom-index.yml

@@ -0,0 +1,37 @@
+name: Loom Incremental Sync
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  loom-sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install Loom
+        run: |
+          uv sync
+
+      - name: Start FalkorDB
+        run: |
+          docker run -d -p 6379:6379 --name loom-db falkordb/falkordb
+
+      - name: Loom incremental sync
+        run: |
+          uv run loom sync \
+            --old-sha "${{ github.event.before }}" \
+            --new-sha "${{ github.sha }}" \
+            --graph-name "${{ github.repository }}" \
+            --repo-path .

loom_tool-0.1.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,41 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.12'
+    
+    - name: Install uv
+      uses: astral-sh/setup-uv@v3
+      with:
+        version: "latest"
+    
+    - name: Build package
+      run: |
+        uv build
+    
+    - name: Check package
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install twine
+        python -m twine check dist/*
+    
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1

loom_tool-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.loom/
+.venv/
+__pycache__/
+.env
+.mypy_cache
+.pytest_cache
+.ruff_cache
+.claude/
+docs/New folder/
+scripts/audit_graph_coverage.py
+scripts/spotcheck_blast_radius.py

loom_tool-0.1.0/.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "loom": {
+      "command": "/Users/devashish/Desktop/loom/.venv/bin/loom",
+      "args": ["serve", "--graph-name", "loom_repo"],
+      "env": {
+        "LOOM_DB_HOST": "localhost",
+        "LOOM_DB_PORT": "6379"
+      }
+    }
+  }
+}

loom_tool-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

loom_tool-0.1.0/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Vector index DDL correctness and schema init error visibility
+- Embedding persistence via `vecf32()` for FalkorDB `VECTOR` type
+- Lexical context in `loom calls` (parents/children via `CONTAINS` edges)
+- Graph expansion includes `CONTAINS` edges in search
+- CLI ambiguity handling for `loom calls` target resolution
+- Comprehensive unit tests for vector indexing and embedding storage
+- QA diagnostic script for DB-level vector query validation
+- Open-source readiness: LICENSE (MIT), CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, GitHub templates, CI
+
+### Fixed
+- Vector index never created due to DDL syntax errors
+- `loom query` always falling back to brute-force vector search
+- Ambiguous names in `loom calls` failing with generic “Target not found”
+
+## [0.1.0] - 2026-03-09
+
+### Added
+- Initial release of Loom
+- Repository indexing into FalkorDB graph
+- Multi-language code understanding (Python, TS/JS, Java, Go, Rust, Ruby, markup)
+- Call graph extraction
+- Document ingestion (Markdown, PDF)
+- Jira and traceability workflows
+- Semantic linking (name match, embedding match, LLM match)
+- Incremental sync and watch mode
+- Semantic search with query-time graph expansion
+- MCP server for editor/agent integration
+- CLI commands: analyze, enrich, query, trace, calls, entrypoints, watch, sync, serve
+
+---
+
+## Release process
+
+1. Update version in `pyproject.toml`
+2. Add a new section to `CHANGELOG.md` under `[Unreleased]`
+3. Commit and push
+4. Create a GitHub Release with the changelog for that version
+5. Tag the release: `git tag v0.1.0 && git push --tags`

loom_tool-0.1.0/CLAUDE.md

@@ -0,0 +1,224 @@
+# Loom — Claude Code Context
+
+This file tells Claude Code everything it needs to know to work effectively in this repo.
+Read this before touching any file.
+
+---
+
+## What this project is
+
+Loom is a **unified code + document knowledge graph**. It reads a codebase (via tree-sitter AST parsing) and documentation files (PDFs, DOCX, Markdown, Confluence) and stores everything as nodes and edges in FalkorDB — a graph database.
+
+The key innovation: **code symbols and document sections are the same node type**, connected by semantic edges (`IMPLEMENTS`, `SPECIFIES`, `VIOLATES`). This enables queries like "does checkout_flow() satisfy PCI-DSS §3.4?" — something no existing tool can answer.
+
+---
+
+## Architecture — read this first
+
+```
+src/loom/
+├── core/        ← START HERE. Node, Edge, Graph. Every module uses these.
+├── ingest/      ← Source connectors. Code repos + doc files → raw data.
+├── analysis/    ← Intelligence. AST parsing, call tracing, communities, summaries.
+├── embed/       ← nomic-embed-text (unified embedding space for code AND docs).
+├── linker/      ← THE CORE INNOVATION. Creates IMPLEMENTS edges between code+docs.
+├── search/      ← Dual-traversal search across code graph + doc tree.
+├── watch/       ← watchfiles-based incremental re-indexer.
+├── drift/       ← Detects spec violations when code changes.
+├── llm/         ← LiteLLM wrapper. Routes to Ollama, OpenAI, Groq etc.
+└── mcp/         ← FastMCP server. 5 tools for Claude Code/Cursor/Copilot.
+```
+
+**Dependency flow:** `core` ← `ingest` ← `analysis` ← `embed` ← `linker` ← `search/watch/drift` ← `mcp`
+
+Never import from a downstream module into an upstream one. `core` has zero internal imports.
+
+---
+
+## The data model — understand this deeply
+
+Everything is a `Node` or an `Edge`. That's it.
+
+```python
+# A function in code:
+Node(id="function:src/auth.py:validate_user", kind=NodeKind.FUNCTION, source=NodeSource.CODE, ...)
+
+# A section in a spec document:
+Node(id="doc:specs/auth.pdf:3.2.4", kind=NodeKind.SECTION, source=NodeSource.DOC, ...)
+
+# The link between them (created by SemanticLinker):
+Edge(from_id="function:src/auth.py:validate_user",
+     to_id="doc:specs/auth.pdf:3.2.4",
+     kind=EdgeType.LOOM_IMPLEMENTS,
+     confidence=0.87,
+     link_method="embed_match")
+```
+
+**Node ID convention — never break this:**
+- Code: `"{kind}:{file_path}:{symbol_name}"` → `"function:src/auth.py:validate_user"`
+- Doc: `"doc:{doc_path}:{section_id}"` → `"doc:specs/auth.pdf:chapter_3.2.4"`
+
+---
+
+## Tech stack — key decisions
+
+| What | Tool | Why it matters |
+|---|---|---|
+| Graph DB | FalkorDB | Redis-based. Run: `docker compose up -d`. Port 6379. |
+| Embeddings | fastembed + nomic-embed-text-v1.5 | Local ONNX, no API key, 768-dim, works for both code and prose |
+| LLM | LiteLLM | `LOOM_LLM_MODEL=ollama/llama3.2` for local/free, `gpt-4o-mini` for fast |
+| Code parsing | tree-sitter | AST-based. Never use regex to parse code. |
+| Async | asyncio + winloop (Windows) / uvloop (Linux/Mac) | See platform check in `src/loom/__init__.py` |
+| Communities | igraph + leidenalg | Leiden algorithm on the call graph |
+| File watching | watchfiles | Rust-based, 500ms debounce |
+| MCP | FastMCP | `@mcp.tool()` decorator pattern |
+
+**Windows note:** uvloop doesn't support Windows. We use winloop instead. The platform check in `config.py` handles this automatically — don't remove it.
+
+---
+
+## Environment setup
+
+```bash
+# 1. Install dependencies
+uv sync
+
+# 2. Start FalkorDB
+docker compose up -d
+
+# 3. Copy env file
+cp .env.example .env
+
+# 4. Set your LLM (use Ollama for free local inference):
+# LOOM_LLM_MODEL=ollama/llama3.2
+# or:
+# LOOM_LLM_MODEL=gpt-4o-mini
+# LOOM_LLM_API_KEY=sk-...
+
+# 5. Run tests
+uv run pytest
+
+# 6. Verify graph connection
+uv run python scripts/check_env.py
+```
+
+---
+
+## Running Loom
+
+```bash
+# Index a repo
+uv run loom analyze /path/to/repo --docs /path/to/docs
+
+# Query
+uv run loom query "how does authentication work?"
+
+# Start MCP server
+uv run loom serve
+
+# Watch mode
+uv run loom watch /path/to/repo
+```
+
+---
+
+## Coding conventions
+
+**Async everywhere.** All I/O — graph queries, LLM calls, file reads — must be async. Use `asyncio.gather()` for concurrent operations. Never `time.sleep()` — always `await asyncio.sleep()`.
+
+**Semaphore for LLM calls.** Always wrap concurrent LLM calls with a semaphore:
+```python
+sem = asyncio.Semaphore(10)
+async def call_with_limit(prompt):
+    async with sem:
+        return await llm.complete(prompt)
+results = await asyncio.gather(*[call_with_limit(p) for p in prompts])
+```
+
+**MERGE not CREATE in FalkorDB.** Re-indexing must be idempotent. Always:
+```cypher
+MERGE (n:Node {id: $id}) SET n += $props
+```
+Never `CREATE` a node directly — it will create duplicates on re-index.
+
+**Bulk over N+1.** Never loop individual FalkorDB inserts. Always `UNWIND`:
+```python
+graph.query("UNWIND $nodes AS n MERGE (node:Node {id: n.id}) SET node += n",
+            {"nodes": [n.model_dump() for n in nodes]})
+```
+
+**LiteLLM for all LLM calls.** Never call OpenAI/Anthropic SDKs directly. Always go through `src/loom/llm/client.py` which wraps LiteLLM. This ensures Ollama/Groq/OpenAI all work with one config change.
+
+**Pydantic v2.** All data models use Pydantic v2 `BaseModel`. Use `model_dump()` and `model_validate()`. Never use `.dict()` (v1 API).
+
+**Type hints everywhere.** Every function must have complete type hints. `mypy --strict` must pass.
+
+---
+
+## Testing
+
+```bash
+uv run pytest                          # all tests
+uv run pytest tests/unit/              # unit tests only (no DB needed)
+uv run pytest tests/integration/       # integration tests (requires Docker)
+uv run pytest --cov=loom               # with coverage
+uv run pytest -k "test_node"           # specific test
+```
+
+**Test fixtures are in `tests/fixtures/`.**
+- `sample_graph.py` — 15 nodes, 20 edges, a realistic auth module. Reuse this everywhere.
+- `sample_repo/auth.py` — the Python file the parser tests run against.
+- `sample_docs/sample_spec.pdf` — the PDF the doc pipeline tests run against.
+
+**Integration tests require FalkorDB running.** They're marked with `@pytest.mark.integration` and skipped if the DB is unreachable.
+
+---
+
+## Current sprint: Sprint 1 — Graph Foundation
+
+**What we're building right now:**
+
+| Ticket | File | Status |
+|---|---|---|
+| LOOM-001 | Project init | ✅ Done |
+| LOOM-002 | Dependencies + env | ✅ Done |
+| LOOM-003 | `src/loom/core/node.py` | 🔄 In progress |
+| LOOM-004 | `src/loom/core/edge.py` | ⬜ Todo |
+| LOOM-005 | `src/loom/core/graph.py` | ⬜ Todo |
+| LOOM-006 | `src/loom/core/schema.py` | ⬜ Todo |
+| LOOM-007 | E2E test | ⬜ Todo |
+
+**Sprint goal:** `pytest tests/integration/test_graph_e2e.py` passes cleanly.
+
+---
+
+## What NOT to do
+
+- **Don't use regex to parse code.** tree-sitter exists for this. Regex breaks on nested structures.
+- **Don't call LLM APIs directly.** Always use `src/loom/llm/client.py`.
+- **Don't touch FalkorDB directly** outside of `src/loom/core/graph.py`. All DB access through `LoomGraph`.
+- **Don't create duplicate node IDs.** The ID convention is strict — use `MERGE`.
+- **Don't add uvloop directly on Windows.** Use the platform check in config.
+- **Don't run LLM calls sequentially in a loop.** Always `asyncio.gather()` with semaphore.
+- **Don't hardcode the LLM model.** Always read from config/env.
+
+---
+
+## Key algorithms (planned for v0.2+)
+
+These are NOT implemented yet but are planned. Don't implement them in v0.1:
+
+- **Personalized PageRank** (igraph) — for impact scoring instead of BFS
+- **Cross-encoder reranking** (sentence-transformers) — for better linker precision
+- **GumTree AST diffing** — for precise drift detection
+- **RAPTOR hierarchical summaries** — for multi-level doc intelligence
+- **HippoRAG search** — PPR-based retrieval over the unified graph
+
+---
+
+## Getting help
+
+- Architecture decisions → see `docs/architecture.md`
+- Ticket details → GitHub Issues (LOOM-XXX labels)
+- Graph queries → see `docs/cypher-examples.md`
+- LLM prompts used in the linker → see `src/loom/linker/prompts.py`

loom_tool-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,26 @@
+# Code of Conduct
+
+## Our Pledge
+
+We pledge to make participation in this project a harassment-free experience for everyone.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+
+Examples of unacceptable behavior include:
+
+- Harassment, discrimination, or insulting/derogatory comments
+- Trolling or personal attacks
+
+## Enforcement
+
+Project maintainers are responsible for clarifying standards and taking appropriate action.
+
+## Scope
+
+This Code of Conduct applies within project spaces and in public spaces when representing the project.

loom_tool-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing
+
+Thanks for your interest in contributing to Loom.
+
+## Development setup
+
+### Requirements
+
+- Python 3.12+
+- uv
+- Docker (for FalkorDB)
+
+### Setup
+
+```bash
+uv sync
+```
+
+Start FalkorDB:
+
+```bash
+docker run -d -p 6379:6379 --name loom-db falkordb/falkordb
+```
+
+Run tests:
+
+```bash
+uv run pytest -q
+```
+
+## Pull requests
+
+- Keep changes focused and incremental.
+- Add or update tests for behavioral changes.
+- Run the test suite before submitting.
+
+## Reporting bugs
+
+Please include:
+
+- What you expected vs what happened
+- Your OS and Python version
+- Loom commands run (and relevant logs)
+- FalkorDB version (Docker image tag)

loom_tool-0.1.0/LICENSE

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