🚀 ADPA - AST DuckDB Package Analyzer

Modern Python package analysis with semantic search capabilities

ADPA combines modern AST analysis with DuckDB's analytical power to provide intelligent code discovery and package insights. Perfect for developers who need to understand large codebases quickly. Features both command-line and interactive modes for optimal user experience.

✨ Features

🔍 Semantic Search - Find functions using natural language queries
📊 DuckDB Analytics - High-performance analysis with SQL queries
🎯 AST Analysis - Deep code structure understanding
⚡ Fast Indexing - Efficient package scanning and caching
🧠 Hybrid Embeddings - Optional graph neural network support
🎨 Beautiful CLI - Rich terminal interface with loguru logging
🎮 Interactive Mode - Guided workflows and examples
🛡️ Production Ready - Comprehensive error handling and testing

🚀 Quick Start

Installation

# Basic installation
pip install adpa

# Development installation
git clone https://github.com/your-org/adpa
cd adpa
uv sync

First Steps

# Start interactive mode (recommended for beginners)
adpa

# Or use command line directly
adpa index requests
adpa search "http client"

Basic Usage

# Interactive mode (recommended for beginners)
adpa

# Index a Python package
adpa index requests

# Search for code using natural language  
adpa search "http client"

# View package statistics
adpa stats

# Analyze call relationships
adpa call-graph --source "loads"

Python API

from adpa import PackageIndexer

# Create indexer
indexer = PackageIndexer()

# Index a package
results = indexer.index_package("requests") 
print(f"Indexed {results['functions']} functions")

# Semantic search
search_results = indexer.search_similar("decode json", threshold=0.3)
for func in search_results['functions']:
    print(f"{func['name']} - similarity: {func['similarity']:.2f}")

# Get statistics
stats = indexer.get_package_stats()
print(f"Total packages: {stats['totals']['packages']}")

📚 CLI Commands

`adpa index`

Index a Python package for analysis:

adpa index requests                    # Index requests package
adpa index --force numpy               # Force re-index numpy  
adpa index --embedding-type hybrid torch  # Use graph embeddings

`adpa search`

Search code using semantic similarity:

adpa search "http client"              # Find HTTP client code
adpa search "json decode" --threshold 0.3   # Precise JSON decoding
adpa search "async request" --type functions # Only search functions  
adpa search "database" --limit 20      # More results

`adpa stats`

Display comprehensive statistics:

adpa stats                    # Basic statistics
adpa stats --detailed         # Detailed package breakdown

`adpa call-graph`

Analyze function relationships:

adpa call-graph --source "loads"       # What calls loads()?
adpa call-graph --target "decode"      # What does decode() call?
adpa call-graph --package "json"       # All calls in json package

`adpa clean`

Clear indexed data:

adpa clean                    # Clear with confirmation
adpa clean --confirm          # Clear without prompt

🎮 Interactive Mode

ADPA provides an interactive mode for easier exploration and guided workflows:

# Start interactive mode
adpa

# Or use the interactive flag
adpa --interactive

The interactive mode provides:

🎯 Package Indexing Wizard - Guided package analysis
🔍 Guided Search Interface - Step-by-step search with options
📊 Statistics Dashboard - Interactive statistics viewer
🕸️ Call Graph Explorer - Visual call relationship analysis
📚 Built-in Examples - Run comprehensive examples and demos
❓ Help System - Interactive documentation and tips

Interactive Features

# Start interactive mode
adpa

# Navigate through menu options:
# 1. Index Package - Guided package indexing
# 2. Search Code - Interactive semantic search
# 3. Show Statistics - Database analytics
# 4. Call Graph - Function relationship analysis
# 5. Run Examples - Built-in examples and demos
# 6. Clean Database - Safe database management
# 7. Help - Detailed help and documentation

🎯 Advanced Features

Hybrid Graph Embeddings

Enable advanced graph neural network embeddings for better code understanding:

# Install with graph support
pip install adpa[graph]

# Use hybrid embeddings
adpa index --embedding-type hybrid torch

from adpa import PackageIndexer

# Create indexer with graph embeddings
indexer = PackageIndexer(use_graph_embeddings=True)
results = indexer.index_package("torch")

Custom Database Location

# Use custom database
adpa --db-path ./my_analysis.db index requests
adpa --db-path ./my_analysis.db search "http"

Getting Help

# Show general help
adpa --help

# Show command-specific help
adpa index --help
adpa search --help

# Interactive help system
adpa --interactive  # Choose "Help" from the menu

Built-in Examples

ADPA includes comprehensive examples to get you started:

# Run examples interactively
adpa --interactive
# Select "Run Examples" from the menu

Available examples:

Quick Demo - Basic ADPA functionality demonstration
Basic Usage - Comprehensive usage examples with Rich output
Demo Features - Package indexing and semantic search demo
Hybrid Embeddings - Advanced graph neural network embeddings
Production Example - Production deployment with monitoring

