Skip to content

Consolidate documentation and add SessionStart hook for AI assistants #400

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
saulshanabrook wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Consolidate documentation and add SessionStart hook for AI assistants #400

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 51 additions & 0 deletions .claude/hooks/SessionStart.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
#!/bin/bash
set -e

echo "🚀 Setting up egglog-python development environment..."
echo ""

# Check if uv is installed
if ! command -v uv &> /dev/null; then
echo "❌ Error: uv is not installed"
echo " Install with: curl -LsSf https://astral.sh/uv/install.sh | sh"
exit 1
fi

echo "📦 Syncing dependencies..."
if uv sync --all-extras --locked 2>&1 | grep -q "Resolved"; then
echo "✅ Dependencies synced successfully"
else
echo "✅ Dependencies already up to date"
Comment on lines +15 to +18
Copy link

Copilot AI Jan 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The grep logic for detecting successful dependency sync may not work reliably. The command checks if "Resolved" appears in the output, but uv sync --all-extras --locked with --locked flag will not resolve dependencies (it uses the lockfile). Consider checking the exit code instead or adjusting the conditional to better reflect what uv sync --locked actually outputs.

Suggested change
if uv sync --all-extras --locked 2>&1 | grep -q "Resolved"; then
echo "✅ Dependencies synced successfully"
else
echo "✅ Dependencies already up to date"
if uv sync --all-extras --locked; then
echo "✅ Dependencies are in sync"
else
echo "❌ Failed to sync dependencies"
exit 1

Copilot uses AI. Check for mistakes.
fi

echo ""
echo "🔍 Running quick validation checks..."
echo ""

# Run ruff check (non-blocking)
echo " → Checking code style with ruff..."
if uv run ruff check . --quiet 2>&1; then
echo " ✅ Ruff checks passed"
else
echo " ⚠️ Ruff found some issues (run 'uv run ruff check --fix .' to auto-fix)"
fi

# Run quick type check (non-blocking)
echo " → Type checking with mypy..."
if make mypy 2>&1 | tail -n 1 | grep -q "Success"; then
echo " ✅ Type checks passed"
else
echo " ⚠️ Type check issues found (run 'make mypy' for details)"
fi
Comment on lines +25 to +39
Copy link

Copilot AI Jan 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The error handling for ruff and mypy checks may not work as expected. Both commands redirect stderr to stdout with 2>&1, but if these commands fail, they won't cause the script to exit (due to the conditional if statement). However, since these are marked as non-blocking validation checks in the comment, the current behavior might be intentional. Consider making it clearer by removing set -e from affecting these commands or adding || true to make the intent explicit.

Copilot uses AI. Check for mistakes.

echo ""
echo "✨ Environment ready! Quick reference:"
echo ""
echo " Run tests: uv run pytest --benchmark-disable -vvv"
echo " After Rust edit: uv sync --reinstall-package egglog --all-extras"
echo " Format code: uv run ruff format ."
echo " Fix linting: uv run ruff check --fix ."
echo " Type check: make mypy"
echo ""
echo "📚 See docs/reference/contributing.md for complete development guide"
echo ""
205 changes: 0 additions & 205 deletions .github/AGENTS.md
View file
Open in desktop

This file was deleted.

127 changes: 120 additions & 7 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,125 @@
# `egglog` Python wrapper
# egglog Python

