Skip to content

Commit 1d92839

Browse files
claudeclaude
committed
Consolidate documentation and add SessionStart hook for AI assistants
- Add SessionStart hook (.claude/hooks/SessionStart.sh) to auto-verify environment setup - Consolidate AGENTS.md content into docs/reference/contributing.md (single source of truth) - Enhance README.md with better examples, features, use cases, and community links - Update docs/index.md to include README content (eliminates duplication) - Remove .github/AGENTS.md (no longer needed) Benefits: - No duplication between files - easier maintenance - SessionStart hook ensures proper setup for Claude Code sessions - Contributing.md is now comprehensive guide for both humans and AI - README provides rich landing page while feeding docs homepage - Tool-agnostic approach works for all AI assistants
1 parent 6a892ec commit 1d92839

File tree

5 files changed

+444
-274
lines changed

5 files changed

+444
-274
lines changed

‎.claude/hooks/SessionStart.sh‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
#!/bin/bash
2+
set -e
3+
4+
echo "🚀 Setting up egglog-python development environment..."
5+
echo ""
6+
7+
# Check if uv is installed
8+
if ! command -v uv &> /dev/null; then
9+
echo "❌ Error: uv is not installed"
10+
echo " Install with: curl -LsSf https://astral.sh/uv/install.sh | sh"
11+
exit 1
12+
fi
13+
14+
echo "📦 Syncing dependencies..."
15+
if uv sync --all-extras --locked 2>&1 | grep -q "Resolved"; then
16+
echo "✅ Dependencies synced successfully"
17+
else
18+
echo "✅ Dependencies already up to date"
19+
fi
20+
21+
echo ""
22+
echo "🔍 Running quick validation checks..."
23+
echo ""
24+
25+
# Run ruff check (non-blocking)
26+
echo " → Checking code style with ruff..."
27+
if uv run ruff check . --quiet 2>&1; then
28+
echo " ✅ Ruff checks passed"
29+
else
30+
echo " ⚠️ Ruff found some issues (run 'uv run ruff check --fix .' to auto-fix)"
31+
fi
32+
33+
# Run quick type check (non-blocking)
34+
echo " → Type checking with mypy..."
35+
if make mypy 2>&1 | tail -n 1 | grep -q "Success"; then
36+
echo " ✅ Type checks passed"
37+
else
38+
echo " ⚠️ Type check issues found (run 'make mypy' for details)"
39+
fi
40+
41+
echo ""
42+
echo "✨ Environment ready! Quick reference:"
43+
echo ""
44+
echo " Run tests: uv run pytest --benchmark-disable -vvv"
45+
echo " After Rust edit: uv sync --reinstall-package egglog --all-extras"
46+
echo " Format code: uv run ruff format ."
47+
echo " Fix linting: uv run ruff check --fix ."
48+
echo " Type check: make mypy"
49+
echo ""
50+
echo "📚 See docs/reference/contributing.md for complete development guide"
51+
echo ""

‎.github/AGENTS.md‎

Lines changed: 0 additions & 205 deletions
This file was deleted.

‎README.md‎

Lines changed: 120 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,125 @@
1-
# `egglog` Python wrapper
1+
# egglog Python
22

