rag-your-code 0.4.1__py3-none-any.whl

rag_your_code-0.4.1.dist-info/METADATA

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: rag-your-code
+Version: 0.4.1
+Summary: A local, explainable RAG index for codebases and coding agents
+Author: rag-your-code contributors
+License-Expression: MIT
+Keywords: rag,code-search,retrieval,indexing,graphrag,offline,explainable,agent
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Text Processing :: Indexing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "dev"
+Dynamic: license-file
+
+# RAG Your Code
+
+`rag-your-code` is the **R** in RAG: a local, explainable retrieval index over a
+codebase. The generation half stays in your agent. It scans functions, methods
+and classes across Python and fourteen other languages, assigns stable serial
+numbers, and answers queries with a file, a line range, the terms that matched,
+and the source itself.
+
+No network calls and no runtime dependencies, by design rather than by
+omission — it is meant to run over a private repository on a machine with the
+network turned off, and to produce an index you can read.
+
+## What the embedding does, and what it does not
+
+This matters more than any feature list, so it is stated up front rather than
+in a footnote.
+
+The embedder is a **signed feature hash**: it hashes tokens into 384 buckets.
+Cosine similarity over those vectors is therefore a normalised measure of
+*token overlap*, and it carries no semantics whatever:
+
+| pair | cosine |
+|---|---|
+| `retry failed card charge` vs itself | 1.0000 |
+| `sum two numbers` vs `add a pair of integers` | **0.0000** |
+| `计算两个数的和` vs `sum two numbers` | **0.0000** |
+| `sum two numbers` vs `delete the user database table` | 0.0000 |
+
+A trained embedding model scores row 2 around 0.8. Here a synonym pair and an
+unrelated pair are indistinguishable, because zero shared tokens is zero either
+way.
+
+Retrieval works anyway, because **identifiers and docstrings are already
+natural language**: `retry_charge` contains the words *retry* and *charge*. But
+it reaches only concepts someone wrote down. Two mechanisms close the rest of
+the gap, and neither of them is a model:
+
+- **Your agent rewrites the query.** It has the conversation; turning "重试扣款"
+  into `retry charge payment gateway` costs it nothing.
+- **Your agent writes the descriptions** (see below), which puts the missing
+  vocabulary into the index once instead of into every query.
+
+## Quick start
+
+```bash
+# Not on PyPI. Take the wheel from the latest release, or install the source:
+#   https://github.com/skymanbp/rag-your-code/releases
+pip install ./rag_your_code-0.4.0-py3-none-any.whl
+#   ... or, from a clone:  python -m pip install -e .
+
+rag-your-code index .
+rag-your-code search "where are HTTP retries handled" --json
+rag-your-code search "what calls the retry handler" --graph --hops 1 --json
+rag-your-code annotate
+```
+
+The index and annotations are written under `.rag-your-code/`; source files are
+never modified. Use `--json` when feeding results to an agent.
+
+For a large repository prefer `rag-your-code index . --compact`. Later
+`index` runs and the agent's `refresh` reuse unchanged files and preserve
+global serials; `--full` discards the cache.
+
+## Agent-authored descriptions
+
+Every unit carries a description, and that description is indexed. By default
+it is generated without a model: the identifier humanised, the parameter and
+callee names listed, the docstring appended. That introduces no vocabulary the
+source did not already contain, which is exactly why retrieval cannot reach a
+concept nobody wrote down.
+
+The agent already reading this index can supply those words:
+
+```bash
+rag-your-code describe status                 # coverage, and what is pending
+rag-your-code describe export --limit 20      # a batch, with source and a brief
+rag-your-code describe import written.json    # store what the agent wrote
+rag-your-code index .                         # apply it
+```
+
+or, in the JSON-lines protocol, `describe_pending` and `describe_put` — which
+take effect in the same session, without a refresh.
+
+Measured on the fixture repository, replacing one generated sentence with an
+agent-written bilingual one:
+
+| query | generated description | agent description |
+|---|---|---|
+| `exponential backoff` | no lexical evidence | **#1**, 1.0172 |
+| `double billing safety` | no lexical evidence | **#1**, 0.3404 |
+| `支付网关超时` | no lexical evidence | **#1**, 0.8632 |
+
+**What this is:** it moves the semantic work from query time to index time.
+Matching stays lexical — a description saying `retry` still cannot answer a
+query saying `resend` unless the description also says so. It is LLM-authored
+keyword expansion, and its reach is bounded by how many ways of saying the
+thing the agent thought to write down.
+
+Descriptions live in `rag-your-code.descriptions.json` at the repository root
+and are meant to be committed, so one person's pass benefits everyone who
+clones. Each is keyed by unit id **and a digest of the unit's source**: when
+the code changes the description is not applied, the unit returns to the
+pending queue, and retrieval falls back to the generated sentence. A
+description that outlived its code would be a confident wrong answer, which is
+the one thing this index is built not to give.
+
+## Configuration
+
+Twelve settings live in `rag-your-code.toml` at the repository root:
+
+```bash
+rag-your-code config init                       # a commented file, all defaults
+rag-your-code config list                       # effective values and their source
+rag-your-code config set index.ignore '["vendor", "generated"]'
+rag-your-code config set search.vector_weight 0.25
+```
+
+Resolution is CLI flag > file > built-in default. There is no environment
+layer: an index is an artifact of a repository, not of a shell.
+
+| section | settings |
+|---|---|
+| `[index]` | `ignore`, `suffixes`, `max_file_bytes` |
+| `[embedding]` | `dimensions` |
+| `[search]` | `vector_weight`, `limit`, `max_chars` |
+| `[agent]` | `max_open_bytes`, `max_open_chars` |
+| `[describe]` | `languages`, `batch`, `max_chars` |
+
+An unknown key or an out-of-range value is an error, not a shrug — a setting
+that is silently dropped is indistinguishable from one that had no effect.
+`index.suffixes` may only name suffixes the parser has rules for, because a
+suffix it cannot read is walked, parsed to nothing, and reported as a clean
+index of zero units.
+
+The four settings under `[index]` and `[embedding]` determine what an index
+*contains*, so a digest of them is recorded in the index and a change forces a
+full rebuild. The rest take effect immediately and never invalidate anything.
+
+## Agent protocol
+
+`rag-your-code agent --root PATH` reads JSON lines from stdin and writes JSON
+lines to stdout:
+
+```json
+{"action":"search","query":"database transaction rollback","limit":5}
+{"action":"research","query":"trace payment retry behavior","max_steps":2}
+{"action":"neighbors","id":"payments.py:4:retry_charge","hops":1}
+{"action":"open","path":"payments.py","start_line":1,"end_line":80}
+{"action":"describe_pending","limit":20}
+{"action":"describe_put","descriptions":[{"id":"payments.py:4:retry_charge","text":"..."}]}
+{"action":"refresh"}
+{"action":"stats"}
+```
+
+No single request can end the session: numeric fields saturate at their bounds,
+`open` is bounded in both lines and bytes, and anything unanticipated is
+reported in-band with its exception type. Streams are pinned to UTF-8 rather
+than following the OS codepage.
+
+The bundled Claude plugin skill documents the recommended workflow: index at
+session start, retrieve narrowly, inspect returned source, describe what is
+pending, and re-index after substantial changes.
+
+## Design notes
+
+- Python uses the standard-library AST, so nested functions, methods, calls,
+  imports, signatures and source line ranges are precise.
+- Other languages use a line-oriented declaration scanner: a per-language rule
+  table matched one line at a time, then a span closer (brace balance, Ruby's
+  `end`, or the next declaration). Because a pattern never sees a second line,
+  the reported line number is the scanner's own loop index and cannot drift,
+  and a declaration cannot swallow the ones after it. Fourteen languages are
+  covered and graded against source-controlled fixtures in
+  `tests/fixtures/languages/`; `SPEC.md` there states what counts as a unit.
+- Retrieval combines lexical overlap and cosine similarity. Every result is
+  explainable: you can read why it matched.
+- Schema 2 supports incremental per-file reuse, repository-global serials,
+  graph edges, and optional compact float32 vector storage (`index --compact`).
+- GRAG expands bounded `calls`/`imports`/`contains` neighbours with edge-path
+  evidence, and omits an edge it cannot resolve rather than guessing one. ARAG
+  exposes bounded, observable `research`, `neighbors`, `open` and `refresh`.
+- The generated `RAG[00001] ...` comments live in a sidecar Markdown file,
+  which avoids rewriting your code while preserving the numbered layer that
+  gets embedded.
+
+## What lives where
+
+| path | authored or generated | committed |
+|---|---|---|
+| `rag-your-code.toml` | authored | yes |
+| `rag-your-code.descriptions.json` | authored by your agent | yes |
+| `.rag-your-code/` (index, vectors, annotations) | generated | no |
+
+Nothing authored lives under `.rag-your-code/`: that directory is what people
+delete to clear the cache.
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+pytest -q
+```
+
+No runtime dependencies; `pytest` and, below Python 3.11, `tomli` come from the
+`dev` extra. CI covers Python 3.10 through 3.13 on Linux and Windows and
+installs the built wheel into a clean environment to check that the workflow
+the bundled skill documents actually runs from a published artifact. See
+[CONTRIBUTING.md](CONTRIBUTING.md) for what the golden set and the language
+fixtures are protecting, and [docs/ROADMAP.md](docs/ROADMAP.md) for what is
+deliberately not here yet.

rag_your_code-0.4.1.dist-info/RECORD

@@ -0,0 +1,19 @@
+rag_your_code-0.4.1.dist-info/licenses/LICENSE,sha256=LtQrRkCo2Rbvy8DWxjJGOgaa9VcP3jK4EjqbaGUkJgE,1083
+ragyourcode/__init__.py,sha256=6k5MyVoot5TtRPrCDmPDExED9TRURV8Gv4mUsViEQOo,150
+ragyourcode/agentic.py,sha256=5kucZi36a125_TRfQ9LoMIXNBFPhYmQ7ptpUAJ2Bh0c,2487
+ragyourcode/annotate.py,sha256=IGWCwp886dSXIjZt-o45dNkBJdITLnb9dYteVOdr7Hg,1291
+ragyourcode/cli.py,sha256=oiuqPtfOVoG3JYAMzT7Bvvi6Ophq9SNr8B9d2khmFSQ,29249
+ragyourcode/config.py,sha256=6dJt729dOPo_7Qxb2W6DNe_Jr7wDXf4xDffNuHTG1Eo,23099
+ragyourcode/descriptions.py,sha256=8QEUHgZL-0loNYjRxX0ALPF5i57uy6sAA_CGdiZfFMQ,11133
+ragyourcode/embeddings.py,sha256=rEoi6YhLV_GIYXBaLVDT5mHogdfrAHKzbRwhFoaNuNc,2041
+ragyourcode/graph.py,sha256=GA4fDiGhyphkAmQqdjzg4PoJOf_U6v58CtO-1d2Cn0E,8758
+ragyourcode/indexer.py,sha256=8kqIbtqPdPpcjzi3T2_0zbmEiu-Fbuk-_bNNUgYxoGg,17939
+ragyourcode/models.py,sha256=GnhgHE7X2I-75ZuPYhb2W8drzzUgo1sHAeUq1vLnBcU,2564
+ragyourcode/parser.py,sha256=1JX6j-UvN9qj3Ygxq6NjNIsQntCs_n48ayi32XPjDxo,22305
+ragyourcode/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ragyourcode/search.py,sha256=hXEnC8BgPChXQQMsk-LepY5R4WVAuPNo5dSXX3AU4eU,6225
+rag_your_code-0.4.1.dist-info/METADATA,sha256=pp2-MT3ccYRNBtetlsbt_cRki2GmMZusJ_zi4541SOg,10531
+rag_your_code-0.4.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+rag_your_code-0.4.1.dist-info/entry_points.txt,sha256=r9SkpQf07eEcLSKcKS0uP1pAec-EbwCBsJ9Fgt9gh14,55
+rag_your_code-0.4.1.dist-info/top_level.txt,sha256=Q7HCsNIpxL4UsLM8ZjfPvkCmBbYb2SuVTKD1u0FYKEw,12
+rag_your_code-0.4.1.dist-info/RECORD,,

rag_your_code-0.4.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

rag_your_code-0.4.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+rag-your-code = ragyourcode.cli:main

rag_your_code-0.4.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rag-your-code contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rag_your_code-0.4.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+ragyourcode

ragyourcode/__init__.py

@@ -0,0 +1,6 @@
+"""Local codebase RAG for coding agents."""
+
+from .models import CodeUnit, SearchResult
+
+__all__ = ["CodeUnit", "SearchResult"]
+__version__ = "0.4.1"

ragyourcode/agentic.py

@@ -0,0 +1,55 @@
+"""Bounded, observable agentic retrieval (ARAG) orchestration."""
+
+from __future__ import annotations
+
+from .graph import CodeGraph, graph_search
+from .models import CodeUnit, SearchResult
+from .search import DEFAULT_VECTOR_WEIGHT, SearchIndex, search
+
+
+def _result_ids(results: list[SearchResult]) -> set[str]:
+    return {result.unit.id for result in results}
+
+
+def _serialize(results: list[SearchResult]) -> list[dict]:
+    return [result.to_dict() for result in results]
+
+
+def research(
+    units: list[CodeUnit],
+    query: str,
+    limit: int = 8,
+    hops: int = 1,
+    max_steps: int = 2,
+    confidence_threshold: float = 0.8,
+    graph: CodeGraph | None = None,
+    search_index: SearchIndex | None = None,
+    vector_weight: float = DEFAULT_VECTOR_WEIGHT,
+) -> dict:
+    """Run at most two deterministic retrieval steps and explain the stop.
+
+    This is deliberately bounded. A future LLM planner can replace the query
+    proposal, but the budget, evidence format, and no-progress stop remain
+    stable safety contracts.
+    """
+    max_steps = min(2, max(1, max_steps))
+    steps: list[dict] = []
+    initial = search(units, query, max(limit, 1), search_index=search_index, vector_weight=vector_weight)
+    steps.append({"action": "search", "query": query, "results": _serialize(initial)})
+    best_score = initial[0].score if initial else 0.0
+    if not initial:
+        return {"query": query, "results": [], "steps": steps, "stop_reason": "no_results"}
+    if max_steps == 1 or (best_score >= confidence_threshold and initial[0].matched_terms):
+        return {"query": query, "results": _serialize(initial[:limit]), "steps": steps, "stop_reason": "high_confidence"}
+
+    expanded = graph_search(units, query, limit=max(limit * 2, 8), hops=hops, graph=graph, search_index=search_index, vector_weight=vector_weight)
+    steps.append({"action": "graph_expand", "hops": hops, "results": _serialize(expanded[:limit])})
+    merged = {result.unit.id: result for result in initial}
+    for result in expanded:
+        current = merged.get(result.unit.id)
+        if current is None or result.score > current.score:
+            merged[result.unit.id] = result
+    final = sorted(merged.values(), key=lambda result: (-result.score, result.unit.id))[:limit]
+    new_ids = _result_ids(final) - _result_ids(initial)
+    reason = "new_graph_evidence" if new_ids else "no_new_evidence"
+    return {"query": query, "results": _serialize(final), "steps": steps, "stop_reason": reason}

ragyourcode/annotate.py

@@ -0,0 +1,35 @@
+"""Generate stable, descriptive comments for code units without an LLM."""
+
+from __future__ import annotations
+
+import ast
+import re
+
+
+def _humanize(name: str) -> str:
+    words = re.sub(r"([a-z0-9])([A-Z])", r"\1 \2", name).replace("_", " ").split()
+    return " ".join(words).strip().lower() or "anonymous unit"
+
+
+def describe_python(node: ast.AST, source: str, calls: list[str], imports: list[str]) -> str:
+    name = getattr(node, "name", "anonymous")
+    kind = "method" if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) else "class"
+    args = []
+    if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+        args = [arg.arg for arg in node.args.args]
+    pieces = [f"This {kind} {_humanize(name)}"]
+    if args:
+        pieces.append("accepts " + ", ".join(args))
+    if calls:
+        pieces.append("and calls " + ", ".join(calls[:8]))
+    if imports:
+        pieces.append("using " + ", ".join(imports[:8]))
+    doc = ast.get_docstring(node)
+    if doc:
+        pieces.append("Documented intent: " + " ".join(doc.split()))
+    return ". ".join(pieces) + "."
+
+
+def comment_for(description: str, serial: int, unit_id: str) -> str:
+    """A language-neutral comment payload suitable for sidecar files."""
+    return f"RAG[{serial:05d}] {unit_id}: {description}"