greploom 0.1.0__tar.gz

greploom-0.1.0/.claude/commands/create-release.md

@@ -0,0 +1,17 @@
+# Create Release
+
+Help me create a new release of greploom.
+
+## Steps
+
+1. Ask me for the version number (should follow semver: major.minor.patch)
+2. Ask me for a brief description of what changed in this release
+3. Update the changelog section in README.md with the new version entry (newest first)
+4. Run the release script: `./scripts/release.sh <version> "<description>"`
+
+## Notes
+
+- The release script handles updating version.py, pyproject.toml, committing, tagging, and pushing
+- GitHub Actions will automatically create a GitHub Release and publish to PyPI
+- Make sure all tests pass before releasing: `pytest`
+- Make sure linting passes: `ruff check src tests`

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

@@ -0,0 +1,115 @@
+name: Release and Publish
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  create-release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Wait for tests to pass
+        uses: lewagon/wait-on-check-action@v1.3.1
+        with:
+          ref: ${{ github.ref }}
+          check-regexp: 'Test on Python'
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          wait-interval: 10
+
+      - name: Extract version from tag
+        id: version
+        run: |
+          VERSION=${GITHUB_REF#refs/tags/v}
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "tag=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
+
+      - name: Read version from version.py
+        id: read_version
+        run: |
+          VERSION_PY=$(grep -E '^__version__' src/greploom/version.py | cut -d'"' -f2)
+          echo "version_py=$VERSION_PY" >> $GITHUB_OUTPUT
+
+      - name: Verify version match
+        run: |
+          if [ "${{ steps.version.outputs.version }}" != "${{ steps.read_version.outputs.version_py }}" ]; then
+            echo "Error: Tag version (${{ steps.version.outputs.version }}) does not match version.py (${{ steps.read_version.outputs.version_py }})"
+            exit 1
+          fi
+
+      - name: Extract changelog for this version
+        id: changelog
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          CHANGELOG=$(awk "/### Version $VERSION/,/### Version [0-9]/ { if (/### Version [0-9]/ && !/### Version $VERSION/) exit; if (!/### Version $VERSION/) print }" README.md | sed '/^$/d')
+          if [ -z "$CHANGELOG" ]; then
+            CHANGELOG="Release version $VERSION"
+          fi
+          echo "$CHANGELOG" > /tmp/changelog.txt
+
+      - name: Create GitHub Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          CHANGELOG=$(cat /tmp/changelog.txt)
+          gh release create "${{ steps.version.outputs.tag }}" \
+            --title "Release ${{ steps.version.outputs.tag }}" \
+            --notes "$CHANGELOG" \
+            --verify-tag
+
+  build:
+    name: Build distribution
+    needs: [create-release]
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Store distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    needs: [build]
+    runs-on: ubuntu-latest
+
+    environment:
+      name: pypi
+      url: https://pypi.org/p/greploom
+
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distribution packages
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

greploom-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,79 @@
+name: Tests
+
+on:
+  push:
+    branches: [ main ]
+    tags:
+      - 'v*.*.*'
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    name: Test on Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[dev,mcp]
+
+      - name: Run tests with pytest
+        run: |
+          pytest --cov=greploom --cov-report=xml --cov-report=term-missing
+
+      - name: Lint with ruff
+        run: |
+          ruff check src tests
+
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    needs: [test]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check build with twine
+        run: |
+          pip install twine
+          twine check dist/*
+
+  status:
+    name: Tests Status
+    runs-on: ubuntu-latest
+    needs: [test, build]
+    if: always()
+
+    steps:
+      - name: Check test results
+        run: |
+          if [ "${{ needs.test.result }}" != "success" ] || [ "${{ needs.build.result }}" != "success" ]; then
+            echo "Tests or build failed"
+            exit 1
+          fi
+          echo "All tests passed successfully"

greploom-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+*.db
+.greploom/
+.DS_Store
+*.swp
+*~
+venv/
+.venv/
+
+# Test output
+/test-output/

greploom-0.1.0/CLAUDE.md

@@ -0,0 +1,73 @@
+# greploom -- Project Context
+
+greploom is a semantic code search library with graph-aware context retrieval. It reads a treeloom Code Property Graph (JSON), indexes it for hybrid search (vector + BM25), and returns structurally-complete context neighborhoods suitable for LLM consumption.
+
+See the [loom-research](https://github.com/rdwj/loom-research) repo for the full design document and architectural decisions.
+
+## Tech Stack
+
+- Python 3.10+, package name `greploom`
+- Search: sqlite-vec (vector), SQLite FTS5 (BM25), reciprocal rank fusion
+- Graph: reads treeloom CPG JSON format, walks edges for context expansion
+- Embeddings: nomic-embed-text via ollama (default), any OpenAI-compatible endpoint
+- CLI: click
+- Token counting: tiktoken
+- Build: Hatchling
+- Testing: pytest, 80%+ coverage target
+
+## Architecture
+
+```
+greploom/
+├── src/greploom/
+│   ├── index/          # Indexing pipeline: summarizer, embedder, storage
+│   │   ├── summarizer.py    # Generate text summaries from CPG nodes
+│   │   ├── embedder.py      # Embed summaries via ollama or API
+│   │   └── store.py         # SQLite storage (sqlite-vec + FTS5)
+│   ├── search/         # Search engine: hybrid search, ranking, context assembly
+│   │   ├── hybrid.py        # BM25 + vector search with RRF
+│   │   ├── expand.py        # Graph walk to assemble context neighborhoods
+│   │   └── budget.py        # Token budget management
+│   ├── cli/            # CLI commands
+│   │   ├── __init__.py
+│   │   ├── index_cmd.py
+│   │   ├── query_cmd.py
+│   │   └── serve_cmd.py
+│   ├── mcp/            # MCP server mode
+│   │   └── server.py
+│   ├── version.py
+│   └── __init__.py
+├── tests/
+│   ├── fixtures/
+│   ├── test_index/
+│   ├── test_search/
+│   └── test_cli/
+├── pyproject.toml
+├── CLAUDE.md
+└── README.md
+```
+
+## Design Principles
+
+1. **treeloom is the graph, greploom is the search.** greploom reads treeloom's CPG JSON — it never parses source code or builds its own graph.
+2. **SQLite-only storage.** sqlite-vec + FTS5. No servers, no Docker, one file. Portable and inspectable.
+3. **Hybrid search.** Vector similarity for semantic queries ("where is authentication?") + BM25 for symbol queries ("find UserService"). Reciprocal rank fusion merges results.
+4. **Graph expansion at query time.** Search finds candidate nodes. CPG walk adds callers, callees, imports, data flow sources. The agent gets code in structural context.
+5. **Token budget management.** Returns exactly as much context as the LLM can use, ranked by structural relevance. Default: 8000 tokens.
+6. **Incremental re-indexing.** Track content hash per node. On re-index, only re-embed changed nodes.
+
+## Relationship to treeloom
+
+greploom depends on treeloom but does not import treeloom at runtime for core search operations. The dependency is via the CPG JSON format:
+
+- `greploom index` reads a treeloom CPG JSON file and builds its search index
+- `greploom query` reads both the search index (SQLite) and the CPG JSON (for graph expansion)
+- The CPG JSON format is documented in treeloom's CLAUDE.md
+
+This means greploom can work with any tool that produces treeloom-compatible CPG JSON, not just treeloom itself.
+
+## Releasing
+
+The version lives in two files that must stay in sync:
+- `src/greploom/version.py` — `__version__ = "x.y.z"`
+- `pyproject.toml` — `version = "x.y.z"`

greploom-0.1.0/LICENSE

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

greploom-0.1.0/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: greploom
+Version: 0.1.0
+Summary: Semantic code search with graph-aware context retrieval, built on treeloom
+Author: rdwj
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: apsw>=3.45
+Requires-Dist: click>=8.0
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: sqlite-vec>=0.1.0
+Requires-Dist: tiktoken>=0.5.0
+Requires-Dist: treeloom>=0.3.0
+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'
+Provides-Extra: mcp
+Requires-Dist: fastmcp>=2; extra == 'mcp'
+Provides-Extra: ollama
+Requires-Dist: ollama>=0.3.0; extra == 'ollama'
+Description-Content-Type: text/markdown
+
+# greploom
+
+Semantic code search with graph-aware context retrieval, built on [treeloom](https://github.com/rdwj/treeloom).
+
+greploom reads a treeloom Code Property Graph (CPG JSON), indexes it for hybrid search (vector embeddings + BM25), and returns structurally-complete context neighborhoods for LLM consumption. Vector search finds the right neighborhood; graph traversal expands it to include callers, callees, imports, and data flow sources.
+
+## Installation
+
+```bash
+pip install greploom           # Core — CLI and search engine
+pip install greploom[mcp]      # Adds MCP server (requires fastmcp)
+```
+
+The default embedding model is `nomic-embed-text` via a local [Ollama](https://ollama.com) instance. Any OpenAI-compatible embedding endpoint works via `GREPLOOM_EMBEDDING_URL`.
+
+## Quick Start
+
+```bash
+# 1. Build a CPG with treeloom
+treeloom build src/ -o cpg.json
+
+# 2. Index for search (creates .greploom/index.db)
+greploom index cpg.json
+
+# 3. Search
+greploom query "where is authentication handled?"
+```
+
+## How It Works
+
+```
+Source code
+    |
+    v
+treeloom build --> CPG (JSON)
+    |
+    v
+greploom index --> vector store + BM25 index (SQLite)
+    |
+    v
+greploom query "how is auth handled?" --> context bundle
+    |
+    v
+LLM agent receives focused, graph-aware context
+```
+
+Storage is a single SQLite file using sqlite-vec for vectors and FTS5 for BM25. No server required, no Docker, portable and inspectable.
+
+## CLI Reference
+
+### `greploom index`
+
+Build or update the search index from a treeloom CPG JSON file.
+
+```
+greploom index CPG_JSON [OPTIONS]
+
+Arguments:
+  CPG_JSON    Path to the treeloom CPG JSON file
+
+Options:
+  --db PATH              SQLite database path (default: .greploom/index.db)
+  --tier [fast|enhanced] Summary tier (default: enhanced)
+  --model TEXT           Embedding model name
+  --ollama-url URL       Ollama server URL
+  --force                Re-index all nodes, ignoring content hashes
+```
+
+Re-indexing is incremental by default — only nodes whose content has changed are re-embedded. Use `--force` to rebuild from scratch.
+
+Summary tiers:
+- `fast` — function signatures only; fastest to build
+- `enhanced` — signatures, docstrings, and callees; better recall
+
+```bash
+# Index with defaults
+greploom index cpg.json
+
+# Use a custom database path and force full re-index
+greploom index cpg.json --db /tmp/myproject.db --force
+
+# Point at a non-default Ollama instance
+greploom index cpg.json --ollama-url http://gpu-box:11434
+```
+
+### `greploom query`
+
+Search the index and return graph-aware context.
+
+```
+greploom query QUERY_TEXT [OPTIONS]
+
+Arguments:
+  QUERY_TEXT    Natural language or symbol query
+
+Options:
+  --db PATH              SQLite database path (default: .greploom/index.db)
+  --cpg PATH             CPG JSON path for graph expansion
+  --budget INT           Token budget (default: 8192)
+  --top-k INT            Number of search results (default: 5)
+  --format [context|json] Output format (default: context)
+  --model TEXT           Embedding model name
+  --ollama-url URL       Ollama server URL
+```
+
+Without `--cpg`, the query returns ranked search hits with scores and summaries. With `--cpg`, hits are expanded through the graph and assembled into a context bundle trimmed to the token budget.
+
+```bash
+# Simple search — ranked hits with summaries
+greploom query "user authentication"
+
+# Full graph-expanded context, ready for an LLM
+greploom query "where is authentication handled?" --cpg cpg.json
+
+# Pipe JSON output to jq
+greploom query "UserService" --cpg cpg.json --format json | jq '.[].name'
+
+# Narrow token budget for smaller context windows
+greploom query "error handling" --cpg cpg.json --budget 4096
+```
+
+### `greploom serve`
+
+Start the MCP server.
+
+```
+greploom serve [OPTIONS]
+
+Options:
+  --db PATH                    SQLite database path
+  --cpg PATH                   Default CPG JSON path
+  --host TEXT                  Host to bind (default: 0.0.0.0)
+  --port INT                   Port to listen on (default: 8901)
+  --transport [streamable-http|stdio]  MCP transport (default: streamable-http)
+```
+
+```bash
+# Start the MCP server on default port 8901
+greploom serve --db .greploom/index.db --cpg cpg.json
+
+# stdio transport for direct agent integration
+greploom serve --transport stdio
+```
+
+## MCP Server
+
+The MCP server exposes two tools:
+
+**`search_code`** — Search code semantically and return graph-aware context.
+
+Parameters: `query` (required), `cpg_path` (required), `db_path`, `budget`, `top_k`
+
+**`index_code`** — Build or update the search index from a CPG JSON file.
+
+Parameters: `cpg_path` (required), `db_path`, `tier`
+
+Example MCP server URL for agent configuration: `http://localhost:8901/mcp`
+
+## Configuration
+
+All settings can be provided via environment variables. CLI flags override environment variables for individual commands.
+
+| Variable | Default | Description |
+|---|---|---|
+| `GREPLOOM_EMBEDDING_URL` | `http://localhost:11434` | Ollama or OpenAI-compatible endpoint |
+| `GREPLOOM_EMBEDDING_MODEL` | `nomic-embed-text` | Embedding model name |
+| `GREPLOOM_DB_PATH` | `.greploom/index.db` | SQLite database path |
+| `GREPLOOM_TOKEN_BUDGET` | `8192` | Default token budget for context assembly |
+| `GREPLOOM_SUMMARY_TIER` | `enhanced` | Summary tier (`fast` or `enhanced`) |
+
+To use an OpenAI-compatible embedding API instead of Ollama:
+
+```bash
+export GREPLOOM_EMBEDDING_URL=https://api.openai.com/v1
+export GREPLOOM_EMBEDDING_MODEL=text-embedding-3-small
+```
+
+## Relationship to treeloom
+
+greploom reads treeloom's CPG JSON format but does not import treeloom at runtime. `greploom index` reads the CPG JSON to build the search index; `greploom query` reads both the index and the CPG JSON for graph expansion. Any tool that produces treeloom-compatible CPG JSON will work.
+
+## Changelog
+
+### Version 0.1.0
+
+Initial release — full indexing pipeline (summarize, embed, store), hybrid search with RRF, graph expansion for context neighborhoods, token budget management, CLI (index/query/serve), and MCP server with search_code/index_code tools.
+
+## LLM Documentation
+
+This project provides [llms.txt](llms.txt) and [llms-full.txt](llms-full.txt) files following the [llmstxt.org](https://llmstxt.org/) specification for LLM-friendly documentation.
+
+## License
+
+MIT