Metadata-Version: 2.4
Name: rylox
Version: 0.0.2
Summary: Local, deterministic repository context engine — turns a codebase + task into a token-budgeted markdown context package.
Author: Darsh Vithlani
License: Apache-2.0
License-File: LICENSE
Keywords: code-search,context-engine,llm-tooling,rag,retrieval
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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.13,>=3.9
Requires-Dist: faiss-cpu<2.0,>=1.7.4
Requires-Dist: numpy<2.1
Requires-Dist: onnxruntime<2.0,>=1.17
Requires-Dist: rank-bm25<0.3,>=0.2.2
Requires-Dist: sentence-transformers<4.0,>=3.2
Requires-Dist: tiktoken<1.0,>=0.7
Requires-Dist: tomli<3.0,>=2.0; python_version < '3.11'
Requires-Dist: tree-sitter-python<0.22,>=0.21
Requires-Dist: tree-sitter<0.22,>=0.21
Requires-Dist: typer<1.0,>=0.12
Provides-Extra: dev
Requires-Dist: mypy<2.0,>=1.10; extra == 'dev'
Requires-Dist: pytest-cov<6.0,>=5.0; extra == 'dev'
Requires-Dist: pytest<9.0,>=8.0; extra == 'dev'
Requires-Dist: ruff<1.0,>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# Rylox

**Rylox** is a fast, local repository context engine for Python codebases.

It analyzes your repository, builds a structured semantic index, and
retrieves relationship-aware, token-budgeted context that can be pasted
into any large language model.

Unlike keyword search or sending entire files to an LLM, Rylox understands
the structure of your codebase — functions, methods, classes, and how they
reference each other — and selects only the code relevant to your question.
Indexing and retrieval run entirely on your machine: no API keys, no cloud
services, no vendor lock-in. The only network access Rylox ever makes is a
one-time download of its local embedding model on first use; after that,
everything is fully offline.

```bash
rylox index
rylox context "How does authentication work?" --max-tokens 20000
```

The output is a structured Markdown document — query, entry points,
execution flow, included files, and the actual relevant code — sized to
fit within the token budget you set, ready to paste into ChatGPT, Claude,
Gemini, Codex, or any other LLM.

---

## Why Rylox?

Large repositories quickly exceed an LLM's context window. Keyword search
often retrieves unrelated files; pasting whole files wastes tokens on
irrelevant code; cloud-based embedding services require API keys, cost
money per query, and send your code off your machine.

Rylox instead parses your repository's actual structure, combines dense
(embedding-based) and sparse (keyword-based) retrieval, follows one hop of
real call/reference relationships from the best matches, and assembles the
result deterministically within a token budget — all locally.

---

## Features

- Tree-sitter powered Python parsing
- Semantic chunking at the function, method, and class level, including
  decorators and `async def`
- Incremental indexing using SHA-256 content hashing — only changed files
  are re-parsed and re-embedded on subsequent runs
- Hybrid retrieval: dense (local sentence-transformer embeddings + FAISS)
  and sparse (BM25) search, combined via Reciprocal Rank Fusion
- One-hop relationship expansion (callers, callees, constructor/decorator
  usage) from the top-ranked matches
- Deterministic, token-budgeted context assembly — a chunk that doesn't
  fit the budget is skipped whole, never truncated mid-body
- Structured Markdown output with a fixed section layout
- Persistent on-disk cache for both the parsed index and computed
  embeddings
- `.gitignore`-aware and configurable ignore patterns, with a configurable
  per-file size ceiling
- `rylox doctor` for diagnosing your local environment and repository
  cache state
- Offline after first run — the only network call is the initial,
  one-time embedding model download
- Cross-platform (Linux, macOS, Windows)

---

## Example

Index a repository:

```bash
rylox index
```

Generate context for an LLM:

```bash
rylox context "How does authentication work?" --max-tokens 20000
```

Rylox writes a Markdown file containing the most relevant parts of the
repository for that question, within the requested token budget.

---

## Current status

Rylox is functional end to end — `index`, `context`, `clean`, and `doctor`
all work as real commands, not stubs. That said, this is an early release
(v0.0.2, pre-1.0), and retrieval *quality* is actively being improved:
running Rylox against real open-source repositories has already surfaced
and fixed real bugs in how relationships between code are detected (see
[`KNOWN_LIMITATIONS.md`](KNOWN_LIMITATIONS.md) for specifics and current
known gaps). If you hit a case where retrieval picks the wrong code or
misses something obviously relevant, that's useful signal — please open an
issue.

---

## Philosophy

**Offline first.** Repository indexing and retrieval never require a
network connection after the one-time initial model download.

**Vendor independent.** The generated context is plain Markdown — it works
with any language model, not a specific provider.

**Deterministic retrieval.** Given the same index and query, output
ordering is reproducible — driven by repository structure and fusion
scoring, not opaque or randomized ranking.

---

## Installation

Install the latest release from PyPI:

```bash
pip install rylox
```
Upgrade existing installation:
```bash
pip install --upgrade rylox
```
Contributing or running the test suite:

```bash
pip install -e ".[dev]"
pytest
```

---

## Supported language

- Python (3.9–3.12)

Additional language support is a future goal via Tree-sitter's grammar
ecosystem, not yet implemented.

---

## License

Rylox is licensed under the Apache License 2.0. See
[`LICENSE`](LICENSE) for details.