Getting Started

indx requires Python 3.11 or newer. The repository uses uv for Python dependencies and just for repeatable commands. jq is needed only by the bundled demo.

Install

Start with the development and acceptance-test dependencies:

uv sync --all-packages --all-groups

This intentionally carries no model runtime. Add every runnable engine when you want OCR, VLM, and model-backed embeddings:

uv sync --all-packages --all-groups --all-extras

You can install one heavy lane instead, for example --extra ocr. Run uv run indx capabilities at any time. It shows what the current environment can route against, and why an installed capability may be unavailable.

See it decide

just demo::run

The demo plans native text, detects an invoice specialist, and executes a scanned fixture. On the minimal installation the scan descends to manual review; with the OCR extra it is read. In both cases the page remains accounted for.

Use the interfaces

CLI

uv run indx plan --signatures \
  file://$PWD/tests/fixtures/invoice-anthropic.pdf

uv run indx encode \
  file://$PWD/tests/fixtures/mixed-multipage.pdf

Python

from indx import Indx, PlanRequest, RequestId, UriSource

service = Indx()
plan = service.plan(
    PlanRequest(
        request_id=RequestId("quickstart"),
        source=UriSource(uri="file:///absolute/path/report.pdf"),
    )
)

print(plan.status)
print(plan.routes[0].selected.capability_id)

HTTP

Start the server:

just demo::server

Then plan a file visible to that server process:

curl -s http://127.0.0.1:8000/v1/plan \
  -H 'content-type: application/json' \
  -d '{
    "request_id": "quickstart",
    "source": {
      "type": "uri",
      "uri": "file:///absolute/path/report.pdf"
    }
  }'

The plan is an artifact

Its source digest, media type, policy version, and content-addressed capability snapshot bind the decision to the input and environment that produced it. A later encode can execute that exact plan. If the source or snapshot no longer matches, the plan is rejected explicitly.

file:// works above because the workspace install includes indx-loader-file. URI schemes are a property of what is installed, not of indx. file:/data: come from indx-loader-file, http:/https: from indx-loader-http, and s3: from indx-loader-s3. Every format indx observes arrives the same way, from indx-observer-pdf, indx-observer-image, indx-observer-office, indx-observer-text and indx-observer-email. A bare pip install indx therefore resolves no URI at all. It answers 415 and names what it can resolve. Inline base64 sources still work, because they were never fetched. uv run indx capabilities reports the current set under resolvable.

Next steps

• How it works explains planning, execution, and fallback behavior.
• Interfaces & API shows the four public operations and typed failures.
• Extend indx shows how to add readers, specialist parsers, and embedding spaces in your own package.
• Benchmarks states what the current measurements do and do not prove.