Files
Bundle OKF 0.2 · 8 conceitos · avaxML/cite-right
Open source Repository Open in the app JSON README (API)
About
# Files
- [Cite-Right Wiki Quickstart](quickstart.md) - Agent-only routing map for the documentation tree under openwiki/. Indexes the 16 public pages and the 2 agent-only pages under openwiki/testing/, lists the public-vs-agent split, and points new agents at the right entry page (openwiki/index.md for reader questions, openwiki/concepts/how-it-works.md for pipeline work, openwiki/testing/contract-tests.md for Rust parity work).
- [openwiki/](README.md)
# Directories
- [advanced](advanced/)
- [concepts](concepts/)
- [configuration](configuration/)
- [getting-started](getting-started/)
- [integrations](integrations/)
- [testing](testing/)
Details
- Kind
- OKF bundles
- Topic
- Developer tools
- Publisher
- avaxml
- Origin
- okf_github
- Category
- dados
- Version
- 0.2
- Stars
- 2
- Forks
- 2
- Open pull requests
- 6
- Last push
- 2026-09-02T12:45:29Z
- Repository state
- ativo
- Language
- Python
- License
- Apache-2.0
- Added
- 2026-09-08 09:01:12
- Updated
- 2026-09-08 09:01:12
- Origin id
avaxML/cite-right:openwiki/index.md
README
# Cite-Right
[](https://github.com/avaxML/cite-right/actions/workflows/ci.yml)
**Character-accurate citations for AI outputs.** Cite-Right aligns generated answers to source text and returns exact character offsets for highlighting, extraction, and verification. The Python API is the reference implementation, with an optional Rust extension for speed.
## Core features
- **Document-source linking**: Map each answer span to the exact source substring.
- **Character-accurate offsets**: `char_start` / `char_end` are ready for UI highlights.
- **Multi-paragraph support**: Works on RAG-style answers with multiple sentences.
- **Grounding metrics**: Compute hallucination and groundedness stats.
## How it works (high level)
1. Segment the answer into spans (sentences/clauses).
2. Find candidate passages in each source and align with Smith-Waterman.
3. Return citations with absolute character offsets into the original source text.
## Docs
- Site: https://avaxml.github.io/cite-right/
- Start here: `docs/index.md`
- MkDocs config: `mkdocs.yml`
- Coding agents: `openwiki/` (brief in `openwiki/INSTRUCTIONS.md`; generated pages appear after CI runs with `OPENROUTER_API_KEY`). Public site copy lives in `docs/`.
## Install
Requirements: Python 3.11+ (Rust is only needed when building from source or if no wheel exists for your platform).
```bash
pip install cite-right
```
For the embedding-backed quickstart below, install extras:
```bash
pip install "cite-right[embeddings,tiktoken]"
```
See `docs/getting-started/` for optional extras (spaCy, embeddings, HuggingFace, tiktoken) and deeper examples.
## Quickstart
```python
from cite_right import SourceDocument, align_citations
from cite_right.core.citation_config import CitationConfig
from cite_right.models.sbert_embedder import SentenceTransformerEmbedder
from cite_right.text.tokenizer_tiktoken import TiktokenTokenizer
question = (
"What method is introduced to improve sample efficiency, and what gains does it "
"report over GRPO and MIPROv2?"
)
answer = (
"GEPA (Genetic-Pareto) is introduced as a reflective prompt optimizer for compound AI systems. "
"On Qwen3 8B, GEPA outperforms GRPO by up to 19% while requiring up to 35x fewer rollouts. "
"It surpasses MIPROv2 with aggregate optimization gains of +14%, more than doubling MIPROv2's +7%."
)
sources = [
SourceDocument(
id="gepa_intro",
text=(
"To operationalize this, we introduce GEPA (Genetic-Pareto), a reflective prompt "
"optimizer for compound AI systems that merges textual reflection with multi-objective "
"evolutionary search."
),
),
SourceDocument(
id="grpo_results",
text=(
"Our results show that GEPA demonstrates robust generalization and is highly sample efficient: "
"on Qwen3 8B, GEPA outperforms GRPO (24,000 rollouts with LoRA) by up to 19% while requiring up to "
"35x fewer rollouts."
),
),
SourceDocument(
id="mipro_results",
text=(
"GEPA surpasses the previous state-of-the-art prompt optimizer, MIPROv2, on every benchmark and model, "
"obtaining aggregate optimization gains of +14%, more than doubling the gains achieved by MIPROv2 (+7%)."
),
),
]
results = align_citations(
answer,
sources,
config=CitationConfig(top_k=1),
embedder=SentenceTransformerEmbedder("all-MiniLM-L6-v2"),
tokenizer=TiktokenTokenizer(),
)
for result in results:
print(result.answer_span.text, result.status)
for citation in result.citations:
source_doc = sources[citation.source_index]
evidence = source_doc.text[citation.char_start : citation.char_end]
print(" ", citation.source_id, evidence)
```
Why embeddings help here:
- The last sentence paraphrases the source, so token overlap alone can fall below the supported threshold.
- The embedder pulls semantically similar passages into the candidate set; alignment then confirms the exact span and returns precise offsets.
- Embeddings improve recall, but only alignment-backed matches become citations. High-similarity passages without localized alignment remain retrieval support, not exact evidence.
## High-Precision Configuration
If your application requires extremely high precision (e.g., minimizing or completely eliminating false positive citations on adversarial inputs like negations, numerical updates, or swapped entities), we recommend using the benchmarked optimal high-precision configuration:
```python
from cite_right import CitationConfig, CitationWeights
# Custom weights optimized to balance alignment and semantic embedding similarity
high_precision_weights = CitationWeights(
alignment=1.0,
answer_coverage=1.0,
evidence_coverage=0.0,
lexical=0.5,
embedding=0.5,
)
# High-precision configuration
high_precision_config = CitationConfig(
top_k=1,
min_alignment_score=0,
min_answer_coverage=0.4,
supported_answer_coverage=0.6,
min_embedding_similarity=0.3,
min_final_score=2.6, # Threshold designed to filter out adversarial and near-miss false positives
weights=high_precision_weights,
)
```
This configuration was derived using multi-dimensional grid optimization over a rich adversarial RAG dataset and successfully eliminates false positives while preserving robust recall on aligned citations.
## Development
```bash
uv sync --frozen
uv run maturin develop
uv run pytest
```
Optional checks:
```bash
uv run ruff check .
uv run ruff format --check .
uv run pyright
```
## License
Apache-2.0 (see `LICENSE`).