Pygrad¶

Build searchable knowledge graphs from Python repository documentation

Transform any Python repository into an AI-powered documentation assistant using Graph RAG technology.

Features¶

Knowledge Graph¶

Automatically builds a semantic knowledge graph from Python source code, connecting classes, methods, functions, and usage examples.

Semantic Search¶

Ask natural language questions about any Python library and get accurate, contextual answers with code examples.

Tree-sitter Parsing¶

Fast and accurate AST parsing extracts classes, functions, docstrings, and type annotations from Python code.

Usage Examples¶

Automatically mines real usage examples from test files, notebooks, and example directories.

Local LLM Support¶

Works with Ollama and other local LLM providers for privacy-conscious deployments.

Simple API¶

Numpy-style API that's easy to learn and use: pg.add(), pg.search(), pg.list().

Quick Start¶

PythonCLI

import pygrad as pg

# Index a repository
await pg.add("https://github.com/pydantic/pydantic")

# Ask questions about it
result = await pg.search(
    "https://github.com/pydantic/pydantic",
    "How do I validate email addresses?"
)
print(result)

# Index a repository
pygrad add https://github.com/pydantic/pydantic

# Ask questions
pygrad ask https://github.com/pydantic/pydantic "How to validate emails?"

# List indexed repositories
pygrad list

How It Works¶

graph LR
    subgraph Input
        A[GitHub URL]
    end

    subgraph Processing
        B[Clone Repository]
        C[Parse with Tree-sitter]
        D[Extract API & Examples]
        E[Generate XML]
    end

    subgraph Storage
        F[Cognee Knowledge Graph]
    end

    subgraph Query
        G[Semantic Search]
        H[LLM Response]
    end

    A --> B --> C --> D --> E --> F
    F --> G --> H

Clone: Downloads the repository (shallow clone for speed)
Parse: Uses Tree-sitter to extract classes, functions, and docstrings
Extract: Finds usage examples from tests and example files
Generate: Creates structured API documentation in XML format
Index: Builds a knowledge graph using Cognee
Search: Answers questions using semantic search and LLM generation

Installation¶

pip install pygrad

For development:

pip install pygrad[dev]

Use Cases¶

Learning new libraries: Quickly understand how to use unfamiliar Python packages
API documentation: Generate searchable documentation from any codebase
Code exploration: Ask questions about large codebases
Developer onboarding: Help new team members understand internal libraries
Research: Analyze patterns across multiple repositories

License¶

Pygrad is released under the BSD 3-Clause License.