AGENTS.md · docling-project/docling

Sections

1. Communication
2. Project overview
3. Project structure
4. Skills
5. Key commands
6. Code standards
7. When making changes
8. Before finishing

First lines (shown under the repo's MIT license)

# Docling

This file provides guidance to AI coding agents when working with code in this
repository.

## Communication

Use ASD-STE100 Simplified Technical English when you communicate with the user.
Use short sentences, active voice, and consistent terms. Keep code identifiers,
API names, and quoted source text exact. State the result and any limits clearly.

## Project overview

Docling is a Python SDK and CLI for converting PDFs, Office files, HTML,
Markdown, audio, images, XML, and other formats into a unified
`DoclingDocument` representation for downstream AI workflows.

## Project structure

```text
docling/                 # main Python package
docling/.agents/skills/  # usage skills shipped inside the package (see below)
packages/docling/        # full docling meta-package
packages/docling-slim/   # slim package readme
tests/                   # pytest suite and test data
docs/                    # MkDocs documentation and examples
scripts/                 # project maintenance scripts
```

## Skills

- **Development skills** (for contributors working *on* Docling) live in
  [`.agents/skills/`](.agents/skills/) at the repo root, e.g. `dignified-python`
  and `building-pydantic-ai-agents`.
  Select the applicable skills from the
  [task routes](.agents/skills/skill-router.json). For PR reviews and re-reviews,
  use [review](.agents/skills/review/SKILL.md) before you assess the changes.
- **Usage skills** (for agents *using* Docling to convert documents) are shipped
  inside the package at
  [`docling/.agents/skills/docling/`](docling/.agents/skills/docling/SKILL.md).
  They are packaged into the wheel/sdist so they are discoverable via
  `uvx`-style library skills once `docling` is installed. Keep them in sync with
  the CLI, the SDK (`PipelineOptions`), the Service Client, and the
  `docling-slim` extras when user-facing behavior changes.

## Key commands

```bash
make setup          # install CI-style dev environment
make test           # run pytest
make check          # run read-only local checks
make validate       # run mutating hooks on the current changeset
```

## Code standards

- Keep public APIs typed and compatible with Python 3.10+.
- Use `uv add` or project-local dependency patterns when dependencies change.
- Add focused tests for behavior changes; regenerate reference data only when
  conversion outputs intentionally change.
- Prefer structured models over loose dictionaries for durable schema-like data. Use Pydantic models or dataclasses when data crosses module boundaries, is serialized, or represents a stable contract. Exceptions may apply for internal datatypes and trivial data structures.
- Prefer `pathlib.Path` for path-handling code. Use `Path` operations instead of `os.path` in new or edited code unless an API explicitly requires string paths.
- Avoid `hasattr(...)`, broad `getattr(...)`, and similar attribute-probing patterns. These usually hide interface uncertainty. If such a check is genuinely required for compatibility with a documented third-party API, keep it narrowly scoped and explain in a comment.
- Do not add trivial or self-validating tests. Tests should verify meaningful application behavior, regressions, or integration boundaries, not restate assumptions about well-established library functionality or implementation details introduced only to validate the agent’s own code changes. Avoid mock-heavy tests unless mocking is the clearest way to exercise a real contract or failure mode.

## When making changes

1. Keep edits scoped and consistent with the surrounding module.
2. Update docs/examples when user-facing behavior changes.
3. Run targeted tests for touched behavior.
4. For reference output changes, use `DOCLING_GEN_TEST_DATA=1 uv run pytest`
   and review generated data carefully.

## Before finishing

Run `make validate` before considering a task complete. If hooks modify files,
review the changes and rerun `make validate` until it passes cleanly. Also run
the affected tests for the files or behavior you changed. Use `make check` when
you need a read-only verification pass.