Docling Project Assistant

Expert assistant for working with the Docling document conversion library. This skill enforces critical project rules and provides guidance on development workflows, testing, and Docker usage.

Critical Rules (MUST FOLLOW)

When working with the Docling project, you MUST follow these rules:

1. **NEVER run Python directly** - Python is NOT installed locally. Use Docker for ALL Python tasks.

2. **NEVER modify files in `/home/corey/projects/docling/docling-github/`** - This is protected source from GitHub.

3. **Working directory**: Use `/home/corey/projects/docling/scout-docs/` for all new files and modifications.

These rules were strengthened after being violated 7-10 times. Breaking them demonstrates inability to follow explicit instructions.

Step-by-Step Instructions

When the user asks to run Python code or tests:

1. **Check if Docker is running**: Use `docker compose ps` to verify containers are up

2. **If containers are not running**: Execute `docker compose up -d` to start them

3. **Run Python commands in Docker**: Use `docker compose exec backend python -c "..."` or `docker compose exec backend bash` for interactive sessions

4. **Never attempt**: Running `python`, `pytest`, or any Python commands directly in the host shell

When the user asks to modify code:

1. **Verify the file path**: Check if the file is in `/home/corey/projects/docling/docling-github/`

2. **If in protected directory**: Inform the user that modifications cannot be made there, and ask if they want to create/modify in `/home/corey/projects/docling/scout-docs/` instead

3. **If in scout-docs**: Proceed with modifications

4. **After code changes**: Suggest running code quality checks using Docker:

- `docker compose exec backend ruff format`

- `docker compose exec backend ruff check --fix`

- `docker compose exec backend mypy docling`

When the user asks to add dependencies:

1. **Use uv for package management**: Execute `uv add <package>` to update pyproject.toml and uv.lock

2. **Rebuild Docker containers**: After dependency changes, run `docker compose build` to ensure containers have the new dependencies

3. **Restart if needed**: Use `docker compose restart` to apply changes

When the user asks to run tests:

1. **Ensure Docker is running**: Verify with `docker compose ps`

2. **Run pytest in Docker**: Use `docker compose exec backend pytest`

3. **For test data regeneration**: Use `docker compose exec backend bash -c "DOCLING_GEN_TEST_DATA=1 pytest"`

4. **Note about reference data**: All PRs modifying reference test data require double review

When the user asks about document conversion:

1. **Explain the conversion flow**:

- Input Processing → Backend Selection → Conversion → Pipeline Processing → Output Generation

2. **Key entry points**:

- `DocumentConverter` in `docling/document_converter.py`

- Format-specific backends in `docling/backend/`

3. **CLI usage** (inside Docker):

- Basic: `docling <file_or_url>`

- VLM pipeline: `docling --pipeline vlm --vlm-model smoldocling <file_or_url>`

- Note: vLLM automatically used on GPU for maximum performance

When the user asks to view logs:

1. **For all services**: Use `docker compose logs -f`

2. **For specific service**: Use `docker compose logs -f backend`

3. **Explain what to look for**: Conversion errors, pipeline issues, backend selection

When the user asks about documentation:

1. **Local preview**: Use `mkdocs serve` (runs on localhost:8000)

2. **Deployment**: Use `mkdocs gh-deploy` for GitHub Pages

3. **Documentation location**: Typically in `docs/` directory

4. **Tech stack**: MkDocs with Material theme

Architecture Overview

Core Components:

Technology Stack:

Important Notes

Common Docker Commands

```bash

Start services

docker compose up -d

Run Python code

docker compose exec backend python -c "print('Hello')"

Open shell

docker compose exec backend bash

View logs

docker compose logs -f backend

Run tests

docker compose exec backend pytest

Run code quality checks

docker compose exec backend ruff format

docker compose exec backend ruff check --fix

docker compose exec backend mypy docling

Stop services

docker compose down

```

Constraints

1. Always check if operations would violate the protected directory rule

2. Always use Docker for Python execution - no exceptions

3. Always verify Docker containers are running before attempting Python operations

4. Always suggest code quality checks after modifications

5. Always remind about double review requirement for test data changes