33
[![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)
44

5-
`egglog` is a Python package that provides bindings to the Rust library [`egglog`](https://github.com/egraphs-good/egglog/),
6-
allowing you to use e-graphs in Python for optimization, symbolic computation, and analysis.
5+
**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.
76

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

10-
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)!
9+
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.
1110

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

14-
If you use **egglog-python** in academic work, please cite the paper:
16+
See the paper ["Better Together: Unifying Datalog and Equality Saturation"](https://arxiv.org/abs/2304.04332) for details.
17+
18+
## Installation
19+
20+
```shell
21+
pip install egglog
22+
```
23+
24+
Requires Python 3.11+ and works on Linux, macOS, and Windows.
25+
26+
## Quick Example
27+
28+
Here's how to use egglog to prove that `2 * (x + 3)` is equivalent to `6 + 2 * x` through algebraic rewriting:
29+
30+
```{code-cell} python
31+
from __future__ import annotations
32+
from egglog import *
33+
34+
35+
class Num(Expr):
36+
def __init__(self, value: i64Like) -> None: ...
37+
38+
@classmethod
39+
def var(cls, name: StringLike) -> Num: ...
40+
41+
def __add__(self, other: Num) -> Num: ...
42+
43+
def __mul__(self, other: Num) -> Num: ...
44+
45+
46+
egraph = EGraph()
47+
48+
# Create two expressions
49+
expr1 = egraph.let("expr1", Num(2) * (Num.var("x") + Num(3)))
50+
expr2 = egraph.let("expr2", Num(6) + Num(2) * Num.var("x"))
51+
52+
53+
# Define rewrite rules for algebraic simplification
54+
@egraph.register
55+
def _num_rules(a: Num, b: Num, c: Num, i: i64, j: i64):
56+
yield rewrite(a + b).to(b + a) # Commutative
57+
yield rewrite(a * (b + c)).to((a * b) + (a * c)) # Distributive
58+
yield rewrite(Num(i) + Num(j)).to(Num(i + j)) # Constant folding
59+
yield rewrite(Num(i) * Num(j)).to(Num(i * j))
60+
61+
62+
# Run equality saturation
63+
egraph.saturate()
64+
65+
# Prove the expressions are equivalent
66+
egraph.check(expr1 == expr2)
67+
68+
# Extract the simplified form
69+
egraph.extract(expr1)
70+
```
71+
72+
## Features
73+
74+
- **Pythonic API**: Natural Python syntax with type hints and decorators
75+
- **High Performance**: Powered by Rust and the battle-tested egglog library
76+
- **Type Safe**: Full type annotations and mypy support
77+
- **Datalog Integration**: Combine e-graphs with relational queries
78+
- **Rich Ecosystem**: Jupyter integration, visualization tools, examples
79+
- **Well Documented**: Comprehensive tutorials, guides, and API reference
80+
81+
## Use Cases
82+
83+
egglog-python is useful for:
84+
- **Compiler optimizations**: Optimize IR or DSL programs
85+
- **Symbolic mathematics**: Simplify and manipulate mathematical expressions
86+
- **Program synthesis**: Generate optimal programs from specifications
87+
- **Query optimization**: Optimize database queries or data transformations
88+
- **Theorem proving**: Automated reasoning with equality
89+
90+
## Documentation
91+
92+
**[📚 Full Documentation](https://egglog-python.readthedocs.io/)** - Tutorials, guides, and API reference
93+
94+
Key sections:
95+
- [Tutorials](https://egglog-python.readthedocs.io/latest/tutorials/) - Step-by-step guides
96+
- [How-to Guides](https://egglog-python.readthedocs.io/latest/how-to-guides/) - Task-oriented recipes
97+
- [API Reference](https://egglog-python.readthedocs.io/latest/reference/) - Complete API documentation
98+
- [Examples](https://egglog-python.readthedocs.io/latest/tutorials/examples/) - Real-world usage examples
99+
100+
## Contributing
101+
102+
Contributions are welcome! Whether you want to:
103+
- Report a bug or request a feature
104+
- Improve documentation
105+
- Add examples
106+
- Contribute code
107+
108+
See **[docs/reference/contributing.md](docs/reference/contributing.md)** for:
109+
- Development setup and environment
110+
- Running tests, linters, and type checkers
111+
- Code standards and architecture overview
112+
- Common patterns and troubleshooting
113+
114+
## Community
115+
116+
- **[💬 Zulip Chat](https://egraphs.zulipchat.com/)** - Join the e-graphs community
117+
- **[🐛 Issues](https://github.com/egraphs-good/egglog-python/issues)** - Report bugs or request features
118+
- **[📖 Changelog](https://egglog-python.readthedocs.io/latest/reference/changelog.html)** - See what's new
119+
120+
## Citation
121+
122+
If you use **egglog-python** in academic work, please cite:
15123

16124
```bibtex
17125
@misc{Shanabrook2023EgglogPython,
@@ -25,3 +133,8 @@ If you use **egglog-python** in academic work, please cite the paper:
25133
url = {https://arxiv.org/abs/2305.04311},
26134
note = {Presented at EGRAPHS@PLDI 2023}
27135
}
136+
```
137+
138+
## License
139+
140+
MIT License - see LICENSE file for details.

0 commit comments

Comments
 (0)