# AGENTS.md
Guidance for AI coding agents (Claude Code, Codex, Cursor, ...) working in this
repository. Humans should start from [README.md](README.md) and
[docs/CONTRIBUTING.md](docs/CONTRIBUTING.md); this file is the condensed,
agent-oriented version and the single source of truth for agent instructions.
## What this project is
`dataprof` is a local, deterministic data profiling and quality assessment
library: a Rust workspace with a PyO3-based Python package on top. The release
surface is Rust library crates plus Python wheels — there is **no CLI binary**.
It profiles data and reports on it; it does not transform, clean, or move data.
Keep changes within that identity.
## Layout
- `Cargo.toml` (root) — workspace: versions, shared dependencies, feature flags.
- `crates/dataprof/src/` — public Rust facade (re-exports internal crates).
- `crates/dataprof-*` — core, metrics, csv/json/parquet parsers, engines,
partial analysis, db connectors, runtime, python bindings.
- `python/` — Python package sources and tests.
- `tests/` — Rust integration tests for the facade.
- `docs/` — guides, release notes, contributing, security policy.
- `examples/` — executable docs; CI runs them, keep them working.
## Build, test, lint
Prerequisites: Rust 1.96+, Python 3.10+, [uv](https://docs.astral.sh/uv/).
```bash
uv sync # install the Python dev environment
uv run maturin develop # build + install the local Python extension
# Focused tests (prefer these; match the command to your change)
cargo test -p dataprof-core
cargo test -p dataprof-python
uv run pytest python/tests/test_python_api.py -q
# Gates that CI enforces — run before committing
cargo fmt --all
cargo clippy --all --all-targets -- -D warnings
uv run ruff format python/ .github/scripts/
uv run ruff check python/ .github/scripts/
uv run ty check python/
```
Don't run every expensive workspace check for a small docs or Python-only
change; run what matches the change and list the commands in the PR body.
## Conventions
- **Commits**: conventional commits (`feat:`, `fix:`, `docs:`, `ci:`,
`chore:`, with optional scope like `fix(python):`). Release notes are
generated by git-cliff from commit subjects, so a non-conventional subject
can silently vanish from the changelog. Keep messages brief. Do **not** add
AI attribution trailers (`Co-Authored-By: Claude`, "Generated with...").
- **Branches**: `feature/...`, `fix/...`, `docs/...`, `perf/...`. PRs target
`master`. One behavior change per PR; no drive-by refactors.
- **Error handling**: never swallow decode/parse errors into defaults
(`.ok()`, `unwrap_or_default()` on decode paths). A silent error that turns
into a plausible number is the worst bug class for a profiler.
- **Semantics**: `None`/absent means "not analyzed"; empty means "analyzed,
nothing found". Preserve this distinction in reports and bindings.
- **Output contract**: profile numbers must be identical regardless of which
engine or input path produced them. If you touch an engine or parser, check
the other paths for parity.
## Project board rules
- Milestones are **releases only** (e.g. `0.9.1`). Do not create thematic
milestones.
- Themes/initiatives live in **epic issues** (e.g. "Epic: Agent & LLM
Integration"); link related issues from the epic body.
- No version-specific labels; use `area: *` and `type: *` labels.
## Key docs
- [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) — full contributor workflow.
- [docs/release-notes.md](docs/release-notes.md) — real state of the current
release, including breaking changes.
- [docs/SECURITY.md](docs/SECURITY.md) — supported versions, reporting.