# CLAUDE.md — grafeo-langchain

Project-level instructions for Claude Code sessions.

## Project

grafeo-langchain — LangChain GraphStore and GraphVectorStore backed by GrafeoDB.

## Layout

```
grafeo-langchain/
├── src/grafeo_langchain/       # package source (src layout)
│   ├── __init__.py
│   ├── graph_store.py          # GrafeoGraphStore (knowledge graph)
│   ├── graph_vector_store.py   # GrafeoGraphVectorStore (vector + graph)
│   └── graph_document.py       # GraphDocument conversion helpers
├── tests/                      # pytest test suite
├── examples/                   # runnable usage examples
├── pyproject.toml              # project metadata, deps, tool config
└── .claude/                    # Claude Code project context (internal)
    ├── CLAUDE.md               # this file
    ├── ARCHITECTURE.md         # design decisions and component map
    ├── CODE_STYLE.md           # coding conventions
    ├── ROADMAP.md              # planned work (links to phase files)
    ├── todo/                   # actionable phase specs
    │   ├── phase-1-core.md
    │   ├── phase-2-polish.md
    │   └── phase-3-advanced.md
    └── .archive/               # completed / superseded docs
        └── grafeo-langchain.md # original monolithic design spec
```

## Tooling

| Tool       | Purpose                              | Command              |
|------------|--------------------------------------|----------------------|
| **uv**     | Package management, venv, lockfile   | `uv sync`, `uv run`  |
| **ruff**   | Linting + formatting                 | `ruff check`, `ruff format` |
| **ty**     | Type checking                        | `ty check`           |
| **pytest** | Testing                              | `uv run pytest`      |
| **prek**   | Git hooks — pre-commit in Rust       | `prek run --all-files` |

## Key Commands

```bash
# Install deps (creates venv automatically)
uv sync --all-extras

# Run tests
uv run pytest

# Lint & format
ruff check src/ tests/ --fix
ruff format src/ tests/

# Type check
ty check

# Run a single example
uv run python examples/basic_graph_store.py
```

## Conventions

- Python 3.12+, src layout (`src/grafeo_langchain/`)
- `from __future__ import annotations` in every module
- Type hints everywhere, no `Any` unless interfacing with LangChain ABCs
- ruff rule set: `["E", "F", "W", "I", "UP", "B", "SIM", "RUF"]`
- Line length: 120
- Test files mirror source: `test_graph_store.py` tests `graph_store.py`
- No docstring on trivial/obvious methods; concise Google-style docstrings otherwise

## Grafeo Source

The GrafeoDB source lives at `H:\GrafeoDB\grafeo\`. This is the upstream project and may contain unreleased APIs. Refer to it when you need to check Grafeo's actual method signatures, available features, or internal behavior.

When you discover bugs or missing features in Grafeo during testing, create a task file at `H:\GrafeoDB\grafeo\.claude\todo\4_language_bindings\` describing the issue and required fix.

## Dependencies

- **Runtime:** `grafeo>=0.4`, `langchain-core>=0.3,<1`
- **Optional:** `langchain-graph-retriever>=0.3` (for advanced traversal strategies)
- **Dev:** `pytest>=8`, `ruff>=0.11`, `ty>=0.1`, `langchain>=0.3`
- **CLI tools (installed separately):** `prek` (git hooks, Rust-based pre-commit replacement)

## Design Reference

Phase-specific specs with tasks, interface contracts, and implementation details:

- Phase 1 (Core): `.claude/todo/phase-1-core.md`
- Phase 2 (Polish): `.claude/todo/phase-2-polish.md`
- Phase 3 (Advanced): `.claude/todo/phase-3-advanced.md`

Original monolithic spec archived at `.claude/.archive/grafeo-langchain.md`.