[![Documentation Status](https://readthedocs.org/projects/egglog-python/badge/?version=latest)](https://egglog-python.readthedocs.io/latest/?badge=latest) [![Test](https://github.com/egraphs-good/egglog-python/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/egraphs-good/egglog-python/actions/workflows/CI.yml) [![PyPi Package](https://img.shields.io/pypi/v/egglog.svg)](https://pypi.org/project/egglog/) [![License](https://img.shields.io/pypi/l/egglog.svg)](https://pypi.org/project/egglog/) [![Python Versions](https://img.shields.io/pypi/pyversions/egglog.svg)](https://pypi.org/project/egglog/) [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit) [![CodSpeed Badge](https://img.shields.io/endpoint?url=https://codspeed.io/badge.json)](https://codspeed.io/egraphs-good/egglog-python)

`egglog` is a Python package that provides bindings to the Rust library [`egglog`](https://github.com/egraphs-good/egglog/),
allowing you to use e-graphs in Python for optimization, symbolic computation, and analysis.
**egglog** is a Python package that provides bindings to the Rust library [`egglog`](https://github.com/egraphs-good/egglog/), allowing you to use **e-graphs** in Python for optimization, symbolic computation, and program analysis.

Please see the [documentation](https://egglog-python.readthedocs.io/) for more information.
## What are e-graphs?

Come say hello [on the e-graphs Zulip](https://egraphs.zulipchat.com/#narrow/stream/375765-egglog/) or [open an issue](https://github.com/egraphs-good/egglog-python/issues/new/choose)!
E-graphs (equality graphs) are data structures that efficiently represent equivalence classes of expressions. They enable powerful program optimizations through **equality saturation** - a technique that finds optimal expressions by exploring many equivalent representations simultaneously.

## How to cite
The underlying [`egglog`](https://github.com/egraphs-good/egglog) Rust library combines:
- **Datalog**: Efficient incremental reasoning and queries
- **Equality Saturation**: Term rewriting and optimization
- **E-graphs**: Compact representation of equivalent expressions

If you use **egglog-python** in academic work, please cite the paper:
See the paper ["Better Together: Unifying Datalog and Equality Saturation"](https://arxiv.org/abs/2304.04332) for details.

## Installation

```shell
pip install egglog
```

Requires Python 3.11+ and works on Linux, macOS, and Windows.

## Quick Example

Here's how to use egglog to prove that `2 * (x + 3)` is equivalent to `6 + 2 * x` through algebraic rewriting:

```{code-cell} python
Copy link

Copilot AI Jan 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The code block uses MyST-NB directive {code-cell} python which is designed for Sphinx documentation with the MyST-NB extension. This won't render properly on GitHub or PyPI where the README is typically displayed. Consider using standard markdown code fences (```python) for the README, or ensure that the rendering context (e.g., on PyPI) supports MyST-NB directives.

Suggested change
```{code-cell} python
```python

Copilot uses AI. Check for mistakes.
from __future__ import annotations
from egglog import *


class Num(Expr):
def __init__(self, value: i64Like) -> None: ...

@classmethod
def var(cls, name: StringLike) -> Num: ...

def __add__(self, other: Num) -> Num: ...

def __mul__(self, other: Num) -> Num: ...


egraph = EGraph()

# Create two expressions
expr1 = egraph.let("expr1", Num(2) * (Num.var("x") + Num(3)))
expr2 = egraph.let("expr2", Num(6) + Num(2) * Num.var("x"))


# Define rewrite rules for algebraic simplification
@egraph.register
def _num_rules(a: Num, b: Num, c: Num, i: i64, j: i64):
yield rewrite(a + b).to(b + a) # Commutative
yield rewrite(a * (b + c)).to((a * b) + (a * c)) # Distributive
yield rewrite(Num(i) + Num(j)).to(Num(i + j)) # Constant folding
yield rewrite(Num(i) * Num(j)).to(Num(i * j))


# Run equality saturation
egraph.saturate()

# Prove the expressions are equivalent
egraph.check(expr1 == expr2)

# Extract the simplified form
egraph.extract(expr1)
```

## Features

- **Pythonic API**: Natural Python syntax with type hints and decorators
- **High Performance**: Powered by Rust and the battle-tested egglog library
- **Type Safe**: Full type annotations and mypy support
- **Datalog Integration**: Combine e-graphs with relational queries
- **Rich Ecosystem**: Jupyter integration, visualization tools, examples
- **Well Documented**: Comprehensive tutorials, guides, and API reference

## Use Cases

egglog-python is useful for:
- **Compiler optimizations**: Optimize IR or DSL programs
- **Symbolic mathematics**: Simplify and manipulate mathematical expressions
- **Program synthesis**: Generate optimal programs from specifications
- **Query optimization**: Optimize database queries or data transformations
- **Theorem proving**: Automated reasoning with equality

## Documentation

**[📚 Full Documentation](https://egglog-python.readthedocs.io/)** - Tutorials, guides, and API reference

Key sections:
- [Tutorials](https://egglog-python.readthedocs.io/latest/tutorials/) - Step-by-step guides
- [How-to Guides](https://egglog-python.readthedocs.io/latest/how-to-guides/) - Task-oriented recipes
- [API Reference](https://egglog-python.readthedocs.io/latest/reference/) - Complete API documentation
- [Examples](https://egglog-python.readthedocs.io/latest/tutorials/examples/) - Real-world usage examples

## Contributing

Contributions are welcome! Whether you want to:
- Report a bug or request a feature
- Improve documentation
- Add examples
- Contribute code

See **[docs/reference/contributing.md](docs/reference/contributing.md)** for:
- Development setup and environment
- Running tests, linters, and type checkers
- Code standards and architecture overview
- Common patterns and troubleshooting

## Community

- **[💬 Zulip Chat](https://egraphs.zulipchat.com/)** - Join the e-graphs community
- **[🐛 Issues](https://github.com/egraphs-good/egglog-python/issues)** - Report bugs or request features
- **[📖 Changelog](https://egglog-python.readthedocs.io/latest/reference/changelog.html)** - See what's new

## Citation

If you use **egglog-python** in academic work, please cite:

```bibtex
@misc{Shanabrook2023EgglogPython,
Expand All @@ -25,3 +133,8 @@ If you use **egglog-python** in academic work, please cite the paper:
url = {https://arxiv.org/abs/2305.04311},
note = {Presented at EGRAPHS@PLDI 2023}
}
```

## License

MIT License - see LICENSE file for details.
Loading