loomgraph 0.11.1__tar.gz

loomgraph-0.11.1/.claude/skills/loomgraph.md

@@ -0,0 +1,126 @@
+# LoomGraph Skill
+
+Use this skill when users ask about code search, code understanding, finding function callers/callees, or indexing a codebase for semantic search.
+
+## Overview
+
+LoomGraph is a code intelligence engine that provides:
+- **Code Indexing**: Parse code → Generate embeddings → Build knowledge graph
+- **Semantic Search**: Find code by natural language queries
+- **Graph Queries**: Find callers, callees, inheritance relationships
+
+## Prerequisites
+
+Before using LoomGraph commands, ensure dependencies are installed:
+
+```bash
+# Check status
+loomgraph status
+
+# If codeindex is missing
+pip install matrix-codeindex
+
+# If database is not running
+docker compose up -d postgres
+
+# If embedding service is not running
+docker compose up -d embedding
+```
+
+## Commands
+
+### Index a Repository
+
+**One-step (recommended for most cases)**:
+```bash
+loomgraph index /path/to/repo
+```
+
+**Step-by-step (for debugging or custom workflows)**:
+```bash
+# Step 1: Parse code with codeindex
+codeindex scan /path/to/repo --output json > parse_results.json
+
+# Step 2: Generate embeddings
+loomgraph embed parse_results.json --output embeddings.json
+
+# Step 3: Inject into graph database
+loomgraph inject parse_results.json embeddings.json
+```
+
+### Search Code
+
+```bash
+# Semantic search
+loomgraph search "user authentication logic"
+
+# With specific mode
+loomgraph search "login function" --mode semantic --limit 5
+```
+
+### Query Call Graph
+
+```bash
+# Find who calls a function
+loomgraph graph "UserService.login" --direction callers
+
+# Find what a function calls
+loomgraph graph "UserService.login" --direction callees
+
+# Find inheritance
+loomgraph graph "UserService" --relation-type INHERITS
+```
+
+## Output Format
+
+All commands output JSON for easy parsing:
+
+```json
+{
+  "success": true,
+  "data": { ... }
+}
+```
+
+Or on error:
+```json
+{
+  "success": false,
+  "error": {
+    "code": "ERROR_CODE",
+    "message": "Human readable message",
+    "suggestion": "How to fix it"
+  }
+}
+```
+
+## Error Recovery
+
+When a command fails, read the error message and follow the suggestion:
+
+| Error Code | Action |
+|------------|--------|
+| `CODEINDEX_NOT_FOUND` | `pip install matrix-codeindex` |
+| `DATABASE_CONNECTION_FAILED` | `docker compose up -d postgres` |
+| `EMBEDDING_SERVICE_UNAVAILABLE` | `docker compose up -d embedding` |
+
+## Example Workflow
+
+User asks: "Find all functions that call the login method"
+
+```bash
+# 1. First, ensure the codebase is indexed
+loomgraph status
+
+# 2. If not indexed, index it
+loomgraph index /path/to/repo
+
+# 3. Query the call graph
+loomgraph graph "login" --direction callers
+```
+
+## Documentation
+
+- CLI Reference: `docs/api/CLI_DESIGN.md`
+- System Design: `docs/architecture/SYSTEM_DESIGN.md`
+- Data Contract: `docs/api/DATA_CONTRACT.md`

loomgraph-0.11.1/.codeindex.yaml

@@ -0,0 +1,35 @@
+# codeindex configuration
+# Generated by Interactive Setup Wizard
+
+version: 1
+
+languages:
+  - python
+
+include:
+  - src/
+
+exclude:
+  - "**/*.pyc"
+  - "**/.eggs/**"
+  - "**/.git/**"
+  - "**/.pytest_cache/**"
+  - "**/.tox/**"
+  - "**/.venv/**"
+  - "**/__pycache__/**"
+  - "**/build/**"
+  - "**/dist/**"
+  - "**/node_modules/**"
+  - "**/tests/**"
+  - "**/venv/**"
+
+# Performance settings
+parallel_workers: 8
+batch_size: 50
+
+# Git Hooks configuration
+hooks:
+  post_commit:
+    enabled: false
+
+output_file: README_AI.md

loomgraph-0.11.1/.github/workflows/incremental-update.yml

