cocoindex AGENTS.md

AGENTS.md

This file provides guidance to coding agents working with code in this repository. Claude Code compatibility is kept through CLAUDE.md, which imports this file.

Build and Test Commands

This project uses uv for Python project management.

Building

uv run maturin develop   # Build Rust code and install Python package (required after Rust changes)

Testing

cargo test               # Run Rust tests
uv run mypy              # Type check Python code
uv run pytest python/    # Run Python tests (use after both Rust and Python changes)

Code Formatting and Linting

uv run ruff format .           # Format Python code
uv run ruff format --check .   # Check formatting without making changes (same as CI)
uv run ruff check .            # Lint Python code
cargo fmt                      # Format Rust code

Pre-submission Checks

CI enforces the full pre-commit hook suite from .pre-commit-config.yaml, which covers more than the commands above — notably regenerating the CLI docs (docs/src/content/docs/cli.mdx) whenever cli.py changes. Run it locally before pushing:

uv tool install prek     # one-time; some hooks also need `protoc` (brew install protobuf)
prek run --all-files

Workflow Summary

Change Type	Commands to Run
Rust code only	uv run maturin develop && cargo test
Python code only	uv run mypy && uv run pytest python/
Both Rust and Python	Run all commands from both categories above
Python formatting	uv run ruff format .
Before pushing	prek run --all-files

Code Structure

cocoindex/
├── rust/                       # Rust crates (workspace)
│   ├── core/                   # Core engine crate
│   │   └── src/
│   │       ├── engine/         # Core engine
│   │       ├── state/          # States of the core engine
│   │       └── inspect/        # Database inspection utilities
│   ├── py/                     # Python bindings (PyO3)
│   ├── py_utils/               # Python-Rust utility helpers (error, convert, future)
│   ├── utils/                  # General utilities: error, batching, fingerprint, etc.
│   └── ops_text/               # Text processing operations (splitter, language detection)
│
├── python/
│   ├── cocoindex/              # Python package
│   │   ├── __init__.py         # Package entry point
│   │   ├── cli.py              # CLI commands
│   │   ├── _internal/          # Internal implementation for the core engine
│   │   │   ├── api.py          # Public API: mount, use_mount, mount_each, map, mount_target, App, fn, start/stop
│   │   │   ├── app.py          # App base implementation
│   │   │   ├── context_keys.py # ContextKey and ContextProvider
│   │   │   ├── environment.py  # Environment and lifespan handling
│   │   │   ├── function.py     # @coco.fn decorator implementation
│   │   │   ├── component_ctx.py # ComponentContext and component_subpath
│   │   │   ├── target_state.py # Target state implementation
│   │   │   └── core.pyi        # Type stubs for the Rust extension module (update when PyO3 APIs change)
│   │   ├── connectors/         # External system connectors (localfs, postgres, qdrant, lancedb, google_drive)
│   │   ├── connectorkits/      # Connector building utilities
│   │   ├── resources/          # Abstractions: file.py (FileLike), chunk.py (Chunk), schema.py
│   │   └── ops/                # Operations: text.py (RecursiveSplitter), sentence_transformers.py
│   └── tests/                  # Python tests
│
├── examples/                   # Example applications
├── docs/                       # Documentation
└── dev/                        # Development utilities