{
  "markdown": "# Cite-Right\n\n[![CI](https://github.com/avaxML/cite-right/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/avaxML/cite-right/actions/workflows/ci.yml)\n![Coverage](./coverage.svg)\n\n**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.\n\n## Core features\n\n- **Document-source linking**: Map each answer span to the exact source substring.\n- **Character-accurate offsets**: `char_start` / `char_end` are ready for UI highlights.\n- **Multi-paragraph support**: Works on RAG-style answers with multiple sentences.\n- **Grounding metrics**: Compute hallucination and groundedness stats.\n\n## How it works (high level)\n\n1. Segment the answer into spans (sentences/clauses).\n2. Find candidate passages in each source and align with Smith-Waterman.\n3. Return citations with absolute character offsets into the original source text.\n\n## Docs\n\n- Site: https://avaxml.github.io/cite-right/\n- Start here: `docs/index.md`\n- MkDocs config: `mkdocs.yml`\n- Coding agents: `openwiki/` (brief in `openwiki/INSTRUCTIONS.md`; generated pages appear after CI runs with `OPENROUTER_API_KEY`). Public site copy lives in `docs/`.\n\n\n## Install\n\nRequirements: Python 3.11+ (Rust is only needed when building from source or if no wheel exists for your platform).\n\n```bash\npip install cite-right\n```\n\nFor the embedding-backed quickstart below, install extras:\n\n```bash\npip install \"cite-right[embeddings,tiktoken]\"\n```\n\nSee `docs/getting-started/` for optional extras (spaCy, embeddings, HuggingFace, tiktoken) and deeper examples.\n\n## Quickstart\n\n```python\nfrom cite_right import SourceDocument, align_citations\nfrom cite_right.core.citation_config import CitationConfig\nfrom cite_right.models.sbert_embedder import SentenceTransformerEmbedder\nfrom cite_right.text.tokenizer_tiktoken import TiktokenTokenizer\n\nquestion = (\n    \"What method is introduced to improve sample efficiency, and what gains does it \"\n    \"report over GRPO and MIPROv2?\"\n)\nanswer = (\n    \"GEPA (Genetic-Pareto) is introduced as a reflective prompt optimizer for compound AI systems. \"\n    \"On Qwen3 8B, GEPA outperforms GRPO by up to 19% while requiring up to 35x fewer rollouts. \"\n    \"It surpasses MIPROv2 with aggregate optimization gains of +14%, more than doubling MIPROv2's +7%.\"\n)\nsources = [\n    SourceDocument(\n        id=\"gepa_intro\",\n        text=(\n            \"To operationalize this, we introduce GEPA (Genetic-Pareto), a reflective prompt \"\n            \"optimizer for compound AI systems that merges textual reflection with multi-objective \"\n            \"evolutionary search.\"\n        ),\n    ),\n    SourceDocument(\n        id=\"grpo_results\",\n        text=(\n            \"Our results show that GEPA demonstrates robust generalization and is highly sample efficient: \"\n            \"on Qwen3 8B, GEPA outperforms GRPO (24,000 rollouts with LoRA) by up to 19% while requiring up to \"\n            \"35x fewer rollouts.\"\n        ),\n    ),\n    SourceDocument(\n        id=\"mipro_results\",\n        text=(\n            \"GEPA surpasses the previous state-of-the-art prompt optimizer, MIPROv2, on every benchmark and model, \"\n            \"obtaining aggregate optimization gains of +14%, more than doubling the gains achieved by MIPROv2 (+7%).\"\n        ),\n    ),\n]\n\nresults = align_citations(\n    answer,\n    sources,\n    config=CitationConfig(top_k=1),\n    embedder=SentenceTransformerEmbedder(\"all-MiniLM-L6-v2\"),\n    tokenizer=TiktokenTokenizer(),\n)\nfor result in results:\n    print(result.answer_span.text, result.status)\n    for citation in result.citations:\n        source_doc = sources[citation.source_index]\n        evidence = source_doc.text[citation.char_start : citation.char_end]\n        print(\" \", citation.source_id, evidence)\n```\n\nWhy embeddings help here:\n\n- The last sentence paraphrases the source, so token overlap alone can fall below the supported threshold.\n- The embedder pulls semantically similar passages into the candidate set; alignment then confirms the exact span and returns precise offsets.\n- Embeddings improve recall, but only alignment-backed matches become citations. High-similarity passages without localized alignment remain retrieval support, not exact evidence.\n\n## High-Precision Configuration\n\nIf 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:\n\n```python\nfrom cite_right import CitationConfig, CitationWeights\n\n# Custom weights optimized to balance alignment and semantic embedding similarity\nhigh_precision_weights = CitationWeights(\n    alignment=1.0,\n    answer_coverage=1.0,\n    evidence_coverage=0.0,\n    lexical=0.5,\n    embedding=0.5,\n)\n\n# High-precision configuration\nhigh_precision_config = CitationConfig(\n    top_k=1,\n    min_alignment_score=0,\n    min_answer_coverage=0.4,\n    supported_answer_coverage=0.6,\n    min_embedding_similarity=0.3,\n    min_final_score=2.6,  # Threshold designed to filter out adversarial and near-miss false positives\n    weights=high_precision_weights,\n)\n```\n\nThis 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.\n\n## Development\n\n```bash\nuv sync --frozen\nuv run maturin develop\nuv run pytest\n```\n\nOptional checks:\n\n```bash\nuv run ruff check .\nuv run ruff format --check .\nuv run pyright\n```\n\n## License\n\nApache-2.0 (see `LICENSE`).\n",
  "bytes": 5774,
  "sha": "eb2b4689403dff3c8438ac54042688f1935b45b4071269e262b569a339549516",
  "repo_slug": "avaxml/cite-right",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_avaxml_cite_right_openwiki_index_md_1b0527a1/readme"
}