ragfabric 0.3.1__tar.gz

ragfabric-0.3.1/.gitignore

@@ -0,0 +1,49 @@
+# Environment
+.env
+.env.*
+!.env.example
+
+# local configuration (copy of ragfabric.example.yaml)
+ragfabric.yaml
+
+# OS
+.DS_Store
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+venv/
+.pytest_cache/
+*.egg-info/
+
+# Local data / databases
+*.db
+backend/data/uploads/
+
+# Node / Angular
+node_modules/
+dist/
+.angular/
+npm-debug.log*
+
+# Editors
+.idea/
+.vscode/
+
+# Frontend test artifacts
+coverage/
+out-tsc/
+
+# Local planning notes and scratch (never committed)
+MEMORY*.md
+*.local.md
+.notes/
+.scratch/
+
+# Secrets and keys (belt and braces; .env already excluded above)
+*.pem
+*.key
+*.p12
+secrets/

ragfabric-0.3.1/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.5
+Name: ragfabric
+Version: 0.3.1
+Summary: RagFabric: self hosted, measurement first RAG platform. Installs the engine, the API and the ragfabric command.
+Project-URL: Homepage, https://github.com/ranjan-del/ragfabric
+Project-URL: Repository, https://github.com/ranjan-del/ragfabric
+Project-URL: Documentation, https://github.com/ranjan-del/ragfabric/tree/main/docs
+Project-URL: Changelog, https://github.com/ranjan-del/ragfabric/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/ranjan-del/ragfabric/issues
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: <3.14,>=3.13
+Requires-Dist: ragfabric-core==0.3.1
+Requires-Dist: ragfabric-sdk==0.3.1
+Requires-Dist: ragfabric-server==0.3.1
+Requires-Dist: typer>=0.27
+Provides-Extra: anthropic
+Requires-Dist: ragfabric-core[anthropic]==0.3.1; extra == 'anthropic'
+Provides-Extra: bm25
+Requires-Dist: ragfabric-core[bm25]==0.3.1; extra == 'bm25'
+Provides-Extra: chroma
+Requires-Dist: ragfabric-core[chroma]==0.3.1; extra == 'chroma'
+Provides-Extra: openai
+Requires-Dist: ragfabric-core[openai]==0.3.1; extra == 'openai'
+Provides-Extra: rerank
+Requires-Dist: ragfabric-core[rerank]==0.3.1; extra == 'rerank'
+Description-Content-Type: text/markdown
+
+# ragfabric
+
+`pip install ragfabric` installs the engine, the HTTP API and the `ragfabric` command. See the repository README.

ragfabric-0.3.1/README.md

@@ -0,0 +1,3 @@
+# ragfabric
+
+`pip install ragfabric` installs the engine, the HTTP API and the `ragfabric` command. See the repository README.

ragfabric-0.3.1/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "ragfabric"
+version = "0.3.1"
+description = "RagFabric: self hosted, measurement first RAG platform. Installs the engine, the API and the ragfabric command."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.13,<3.14"
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.13",
+  "Environment :: Console",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+  "ragfabric-core==0.3.1",
+  "ragfabric-server==0.3.1",
+  "ragfabric-sdk==0.3.1",
+  "typer>=0.27",
+]
+
+[project.optional-dependencies]
+openai = ["ragfabric-core[openai]==0.3.1"]
+anthropic = ["ragfabric-core[anthropic]==0.3.1"]
+chroma = ["ragfabric-core[chroma]==0.3.1"]
+bm25 = ["ragfabric-core[bm25]==0.3.1"]
+rerank = ["ragfabric-core[rerank]==0.3.1"]
+
+[project.scripts]
+ragfabric = "ragfabric_cli.main:app"
+
+[project.urls]
+Homepage = "https://github.com/ranjan-del/ragfabric"
+Repository = "https://github.com/ranjan-del/ragfabric"
+Documentation = "https://github.com/ranjan-del/ragfabric/tree/main/docs"
+Changelog = "https://github.com/ranjan-del/ragfabric/blob/main/CHANGELOG.md"
+Issues = "https://github.com/ranjan-del/ragfabric/issues"
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ragfabric_cli"]