Verbose Logging

# Enable verbose output
adpa --verbose index requests

# Enable debug mode  
adpa --debug search "client"

Interactive Mode

ADPA provides an interactive mode for easier exploration:

# Start interactive mode
adpa

# Or use the interactive flag
adpa --interactive

🏗️ Architecture

ADPA uses a modern, layered architecture:

┌─────────────────────────────────────────────────────────┐
│                   🎨 CLI Layer                          │
│                (rich-click + loguru)                   │
├─────────────────────────────────────────────────────────┤
│                  🔍 Analysis Layer                      │
│              (PackageIndexer + Scanner)                 │  
├─────────────────────────────────────────────────────────┤
│                 🧠 Embedding Layer                      │
│          (SentenceTransformer + Optional PyG)          │
├─────────────────────────────────────────────────────────┤
│                  📊 Storage Layer                       │
│                    (DuckDB)                            │
└─────────────────────────────────────────────────────────┘

Core Components

PackageIndexer - Main indexing and search interface
PackageScanner - AST analysis and file processing
PackageASTAnalyzer - Deep AST structure analysis
HybridCodeEmbedder - Optional graph-based embeddings
CLI - Beautiful command-line interface with interactive mode

📊 Performance

ADPA is designed for performance with:

DuckDB - Columnar analytics for fast queries
Batch Processing - Efficient embedding generation
Caching - Smart file and model caching
Parallel Processing - Multi-threaded analysis
Incremental Updates - Only reprocess changed files

Benchmarks

Package	Functions	Index Time	Search Time
requests	150	2.3s	45ms
numpy	2,847	12.1s	52ms
torch	8,492	45.6s	78ms

Tested on MacBook Pro M2, 16GB RAM

🛠️ Development

Setup Development Environment

git clone https://github.com/your-org/adpa
cd adpa

# Install with uv (recommended)
uv sync

# Or with pip
pip install -e ".[dev]"

Code Quality

# Run tests
uv run pytest

# Code formatting
uv run black src/ tests/
uv run ruff check src/ tests/

# Type checking  
uv run mypy src/

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Add tests for new functionality
Ensure all tests pass (uv run pytest)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📋 Requirements

Python 3.11+ - Modern Python features
DuckDB 0.10+ - Latest analytics engine
Rich 13.0+ - Terminal formatting
SentenceTransformers 2.2+ - Embedding models

Optional Dependencies

PyTorch + PyTorch Geometric - For graph embeddings (pip install adpa[graph])
Polars + PyArrow - For performance (pip install adpa[performance])

🤔 FAQ

Q: How accurate is the semantic search? A: ADPA uses state-of-the-art sentence transformers with 85-95% relevance for code queries. Graph embeddings can improve this further.

Q: Can I use custom embedding models?
A: Yes! Pass any HuggingFace model name: PackageScanner(model_name="your-model")

Q: How much disk space does indexing use? A: Typical packages use 1-5MB per 1000 functions. The requests package (~150 functions) uses ~800KB.

Q: Can I index private/local packages? A: Yes! ADPA works with any importable Python package, including local development packages.

Q: How fast is the search? A: Search queries typically complete in 20-100ms for databases with 10,000+ functions.

Q: What's the difference between command-line and interactive mode? A: Command-line mode is faster for automation and scripting. Interactive mode provides guided workflows, built-in examples, and step-by-step assistance - perfect for learning and exploration.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

DuckDB - Amazing analytical database
Sentence Transformers - Excellent embedding models
PyTorch Geometric - Graph neural network framework
Rich - Beautiful terminal formatting
Loguru - Elegant logging

🔗 Links

Documentation: https://adpa.readthedocs.io
PyPI: https://pypi.org/project/adpa/
GitHub: https://github.com/your-org/adpa
Issues: https://github.com/your-org/adpa/issues

Made with ❤️ for the Python community

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
.github		.github
examples		examples
src/adpa		src/adpa
tests		tests
.gitignore		.gitignore
.python-version		.python-version
README.md		README.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

🚀 ADPA - AST DuckDB Package Analyzer

✨ Features

🚀 Quick Start

Installation

First Steps

Basic Usage

Python API

📚 CLI Commands

adpa index

adpa search

adpa stats

adpa call-graph

adpa clean

🎮 Interactive Mode

Interactive Features

🎯 Advanced Features

Hybrid Graph Embeddings

Custom Database Location

Getting Help

Built-in Examples

Verbose Logging

Interactive Mode

🏗️ Architecture

Core Components

📊 Performance

Benchmarks

🛠️ Development

Setup Development Environment

Code Quality

Contributing

📋 Requirements

Optional Dependencies

🤔 FAQ

📝 License

🙏 Acknowledgments

🔗 Links

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

`adpa index`

`adpa search`

`adpa stats`

`adpa call-graph`

`adpa clean`

Packages