Packaging and distribution
==========================

AutoRAG is distributed from GitHub, **not** PyPI. Consumers pin to a
git tag:

.. code-block:: bash

    pip install "autorag[all] @ git+https://github.com/AutoLogger/AutoRAG@v0.10.0"

Build backend: ``uv_build``. The package layout is the standard ``src/``
shape:

.. code-block:: text

    src/autorag/             # importable package
    src/autorag/static/viz/  # committed React bundle (shipped in the wheel)
    frontend/                # React source — not shipped

Releasing a new version
-----------------------

1. Bump ``__version__`` in ``src/autorag/__init__.py`` and ``version``
   in ``pyproject.toml``.
2. Run ``uv lock`` to refresh the lock file. Commit.
3. ``git tag v0.x.0 && git push --tags``.

Consumers then pin to the tag.

CI
--

``.github/workflows/ci.yml`` runs on every push and PR to ``main``.
Three parallel jobs:

* **Lint & Type Check** — ``ruff check``, ``ruff format --check``,
  ``mypy`` (installs ``--all-extras`` so mypy can see torch /
  chromadb / etc.).
* **Tests (all extras)** — ``pytest -v`` against the full dep stack.
* **SDK base install (no extras)** — ``uv sync --frozen --no-dev``,
  then asserts ``from autorag import AutoRAG`` boots and the SDK
  methods are callable. This is the regression guard for the
  lazy-import contract — if anyone re-introduces a ``chromadb`` /
  ``torch`` / ``whisper`` / ``pyannote`` / ``yt_dlp`` import at module
  top in ``core.py`` / ``embed.py`` / ``__init__.py`` / ``store.py``
  / ``audio_source.py``, this job fails.

The workflow uses ``uv sync --frozen`` (fails if ``uv.lock`` is out of
sync with ``pyproject.toml``). If you change dependencies, run
``uv lock`` locally before pushing.

Docs build
----------

Local build:

.. code-block:: bash

    uv sync --group docs
    uv run make -C docs strict        # treats warnings as errors

The ``[docs]`` extra (sphinx, furo, sphinx-autodoc-typehints,
myst-parser) lives in ``[dependency-groups]`` rather than
``[project.optional-dependencies]`` so it doesn't appear in published
wheels — docs aren't a runtime extra.

``docs/conf.py`` mirrors the runtime extras in
:data:`autodoc_mock_imports <docs.conf.autodoc_mock_imports>` so the
strict docs build works from a base+docs install too (no extras). When
you add a new extras-gated import, add it to that list as well — same
rule as the mypy overrides and the ``[tool.pyright]`` config.

CI also builds and publishes the docs to **GitHub Pages** via
``.github/workflows/docs.yml``. On push to ``main`` (path-filtered to
``docs/**``, ``src/autorag/**``, ``pyproject.toml``, ``uv.lock``, and
the workflow itself) plus ``workflow_dispatch``, it runs
``uv sync --frozen --group docs``, ``make -C docs strict``, drops a
``.nojekyll``, and publishes ``docs/_build/html`` to GitHub Pages
with the official ``upload-pages-artifact`` / ``deploy-pages``
actions (build + deploy jobs, ``concurrency: pages``,
``cancel-in-progress: false``). It installs **base + docs only**, so
it doubles as a second guard that the ``autodoc_mock_imports`` list
stays complete. Requires Settings → Pages → Source = "GitHub Actions"
(one-time, UI-only); served at https://autologger.github.io/AutoRAG/.

Pydantic schemas + ``TYPE_CHECKING``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Pydantic API-schema models (``src/autorag/schemas.py``) resolve field
annotations at runtime, so imports used only in their annotations
(e.g. ``pathlib.Path``) must stay as **runtime** imports — never moved
into a ``TYPE_CHECKING`` block.
``[tool.ruff.lint.flake8-type-checking] runtime-evaluated-base-classes = ["pydantic.BaseModel"]``
stops TC003 from auto-suggesting that move; doing it anyway leaves
the model "not fully defined" and breaks ``model_rebuild()`` /
FastAPI schema gen / the autodoc build.

Third-party stubs
-----------------

These packages have no stubs — covered by mypy
``ignore_missing_imports`` overrides in ``pyproject.toml``:

* ``whisperx``, ``faster_whisper``, ``umap``, ``pydantic_sqlite``,
  ``imageio_ffmpeg``, ``chromadb``, ``pyannote``, ``yt_dlp``.

``langchain-ollama`` and ``langchain-core`` ship inline types — no
overrides needed. ``sklearn`` has no stubs and is suppressed with
``# type: ignore[import-untyped]`` at each import site.

Pylance / Pyright
-----------------

``.vscode/settings.json`` enables Pylance with
``typeCheckingMode: "strict"``. Pylance doesn't read mypy overrides,
so ``[tool.pyright]`` in ``pyproject.toml`` mirrors them:
``reportMissingTypeStubs = "none"`` for the unstubbed third-party set,
and ``reportPrivateUsage = "none"`` for the ``pydantic_sqlite._db``
access. It also disables ``reportUnknownArgumentType`` /
``VariableType`` / ``MemberType``, since mypy strict already catches
the cases the codebase cares about and Pylance's strict mode flags
``Any`` propagation more aggressively than wanted.

If you add a new untyped third-party dep: add it to **both** the mypy
overrides and the pyright config — ``reportMissingTypeStubs = "none"``
covers all unstubbed deps in one shot.