ragfabric-0.3.1/src/ragfabric_cli/__init__.py

@@ -0,0 +1 @@
+"""RagFabric command line."""

ragfabric-0.3.1/src/ragfabric_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""Sub commands of the ragfabric CLI."""

ragfabric-0.3.1/src/ragfabric_cli/commands/access.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+import typer
+
+from ragfabric_cli.commands.common import collection_by_name, session, user_by_email
+from ragfabric_core.auth import service
+from ragfabric_core.auth.api_keys import create_api_key
+from ragfabric_core.models.access import ApiKey, CollectionGrant, Group
+from ragfabric_core.models.document import Collection
+
+groups_app = typer.Typer(help="Groups and membership.")
+grants_app = typer.Typer(help="Collection grants.")
+keys_app = typer.Typer(help="API keys.")
+
+
+def _group(db, name: str) -> Group:
+    group = db.query(Group).filter(Group.name == name).first()
+    if group is None:
+        typer.echo(f"group not found: {name}")
+        raise typer.Exit(code=1)
+    return group
+
+
+@groups_app.command("create")
+def create_group(name: str, description: str = typer.Option("")) -> None:
+    with session() as db:
+        if db.query(Group).filter(Group.name == name).first() is not None:
+            typer.echo(f"group already exists: {name}")
+            raise typer.Exit(code=1)
+        service.create_group(db, name, description)
+        db.commit()
+    typer.echo(f"created group {name}")
+
+
+@groups_app.command("add-member")
+def add_member(group_name: str, email: str) -> None:
+    with session() as db:
+        group = _group(db, group_name)
+        user = user_by_email(db, email)
+        service.add_member(db, group.id, user.id)
+        db.commit()
+    typer.echo(f"added {email} to {group_name}")
+
+
+@groups_app.command("list")
+def list_groups() -> None:
+    with session() as db:
+        for g in db.query(Group).order_by(Group.name).all():
+            members = service_members(db, g.id)
+            typer.echo(f"{g.id}\t{g.name}\t{members} member(s)")
+
+
+def service_members(db, group_id: int) -> int:
+    from ragfabric_core.models.access import GroupMember
+
+    return db.query(GroupMember).filter(GroupMember.group_id == group_id).count()
+
+
+@grants_app.command("add")
+def add_grant(
+    group: str = typer.Option(...),
+    collection: str = typer.Option(...),
+    permission: str = typer.Option("read"),
+) -> None:
+    with session() as db:
+        g = _group(db, group)
+        c = collection_by_name(db, collection)
+        try:
+            service.grant_collection(db, g.id, c.id, permission)
+        except ValueError as exc:
+            typer.echo(str(exc))
+            raise typer.Exit(code=1) from None
+        db.commit()
+    typer.echo(f"granted {permission} on {collection} to {group}")
+
+
+@grants_app.command("list")
+def list_grants() -> None:
+    with session() as db:
+        rows = (
+            db.query(CollectionGrant, Group.name, Collection.name)
+            .join(Group, Group.id == CollectionGrant.group_id)
+            .join(Collection, Collection.id == CollectionGrant.collection_id)
+            .all()
+        )
+        for grant, group_name, collection_name in rows:
+            typer.echo(f"{grant.id}\t{group_name}\t{collection_name}\t{grant.permission}")
+
+
+@keys_app.command("create")
+def create_key(
+    name: str = typer.Option(...),
+    user: str = typer.Option(...),
+    collection: list[str] = typer.Option([], "--collection"),
+    strategy: list[str] = typer.Option([], "--strategy"),
+    rate_limit: int | None = typer.Option(
+        None,
+        "--rate-limit",
+        help="Requests/minute; defaults to limits.rate_limit_per_minute in ragfabric.yaml.",
+    ),
+) -> None:
+    with session() as db:
+        owner = user_by_email(db, user)
+        collection_ids = [collection_by_name(db, c).id for c in collection]
+        key, plaintext = create_api_key(
+            db,
+            name=name,
+            user_id=owner.id,
+            collection_ids=collection_ids,
+            strategies=strategy,
+            rate_limit_per_minute=rate_limit,
+        )
+        db.commit()
+        typer.echo(f"created key {key.id} ({name}) for {user}")
+    typer.echo("store this now, it is not shown again:")
+    typer.echo(plaintext)
+
+
+@keys_app.command("list")
+def list_keys() -> None:
+    with session() as db:
+        for k in db.query(ApiKey).order_by(ApiKey.id).all():
+            typer.echo(
+                f"{k.id}\t{k.name}\t{k.key_prefix}...\t{'active' if k.is_active else 'revoked'}\tlimit {k.rate_limit_per_minute}/min"
+            )
+
+
+@keys_app.command("revoke")
+def revoke_key(key_id: int) -> None:
+    with session() as db:
+        key = db.get(ApiKey, key_id)
+        if key is None:
+            typer.echo(f"key not found: {key_id}")
+            raise typer.Exit(code=1)
+        key.is_active = False
+        db.commit()
+    typer.echo(f"revoked key {key_id}")

ragfabric-0.3.1/src/ragfabric_cli/commands/ask.py

@@ -0,0 +1,197 @@
+"""ragfabric ask: ask a running RagFabric server a question.
+
+Goes through the SDK over HTTP rather than calling core in process: the
+normal case is a remote server, and a second in process code path would
+drift from what API users experience. The cost is that this command needs a
+running server to talk to; the help text says so.
+"""
+
+from __future__ import annotations
+
+import os
+from enum import StrEnum
+
+import typer
+
+from ragfabric_sdk import Client
+from ragfabric_sdk.errors import RagFabricError
+
+DEFAULT_URL = "http://localhost:8000"
+
+
+class Strategy(StrEnum):
+    """Retrieval strategies this command can ask the server for.
+
+    An Enum rather than a free string so Typer refuses an unknown name while
+    parsing, before the command body runs. A typo then costs nothing: no
+    request leaves the machine, no embedding call is spent, and the error
+    names the valid choices instead of arriving as a 422 from the server.
+    The members mirror the server's own Literal in schemas/search.py; the
+    server stays the authority and still validates what it is sent.
+    """
+
+    traditional = "traditional"
+    vectorless = "vectorless"
+    agentic = "agentic"
+    graph = "graph"
+
+
+def ask(
+    question: str = typer.Argument(..., help="The question to ask."),
+    url: str = typer.Option(
+        None, "--url", help=f"Server URL (env RAGFABRIC_URL, default {DEFAULT_URL})."
+    ),
+    token: str = typer.Option(None, "--token", help="JWT bearer token (env RAGFABRIC_TOKEN)."),
+    api_key: str = typer.Option(None, "--api-key", help="rf_ API key (env RAGFABRIC_API_KEY)."),
+    top_k: int = typer.Option(8, "--top-k", min=1, max=50, help="Chunks to retrieve."),
+    threshold: float = typer.Option(
+        0.0, "--threshold", min=0.0, max=1.0, help="Similarity threshold."
+    ),
+    collection: int = typer.Option(None, "--collection", help="Collection id to search."),
+    strategy: Strategy = typer.Option(
+        Strategy.traditional,
+        "--strategy",
+        help=(
+            "Retrieval strategy. traditional embeds the question and searches the "
+            "vector index; vectorless ranks with BM25 fused with ts_rank_cd and "
+            "never calls an embedding model; agentic splits the question into "
+            "parts, retrieves per part, and repairs or abandons the parts it "
+            "cannot answer, reporting which those were; graph walks the knowledge "
+            "graph from the entities the question names and prints the relationships "
+            "it walked and any relationship claims the citation contract dropped."
+        ),
+    ),
+    no_stream: bool = typer.Option(
+        False, "--no-stream", help="Wait for the whole answer instead of streaming tokens."
+    ),
+    as_json: bool = typer.Option(
+        False, "--json", help="Print the whole answer payload as JSON (implies --no-stream)."
+    ),
+) -> None:
+    """Ask a question and print the cited answer.
+
+    Needs a running RagFabric server: this command talks to it over HTTP
+    through the RagFabric SDK, it does not answer the question locally.
+    Streamed stdout can contain a stale, superseded draft ahead of the
+    corrected answer (bytes already printed cannot be recalled); a machine
+    consumer should use --json or --no-stream instead of parsing the stream.
+    """
+    url = url or os.environ.get("RAGFABRIC_URL") or DEFAULT_URL
+    token = token or os.environ.get("RAGFABRIC_TOKEN")
+    api_key = api_key or os.environ.get("RAGFABRIC_API_KEY")
+    if not token and not api_key:
+        typer.echo(
+            "no credentials: pass --token or --api-key, or set RAGFABRIC_TOKEN "
+            "or RAGFABRIC_API_KEY",
+            err=True,
+        )
+        raise typer.Exit(2)
+
+    params: dict[str, object] = {
+        "top_k": top_k,
+        "similarity_threshold": threshold,
+        "strategy": strategy.value,
+    }
+    if collection is not None:
+        params["collection_id"] = collection
+
+    client = Client(url, token=token, api_key=api_key)
+    try:
+        if as_json or no_stream:
+            answer = client.ask(question, **params)
+            if as_json:
+                typer.echo(answer.model_dump_json(indent=2))
+            else:
+                typer.echo(answer.answer)
+                typer.echo("")
+                _print_sources([citation.model_dump() for citation in answer.citations])
+                _print_graph(
+                    answer.subgraph.model_dump() if answer.subgraph is not None else None,
+                    [claim.model_dump() for claim in answer.dropped_relationship_claims],
+                )
+            return
+
+        citations: list[dict] = []
+        subgraph: dict | None = None
+        dropped_relationship_claims: list[dict] = []
+        run_id = None
+        latency_ms = None
+        for event in client.ask_stream(question, **params):
+            if event.event == "retrieval":
+                subgraph = event.data.get("subgraph")
+            elif event.event == "token":
+                typer.echo(event.data.get("text", ""), nl=False)
+            elif event.event == "superseded":
+                # The caller already saw the rejected tokens printed above,
+                # and there is no way to un-print a terminal: say so on
+                # stderr (never mixed into a piped stdout file) and then put
+                # the full corrected answer on stdout so a script reading
+                # stdout still ends up with the complete, correct text, even
+                # though it is preceded by the stale draft.
+                typer.echo(
+                    "\nnotice: the streamed answer above failed the citation "
+                    "contract and was corrected; the corrected answer follows.",
+                    err=True,
+                )
+                typer.echo("\n")
+                typer.echo(event.data.get("text", ""), nl=False)
+                dropped_relationship_claims = event.data.get("dropped_relationship_claims", [])
+            elif event.event == "citations":
+                citations = event.data.get("citations", [])
+            elif event.event == "done":
+                run_id = event.data.get("run_id")
+                latency_ms = event.data.get("latency_ms")
+        typer.echo("")
+        _print_sources(citations)
+        _print_graph(subgraph, dropped_relationship_claims)
+        if run_id is not None:
+            typer.echo(f"run {run_id} in {latency_ms}ms")
+    except RagFabricError as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(1) from exc
+    except Exception as exc:  # connection refused, DNS failure, timeout
+        typer.echo(f"could not reach {url}: {exc}", err=True)
+        raise typer.Exit(1) from exc
+    finally:
+        client.close()
+
+
+def _print_sources(citations: list[dict]) -> None:
+    used = [citation for citation in citations if citation.get("used")]
+    if not used:
+        return
+    typer.echo("sources:")
+    for citation in used:
+        name = citation.get("filename") or f"document {citation.get('document_id')}"
+        page = f" p{citation['page']}" if citation.get("page") else ""
+        typer.echo(f"  {citation['marker']} {name}{page}")
+
+
+def _print_graph(subgraph: dict | None, dropped: list[dict]) -> None:
+    """The relationships the graph strategy walked, and the claims about them it dropped.
+
+    Printed as ``name RELATION name`` in the direction walked, the same reading
+    the answer's ``[E k]`` markers were numbered against. Nothing is printed
+    for a strategy that walks no graph.
+    """
+    if subgraph is not None:
+        names = {node["id"]: node["name"] for node in subgraph.get("nodes", [])}
+        edges = subgraph.get("edges", [])
+        if edges:
+            typer.echo("graph:")
+            for number, edge in enumerate(edges, start=1):
+                start, end = edge["source_id"], edge["target_id"]
+                if edge.get("reversed"):
+                    start, end = end, start
+                typer.echo(
+                    f"  [E {number}] {names.get(start, start)} {edge['walked_as']} "
+                    f"{names.get(end, end)}"
+                )
+        elif subgraph.get("empty_reason"):
+            typer.echo(f"graph: nothing walked ({subgraph['empty_reason']})")
+        if subgraph.get("truncated"):
+            typer.echo("graph: the walk was cut by the node budget")
+    if dropped:
+        typer.echo("dropped relationship claims:")
+        for claim in dropped:
+            typer.echo(f"  {claim['reason']}: {claim['text']}")

ragfabric-0.3.1/src/ragfabric_cli/commands/common.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+
+import typer
+from sqlalchemy.orm import Session
+
+from ragfabric_core.models.document import Collection
+from ragfabric_core.models.user import User
+
+
+@contextmanager
+def session():
+    from ragfabric_core.runtime import get_session_factory
+
+    db: Session = get_session_factory()()
+    try:
+        yield db
+    finally:
+        db.close()
+
+
+def user_by_email(db: Session, email: str) -> User:
+    user = db.query(User).filter(User.email == email.lower()).first()
+    if user is None:
+        typer.echo(f"user not found: {email}")
+        raise typer.Exit(code=1)
+    return user
+
+
+def collection_by_name(db: Session, name: str, create: bool = False) -> Collection:
+    collection = db.query(Collection).filter(Collection.name == name).first()
+    if collection is None:
+        if not create:
+            typer.echo(f"collection not found: {name}")
+            raise typer.Exit(code=1)
+        collection = Collection(name=name)
+        db.add(collection)
+        db.flush()
+    return collection

ragfabric-0.3.1/src/ragfabric_cli/commands/graph.py

@@ -0,0 +1,125 @@
+"""ragfabric graph merges: inspect and undo recorded entity merges (ruling R37).
+
+An operator command, like ``users``, ``groups``, ``grants`` and ``keys``: it
+opens the configured database directly and acts on it, so running it at all
+requires the database credentials only an administrator holds. There is no
+HTTP endpoint for merges in this phase; the Phase 9 console owns that.
+
+Every merge entity resolution makes is recorded as an ``EntityMerge`` row with
+the evidence that justified it (Task 5). Without a way to read and reverse
+those rows the record would be write-only, so ``list`` and ``show`` read them
+and ``undo`` calls ``graph.resolve.unmerge`` and commits only if it succeeds.
+Unmerge is globally last-in, first-out (ruling R30): an older merge cannot be
+undone while a newer one is in place, and ``undo`` says which ones block it
+and exits non-zero rather than attempting a partial repair.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import typer
+
+from ragfabric_cli.commands.common import session
+from ragfabric_core.graph.resolve import UnmergeBlocked, UnmergeResult, unmerge
+from ragfabric_core.models.graph import Entity, EntityMerge
+
+graph_app = typer.Typer(help="Knowledge graph administration.")
+merges_app = typer.Typer(help="Recorded entity merges: list, show and undo.")
+graph_app.add_typer(merges_app, name="merges")
+
+_RESULT_FIELDS = (
+    "restored_entity_id",
+    "survivor_entity_id",
+    "moved_relationship_ids",
+    "shared_relationship_ids",
+    "restored_relationship_ids",
+    "unrestored_relationship_ids",
+    "changed_chunk_ids",
+    "restored_without_sources",
+)
+
+
+def _survivor_name(db, entity_id: int) -> str:
+    entity = db.get(Entity, entity_id)
+    return entity.name if entity is not None else "?"
+
+
+@merges_app.command("list")
+def list_merges() -> None:
+    """Every recorded merge, oldest first. Undo them newest first."""
+    with session() as db:
+        records = db.query(EntityMerge).order_by(EntityMerge.id).all()
+        if not records:
+            typer.echo("no recorded merges")
+            return
+        for record in records:
+            typer.echo(
+                f"{record.id}\t{record.method}\t{record.merged_name} ({record.merged_entity_type})"
+                f" -> {record.surviving_entity_id} {_survivor_name(db, record.surviving_entity_id)}"
+                f"\t{len(record.merged_source_chunk_ids)} chunk(s)\t{record.created_at:%Y-%m-%d}"
+            )
+
+
+def _record(db, merge_id: int) -> EntityMerge:
+    record = db.get(EntityMerge, merge_id)
+    if record is None:
+        typer.echo(f"merge not found: {merge_id}", err=True)
+        raise typer.Exit(code=1)
+    return record
+
+
+@merges_app.command("show")
+def show_merge(merge_id: int) -> None:
+    """One merge: what was merged into what, by which method, and the evidence for it."""
+    with session() as db:
+        record = _record(db, merge_id)
+        evidence: dict[str, Any] = dict(record.evidence)
+        restore: dict[str, Any] = evidence.pop("restore", {}) or {}
+        typer.echo(f"merge {record.id} ({record.method}, {record.created_at:%Y-%m-%d %H:%M})")
+        typer.echo(f"merged: {record.merged_name} ({record.merged_entity_type})")
+        typer.echo(
+            f"into: {record.surviving_entity_id} {_survivor_name(db, record.surviving_entity_id)}"
+        )
+        typer.echo(f"model: {record.model or 'none'}")
+        typer.echo(f"merged aliases: {', '.join(record.merged_aliases) or 'none'}")
+        typer.echo(f"source chunks: {sorted(record.merged_source_chunk_ids)}")
+        typer.echo("evidence:")
+        typer.echo(json.dumps(evidence, indent=2, sort_keys=True, default=str))
+        # The restore payload is what makes the unmerge exact, not justification;
+        # summarised here so an operator can see what an undo would touch.
+        typer.echo(
+            f"undo would restore: {len(restore.get('relationships', []))} recorded "
+            f"relationship(s), {len(restore.get('dropped_self_loops', []))} dropped self "
+            f"loop(s), aliases appended {restore.get('aliases_appended', [])}"
+        )
+
+
+@merges_app.command("undo")
+def undo_merge(merge_id: int) -> None:
+    """Reverse one merge. Refused while any newer merge is still in place."""
+    with session() as db:
+        try:
+            result = unmerge(db, merge_id)
+        except UnmergeBlocked as exc:
+            db.rollback()
+            blocking = " ".join(str(i) for i in exc.blocking_merge_ids)
+            typer.echo(
+                f"cannot undo merge {merge_id}: blocked by later merges: {blocking} "
+                "(undo those first, newest first)",
+                err=True,
+            )
+            raise typer.Exit(code=1) from None
+        except (LookupError, ValueError) as exc:
+            db.rollback()
+            typer.echo(f"cannot undo merge {merge_id}: {exc}", err=True)
+            raise typer.Exit(code=1) from None
+        db.commit()
+    typer.echo(f"undid merge {merge_id}")
+    _print_result(result)
+
+
+def _print_result(result: UnmergeResult) -> None:
+    for field in _RESULT_FIELDS:
+        typer.echo(f"{field}: {getattr(result, field)}")