@@ -0,0 +1,71 @@
+name: Incremental Update (Reusable)
+
+on:
+  workflow_call:
+    inputs:
+      lightrag_endpoint:
+        required: true
+        type: string
+        description: "LightRAG API endpoint URL"
+      embedding_endpoint:
+        required: true
+        type: string
+        description: "Embedding API endpoint URL"
+      working_directory:
+        required: false
+        type: string
+        default: '.'
+        description: "Working directory for the repository"
+      since:
+        required: false
+        type: string
+        default: 'HEAD~1'
+        description: "Git reference to compare from (default: HEAD~1)"
+
+jobs:
+  update:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 2  # Need HEAD~1 to detect changes
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ai-codeindex loomgraph
+
+      - name: Detect changed files
+        id: changes
+        run: |
+          cd ${{ inputs.working_directory }}
+          codeindex affected --json --since ${{ inputs.since }} > changed.json
+
+          # Check if any files changed
+          CHANGED_COUNT=$(cat changed.json | jq -r '.affected_files | length')
+          echo "changed_count=$CHANGED_COUNT" >> $GITHUB_OUTPUT
+
+          if [ "$CHANGED_COUNT" -gt 0 ]; then
+            FILES=$(cat changed.json | jq -r '.affected_files[]' | tr '\n' ',' | sed 's/,$//')
+            echo "files=$FILES" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Incremental update
+        if: steps.changes.outputs.changed_count > 0
+        run: |
+          cd ${{ inputs.working_directory }}
+          loomgraph update \
+            --files "${{ steps.changes.outputs.files }}" \
+            --lightrag-url "${{ inputs.lightrag_endpoint }}" \
+            --embedding-url "${{ inputs.embedding_endpoint }}"
+
+      - name: No changes
+        if: steps.changes.outputs.changed_count == 0
+        run: |
+          echo "No code files changed. Skipping update."

loomgraph-0.11.1/.github/workflows/release.yml

@@ -0,0 +1,128 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write    # GitHub Release upload
+  id-token: write    # PyPI Trusted Publisher (OIDC)
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["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 uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install dependencies
+        run: |
+          uv venv
+          uv pip install -e ".[dev]"
+
+      - name: Lint
+        run: |
+          source .venv/bin/activate
+          ruff check src/ tests/
+
+      - name: Unit tests
+        run: |
+          source .venv/bin/activate
+          pytest tests/unit/ -v --tb=short
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.VERSION }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build + twine
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+
+      - name: Build wheel + sdist
+        run: python -m build
+
+      - name: Inspect distribution metadata
+        run: twine check dist/*
+
+      - name: Extract version from tag
+        id: version
+        run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/loomgraph/${{ needs.build.outputs.version }}/
+    permissions:
+      id-token: write    # Trusted Publisher OIDC
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # OIDC — no API token; project must be configured as a Trusted Publisher
+        # at https://pypi.org/manage/project/loomgraph/settings/publishing/
+
+  github-release:
+    needs: [build, publish-pypi]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+      - name: Extract changelog for this version
+        id: changelog
+        run: |
+          VERSION=${{ needs.build.outputs.version }}
+          CHANGELOG=$(sed -n "/^## \[${VERSION}\]/,/^## \[/p" CHANGELOG.md | head -n -1)
+          if [ -z "$CHANGELOG" ]; then
+            CHANGELOG="Release v${VERSION}"
+          fi
+          echo "BODY<<EOF" >> $GITHUB_OUTPUT
+          echo "$CHANGELOG" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          body: ${{ steps.changelog.outputs.BODY }}
+          files: |
+            dist/*.whl
+            dist/*.tar.gz

loomgraph-0.11.1/.github/workflows/test.yml

@@ -0,0 +1,40 @@
+name: Test
+
+on:
+  pull_request:
+    branches: [develop, main]
+  push:
+    branches: [develop]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["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 uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install dependencies
+        run: |
+          uv venv
+          uv pip install -e ".[dev]"
+
+      - name: Lint
+        run: |
+          source .venv/bin/activate
+          ruff check src/ tests/
+
+      - name: Unit tests
+        run: |
+          source .venv/bin/activate
+          pytest tests/unit/ -v --tb=short

loomgraph-0.11.1/.gitignore

@@ -0,0 +1,132 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.env.local
+.env.*.local
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.project
+.pydevproject
+.settings/
+*.sublime-project
+*.sublime-workspace
+.spyderproject
+.spyproject
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# ruff
+.ruff_cache/
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# LoomGraph specific
+*.db
+*.sqlite
+*.log
+loomgraph_index/
+.loomgraph/
+.loomgraph.yaml
+.loomgraph.yml
+
+# Customer configs (contain internal URLs)
+customers/customers.yaml
+customers/*/config.yaml
+customers/*/
+
+# Secrets
+*.pem
+*.key
+secrets.yaml
+secrets.yml
+
+# UV
+uv.lock
+
+# Test artifacts
+test_output/
+test_index/

loomgraph-0.11.1/.loomgraph.example.yaml

@@ -0,0 +1,27 @@
+# LoomGraph Configuration
+# Copy to .loomgraph.yaml and customize
+
+# LightRAG API connection
+lightrag:
+  # H200 server
+  api_url: "http://117.131.45.179:3001"
+  api_timeout: 30.0
+  default_query_mode: "hybrid"  # local, global, hybrid, naive
+
+# Embedding service (optional, managed by LightRAG)
+embedding:
+  provider: "jina"
+  model: "jinaai/jina-embeddings-v2-base-code"
+  base_url: "http://117.131.45.179:3002"
+  batch_size: 32
+  dimension: 768
+
+# Retrieval settings
+retrieval:
+  default_mode: "hybrid"  # keyword, semantic, graph, hybrid
+  top_k: 10
+  similarity_threshold: 0.7
+
+# Application settings
+debug: false
+log_level: "INFO"