Metadata-Version: 2.4
Name: rag-utils-naveen
Version: 0.1.4
Summary: Reusable AI, RAG, and developer workflow utilities.
Author: Naveen
License-Expression: MIT
Keywords: rag,ai,utilities,retrieval,cosine-similarity
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Dynamic: requires-python

# 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

```python
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:

```bash
mkdir -p src/rag_utils tests
```

Install local tooling:

```bash
python -m pip install -r requirements.txt
```

Install the package in editable mode while developing:

```bash
python -m pip install -e .
```

Run the test suite:

```bash
pytest
```

## Build the Package

```bash
python -m build
```

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

## Validate the Distribution

```bash
python -m twine check dist/*
```

## Upload to PyPI

Create environment variables instead of hardcoding the token in files:

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

For TestPyPI first, use:

```bash
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.

```bash
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:

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

print(greet())
```

## Minimal Local Smoke Test

```bash
python hello.py
```
