rag-utils-naveen 0.1.8

A simple utility to read and display markdown in notebooks.

rag-utils-naveen

Reusable Python utilities for AI, RAG, and notebook workflows.

The distribution name on PyPI is rag-utils-naveen, while the import name is rag_utils.

Folder Structure

rag-utils/
├── pyproject.toml
├── setup.py
├── requirements.txt
├── README.md
├── hello.py
├── src/
│   └── rag_utils/
│       ├── __init__.py
│       ├── __main__.py
│       ├── _version.py
│       ├── helpers.py
│       ├── retrieval.py
│       └── similarity.py
└── tests/
	└── test_rag_utils.py

Why each file exists

pyproject.toml defines the modern build system and package metadata.

setup.py keeps compatibility with legacy build commands and lets you build with the same source of truth.

requirements.txt is for local developer tooling such as build, twine, and pytest.

src/rag_utils/__init__.py exposes the public API, so users can write from rag_utils import greet.

src/rag_utils/_version.py stores the package version in one place.

src/rag_utils/helpers.py contains general helper functions.

src/rag_utils/similarity.py contains cosine similarity logic.

src/rag_utils/retrieval.py contains simple ranking and retrieval helpers.

tests/test_rag_utils.py verifies the public API before you upload a release.

hello.py is a small local smoke test script.

Public API

from rag_utils import greet, cosine_similarity, rank_documents

print(greet())
print(cosine_similarity([1, 0], [1, 0]))

Local Setup

Create the folder structure from a terminal:

mkdir -p src/rag_utils tests

Install local tooling:

python -m pip install -r requirements.txt

Install the package in editable mode while developing:

python -m pip install -e .

Run the test suite:

pytest

Build the Package

python -m build

This creates dist/*.whl and dist/*.tar.gz.

Validate the Distribution

python -m twine check dist/*

Upload to PyPI

Create environment variables instead of hardcoding the token in files:

export TWINE_USERNAME=__token__
export TWINE_PASSWORD='your-pypi-api-token'
python -m twine upload dist/*

For TestPyPI first, use:

python -m twine upload --repository testpypi dist/*

How to Create a PyPI Account and API Token

1. Go to pypi.org and create an account.
2. Verify your email address.
3. Open your account settings and create an API token.
4. Prefer a project-scoped token for one package, or an account-wide token only if you really need it.
5. Store the token in environment variables or a secret manager, never in source code.

Secure Token Configuration

The safest approach is to set the token only in the shell session you use for uploading.

export TWINE_USERNAME=__token__
export TWINE_PASSWORD='your-pypi-api-token'

If you use a .pypirc file, keep it out of version control and restrict its permissions.

Common Errors and Fixes

InvalidDistribution: usually means the version or metadata in pyproject.toml and setup.py is inconsistent.

403 Forbidden: the API token is wrong, expired, or lacks permission for that project.

File already exists: PyPI does not let you upload the same version twice. Bump the version first.

No module named rag_utils: the import name is rag_utils, but the published distribution name is rag-utils-naveen.

ModuleNotFoundError after local edits: reinstall with python -m pip install -e . or run pytest from the repo root.

How to Update Versions Later

1. Edit src/rag_utils/_version.py and bump the version, for example from 0.1.0 to 0.1.1.
2. Update any release notes in this README if needed.
3. Rebuild the package with python -m build.
4. Check the artifacts with python -m twine check dist/*.
5. Upload the new release with python -m twine upload dist/*.

How to Add New Modules Later

1. Create a new file under src/rag_utils/.
2. Add the public functions or classes there.
3. Export them from src/rag_utils/__init__.py if you want easy imports.
4. Add tests in tests/.
5. Rebuild and publish a new version.

Notebook Install Example

After publishing, install the package in a notebook like this:

!pip install rag-utils-naveen
from rag_utils import greet

print(greet())

Minimal Local Smoke Test

python hello.py