Metadata-Version: 2.4
Name: context-rainbow
Version: 0.1.1
Summary: Color-aware OKF context routing for progressively loading repository knowledge.
Author-email: Karthick Raja M <Karthickrajam18@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/karthyick/context-rainbow
Project-URL: Repository, https://github.com/karthyick/context-rainbow
Project-URL: Issues, https://github.com/karthyick/context-rainbow/issues
Keywords: okf,context,llm,agents,repository,routing,clinotes
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: build>=0.10.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"

# context-rainbow

[![PyPI](https://img.shields.io/pypi/v/context-rainbow)](https://pypi.org/project/context-rainbow/)
[![Python](https://img.shields.io/pypi/pyversions/context-rainbow)](https://pypi.org/project/context-rainbow/)
[![License](https://img.shields.io/pypi/l/context-rainbow)](https://github.com/karthyick/context-rainbow/blob/Development/LICENSE)

Color-aware OKF context routing for progressively loading repository knowledge.

`context-rainbow` keeps an OKF bundle as a small map of a repository. An agent
matches a task against that map, follows the relevant branch, and reads only
the source files that the selected OKF documents point to. Source code is not
duplicated inside the knowledge bundle.

## Why

```text
Task: "Fix refresh token expiry"
                 |
                 v
        Read compact OKF map
                 |
                 v
        Match auth / refresh-token
                 |
                 v
        Follow existing OKF relationships
                 |
                 v
        Read only referenced source files
```

The package adds one routing convention to OKF: a top-level `color` field.
Existing OKF paths and relationships remain the navigation structure.

## Installation

```bash
pip install context-rainbow
```

## OKF color convention

Color belongs directly in the document frontmatter:

```yaml
---
type: Index
title: Authentication
description: Authentication architecture and implementation
tags: [okf, auth]
status: stable
color: amber
relationships:
  - type: applies_to
    target: /repositories/example.md
---
```

Colors identify sibling branches. Direct children of one splitter/index must
have different colors. A color may be reused in a different branch.

Supported colors:

```text
blue · green · amber · red · violet · cyan · pink · orange
```

## Python API

```python
from context_rainbow import ContextRainbow, OkfDocument

documents = [
    OkfDocument(
        id="auth.refresh-token",
        type="code-context",
        title="Refresh token",
        color="red",
        tags=("auth", "refresh", "token"),
        relationships=({"type": "applies_to", "target": "/backend/auth"},),
    ),
]

selected = ContextRainbow(documents).route("Fix refresh token expiry")

for match in selected:
    print(match.document.id, match.reasons)
```

Routing is deterministic and body-free: matching uses document IDs, titles,
tags, and existing relationship targets. The selected document body is loaded
only by the caller after routing.

## Optional Clinotes integration

Clinotes is not a required dependency. If a repository has committed
`.clinotes/INDEX.md` and `detail/*.md` files, the adapter exposes those details
as project-memory documents:

```python
from context_rainbow.sources.clinotes import load_clinotes

project_memory = load_clinotes("C:/work/my-repo")
selected = ContextRainbow(project_memory).route("refresh token decision")
```

This adapter is read-only and filesystem-based. Clinotes remains responsible
for writing decisions and learnings through its own API/MCP server.

## Design boundaries

```text
OKF                  → meaning, architecture, relationships, navigation
Context Rainbow      → color validation and deterministic selection
Repository source    → exact implementation files
Clinotes             → optional project decisions and learnings
```

## Development

```bash
python -m pip install -e ".[dev]"
python -m pytest -q
python -m build
```

## Project

- Repository: https://github.com/karthyick/context-rainbow
- Issues: https://github.com/karthyick/context-rainbow/issues
- Author: Karthick Raja M — Karthickrajam18@gmail.com
- License: MIT
