USE 213 - uv cli invocation

[ghukill]

Purpose and background context

This PR updates how the CLI is invoked inside the Docker container.

A recent PR removed the following lines from the cli.py:

if __name__ == "__main__":  # pragma: no cover
    logger = logging.getLogger("embeddings.main")
    main()

This approach was not ideal to begin with, but allowed invoking the CLI inside the Docker container with python -m embeddings.cli given it would default to this __main__ behavior.

Invoking the Docker container had no output, but was returning a valid zero exit code. This made this very easy to miss; I missed both during code review and working with the CLI locally (likely worth a test case of its own somehow, but out of scope here).

On a positive note, this provided an opportunity to refine how we call click CLI applications with uv.

Locally, we utilize a pattern like uv run embeddings, relying on embeddings being an available script in the uv virtual environment courtesy of this block in pyproject.toml:

[project.scripts]
embeddings = "embeddings.cli:main"

Turns out, we can use this embeddings script / callable in the Docker context as well. The key was adding PYTHONPATH=/app which ensures that the globally installed script /usr/local/bin/embeddings will have a working directory of /app where the embeddings module actually exists.

How can a reviewer manually see the effects of these changes?

1- Build the docker image:

make docker-build

2- Note the updated entrypoint for the Dockerfile:

ENTRYPOINT ["embeddings"]

3- Run the docker container, relying on the entrypoint, and testing the loading of the model:

docker run -it timdex-embeddings:latest --verbose test-model-load

Output:

2026-01-08 15:47:15,307 INFO embeddings.cli.main() line 44: Logger 'root' configured with level=WARNING
2026-01-08 15:47:15,307 INFO embeddings.cli.main() line 45: No Sentry DSN found, exceptions will not be sent to Sentry
2026-01-08 15:47:15,307 INFO embeddings.cli.main() line 46: Running process
2026-01-08 15:47:15,308 INFO embeddings.cli.wrapper() line 97: Embedding class 'OSNeuralSparseDocV3GTE' initialized from model URI 'opensearch-project/opensearch-neural-sparse-encoding-doc-v3-gte'.
2026-01-08 15:47:15,308 INFO embeddings.models.os_neural_sparse_doc_v3_gte.load() line 134: Loading model from: /model
2026-01-08 15:47:15,521 INFO embeddings.models.os_neural_sparse_doc_v3_gte.load() line 147: Model loaded successfully, 0.21s
OK
2026-01-08 15:47:15,522 INFO embeddings.cli._log_command_elapsed_time() line 50: Total time to complete process: 0:00:00.214758

Includes new or updated dependencies?

YES

• picks up new TDA version

Changes expectations for external applications?

YES: Docker image has a valid entrypoint, unblocking some AWS Batch testing

What are the relevant tickets?

• https://mitlibraries.atlassian.net/browse/USE-213

Code review

• Code review best practices are documented here and you are encouraged to have a constructive dialogue with your reviewers about their preferences and expectations.

[jonavellecuerdo]

Hmm, where does the app/ folder come from -- as in is it just a folder uv searches for? 🤔 Asking out of curiosity!

[ghukill]

Hmm, where does the app/ folder come from -- as in is it just a folder uv searches for? 🤔 Asking out of curiosity!

It's created as part of the Dockerfile here: https://github.com/MITLibraries/timdex-embeddings/blob/USE-213-uv-cli-invocation/Dockerfile#L10.

In effect, it's where all files are copied to in th rest of the Dockerfile if not explicitly changed or the current working directory changed.

[jonavellecuerdo]

Ah, thanks for clarifying! When reviewing "Files changed", I sometimes forget the Expand up option exists. 😅 Approved!

[ehanson8]

Good approach to standardize on as our uv practices evolve!