ragfly-cli 1.19.1__tar.gz → 1.20.0__tar.gz

{ragfly_cli-1.19.1/ragfly_cli.egg-info → ragfly_cli-1.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ragfly-cli
-Version: 1.19.1
+Version: 1.20.0
 Summary: RAGfly CLI — operate RAGfly from the terminal and CI (login + cloud API). Lightweight, no desktop dependencies.
 Author: CAB Ltda
 License: MIT
@@ -78,10 +78,12 @@ ragfly
     ├── group          list | switch | clear      (signed-in person)
     ├── api-key        create | list | revoke     (signed-in person)
     ├── document       list | show | edges
-    ├── space          list | show
+    ├── space          list | show | compose | read | refresh | promote
     ├── queue          show | runs
     ├── skill          list | show | run
     ├── catalog
+    ├── document-type  list
+    ├── characteristic list
     ├── function       show
     ├── search
     ├── chat           ask
@@ -112,6 +114,8 @@ Output is English end to end (`--status VECTORIZED`, `-o json | jq`).
 ragfly cloud document list --status VECTORIZED --limit 20 -o id
 ragfly cloud skill run SUMMARIZE_DOCUMENT --space 12
 ragfly cloud search "Q1 revenue"
+ragfly cloud search "statements" --filter @filter.json --space 12
+ragfly cloud chat ask "How do I release the entity of my key?" --mode help
 ```
 
 Full reference: <https://api.ragfly.ai/docs>.

{ragfly_cli-1.19.1 → ragfly_cli-1.20.0}/README.md

@@ -58,10 +58,12 @@ ragfly
     ├── group          list | switch | clear      (signed-in person)
     ├── api-key        create | list | revoke     (signed-in person)
     ├── document       list | show | edges
-    ├── space          list | show
+    ├── space          list | show | compose | read | refresh | promote
     ├── queue          show | runs
     ├── skill          list | show | run
     ├── catalog
+    ├── document-type  list
+    ├── characteristic list
     ├── function       show
     ├── search
     ├── chat           ask
@@ -92,6 +94,8 @@ Output is English end to end (`--status VECTORIZED`, `-o json | jq`).
 ragfly cloud document list --status VECTORIZED --limit 20 -o id
 ragfly cloud skill run SUMMARIZE_DOCUMENT --space 12
 ragfly cloud search "Q1 revenue"
+ragfly cloud search "statements" --filter @filter.json --space 12
+ragfly cloud chat ask "How do I release the entity of my key?" --mode help
 ```
 
 Full reference: <https://api.ragfly.ai/docs>.

{ragfly_cli-1.19.1 → ragfly_cli-1.20.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ragfly-cli"
-version = "1.19.1"
+version = "1.20.0"
 description = "RAGfly CLI — operate RAGfly from the terminal and CI (login + cloud API). Lightweight, no desktop dependencies."
 readme = "README.md"
 requires-python = ">=3.10"

ragfly_cli-1.20.0/ragfly_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.20.0"

{ragfly_cli-1.19.1 → ragfly_cli-1.20.0}/ragfly_cli/cli.py

@@ -439,6 +439,48 @@ def cloud_space_show(space_id: int, document_limit: int, output: str):
     _table("Documents", data.get("documents") or [], [("Code", "code"), ("Name", "name"), ("Status", "status")])
 
 
+@cloud_space.command("compose")
+@click.argument("operation", type=click.Choice(["union", "intersection", "difference", "symmetric_difference"]))
+@click.argument("space_a", type=int)
+@click.argument("space_b", type=int)
+@click.option("--name", default="", help="Name of the result (generated when empty)")
+@click.option("--type", "space_type", type=click.Choice(["AREA", "SPACE"]), default="AREA", show_default=True)
+@click.option("-o", "--output", type=OUTPUT_TABLE, default="json")
+def cloud_space_compose(operation: str, space_a: int, space_b: int, name: str, space_type: str, output: str):
+    """Combine two working spaces by set algebra into a new one."""
+    data = _v1("POST", "/v1/spaces/compose", body={
+        "operation": operation, "space_id_a": space_a, "space_id_b": space_b,
+        "name": name, "space_type": space_type,
+    })
+    _emit_json(data) if output == "json" else _fields("New working space", data, [
+        ("ID", "space_id"), ("Name", "name"), ("Type", "type"), ("Documents", "total_documents")])
+
+
+@cloud_space.command("read")
+@click.argument("space_id", type=int)
+@click.option("--resolution", type=click.Choice(["count", "manifest", "chunks", "text"]), default="manifest", show_default=True)
+@click.option("--query", default="", help="Sub-question to rank by (required with --resolution chunks)")
+@click.option("--limit", type=int, default=50, show_default=True)
+def cloud_space_read(space_id: int, resolution: str, query: str, limit: int):
+    """Read a working space at the chosen resolution (JSON output)."""
+    _emit_json(_v1("POST", f"/v1/spaces/{space_id}/read",
+                   body={"resolution": resolution, "query": query, "limit": limit}))
+
+
+@cloud_space.command("refresh")
+@click.argument("space_id", type=int)
+def cloud_space_refresh(space_id: int):
+    """Recompute the members of a working space (JSON output)."""
+    _emit_json(_v1("POST", f"/v1/spaces/{space_id}/refresh"))
+
+
+@cloud_space.command("promote")
+@click.argument("space_id", type=int)
+def cloud_space_promote(space_id: int):
+    """Turn a temporary working space into a permanent one (JSON output)."""
+    _emit_json(_v1("POST", f"/v1/spaces/{space_id}/promote"))
+
+
 # ── cloud queue ──────────────────────────────────────────────────────────────
 
 @cloud.group("queue")
@@ -534,6 +576,38 @@ def cloud_catalog(type_: str, output: str):
         _table("Skills", data["skills"], [("Code", "code"), ("Name", "name"), ("Applies to", "applies_to")])
 
 
+@cloud.group("document-type")
+def cloud_document_type():
+    """Document types of an entity: the codes `search --filter` accepts."""
+
+
+@cloud_document_type.command("list")
+@click.option("--entity", default=None, help="Entity code (defaults to the active entity)")
+@click.option("-o", "--output", type=OUTPUT_LIST, default="table")
+def cloud_document_type_list(entity: str | None, output: str):
+    """List the document types of the entity, with their parent type."""
+    data = _v1("GET", "/v1/catalog/document-types", params={"entity_code": entity})
+    _list(data, output, key="document_types", id_key="code", title="Document types",
+          columns=[("Code", "code"), ("Name", "name"), ("Parent", "parent_code"), ("Documents", "document_count")])
+
+
+@cloud.group("characteristic")
+def cloud_characteristic():
+    """Content characteristics of the document types: the codes `search --filter` accepts."""
+
+
+@cloud_characteristic.command("list")
+@click.option("--document-type", "document_types", multiple=True, help="Document type code (repeat for several)")
+@click.option("--entity", default=None, help="Entity code (defaults to the active entity)")
+@click.option("-o", "--output", type=OUTPUT_LIST, default="table")
+def cloud_characteristic_list(document_types: tuple[str, ...], entity: str | None, output: str):
+    """List the characteristics available for those types (all when none is given)."""
+    data = _v1("GET", "/v1/catalog/characteristics", params={
+        "document_types": ",".join(document_types) or None, "entity_code": entity})
+    _list(data, output, key="characteristics", id_key="code", title="Characteristics",
+          columns=[("Category", "category_code"), ("Code", "code"), ("Name", "name"), ("Role", "role")])
+
+
 @cloud.group("function")
 def cloud_function():
     """Functions (screens) of the RAGfly application."""
@@ -557,8 +631,12 @@ def cloud_function_show(function_code: str, output: str):
 @click.option("--limit", type=int, default=10, show_default=True)
 @click.option("--min-similarity", type=float, default=0.0, show_default=True)
 @click.option("--entity", default=None, help="Filter by entity code")
+@click.option("--space", "space_id", type=int, default=None, help="Search only inside this working space")
+@click.option("--filter", "filter_json", default=None,
+              help="Structured filter as JSON, @file or - (document_types, attributes, characteristics)")
 @click.option("-o", "--output", type=OUTPUT_TABLE, default="table")
-def cloud_search(query: tuple[str, ...], limit: int, min_similarity: float, entity: str | None, output: str):
+def cloud_search(query: tuple[str, ...], limit: int, min_similarity: float, entity: str | None,
+                 space_id: int | None, filter_json: str | None, output: str):
     """Semantic search over the group's vectorized documents."""
     text = " ".join(query).strip()
     if not text:
@@ -566,6 +644,10 @@ def cloud_search(query: tuple[str, ...], limit: int, min_similarity: float, enti
     body = {"query": text, "limit": limit, "min_similarity": min_similarity}
     if entity:
         body["entity_code"] = entity
+    if space_id is not None:
+        body["space_id"] = space_id
+    if filter_json:
+        body["filter"] = _json_argument(filter_json, "--filter")
     data = _v1("POST", "/v1/documents/search", body=body)
     if output == "json":
         _emit_json(data)
@@ -587,8 +669,10 @@ def cloud_chat():
 @click.argument("message", nargs=-1, required=True)
 @click.option("--function", "function_code", default="CHAT-USER", show_default=True, help="Chat function code")
 @click.option("--conversation", "conversation_id", type=int, default=None, help="Continue an existing conversation")
+@click.option("--mode", type=click.Choice(["default", "help"]), default=None,
+              help="help: answer questions about RAGfly itself (how to use or integrate it), without links to web screens")
 @click.option("-o", "--output", type=click.Choice(["text", "json"]), default="text")
-def cloud_chat_ask(message: tuple[str, ...], function_code: str, conversation_id: int | None, output: str):
+def cloud_chat_ask(message: tuple[str, ...], function_code: str, conversation_id: int | None, mode: str | None, output: str):
     """Ask a question. Creates a conversation unless --conversation is given."""
     question = " ".join(message).strip()
     if not question:
@@ -596,6 +680,8 @@ def cloud_chat_ask(message: tuple[str, ...], function_code: str, conversation_id
     body = {"question": question, "function_code": function_code}
     if conversation_id:
         body["conversation_id"] = conversation_id
+    if mode:
+        body["mode"] = mode
     data = _v1("POST", "/v1/ask", body=body)
     if output == "json":
         _emit_json(data)

{ragfly_cli-1.19.1 → ragfly_cli-1.20.0/ragfly_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ragfly-cli
-Version: 1.19.1
+Version: 1.20.0
 Summary: RAGfly CLI — operate RAGfly from the terminal and CI (login + cloud API). Lightweight, no desktop dependencies.
 Author: CAB Ltda
 License: MIT
@@ -78,10 +78,12 @@ ragfly
     ├── group          list | switch | clear      (signed-in person)
     ├── api-key        create | list | revoke     (signed-in person)
     ├── document       list | show | edges
-    ├── space          list | show
+    ├── space          list | show | compose | read | refresh | promote
     ├── queue          show | runs
     ├── skill          list | show | run
     ├── catalog
+    ├── document-type  list
+    ├── characteristic list
     ├── function       show
     ├── search
     ├── chat           ask
@@ -112,6 +114,8 @@ Output is English end to end (`--status VECTORIZED`, `-o json | jq`).
 ragfly cloud document list --status VECTORIZED --limit 20 -o id
 ragfly cloud skill run SUMMARIZE_DOCUMENT --space 12
 ragfly cloud search "Q1 revenue"
+ragfly cloud search "statements" --filter @filter.json --space 12
+ragfly cloud chat ask "How do I release the entity of my key?" --mode help
 ```
 
 Full reference: <https://api.ragfly.ai/docs>.

{ragfly_cli-1.19.1 → ragfly_cli-1.20.0}/ragfly_cli.egg-info/SOURCES.txt

@@ -21,4 +21,5 @@ ragfly_cli/oop/__init__.py
 ragfly_cli/oop/cli_command.py
 ragfly_cli/oop/http_client.py
 tests/test_agent_context_cli.py
-tests/test_api_key_group_override.py
+tests/test_api_key_group_override.py
+tests/test_surface_parity_cli.py

ragfly_cli-1.20.0/tests/test_surface_parity_cli.py

@@ -0,0 +1,75 @@
+"""The CLI exposes the same /v1 operations as the SDKs and MCP: ask mode, filtered search, catalogs, spaces."""
+import json
+
+import httpx
+import pytest
+from click.testing import CliRunner
+
+from ragfly_cli.cli import app
+
+
+@pytest.fixture
+def wire(monkeypatch):
+    monkeypatch.setenv("RAGFLY_API_KEY", "rf_test")
+    monkeypatch.delenv("RAGFLY_TOKEN", raising=False)
+    monkeypatch.setattr("ragfly_cli.config.get_config", lambda: type("C", (), {"codigo_grupo": ""})())
+
+    class Wire:
+        reply = httpx.Response(200, json={})
+        calls: list = []
+
+    def fake_request(method, url, **kwargs):
+        Wire.calls.append({"method": method, "url": url, **kwargs})
+        response = Wire.reply
+        response.request = httpx.Request(method, url)
+        return response
+
+    monkeypatch.setattr(httpx, "request", fake_request)
+    Wire.calls = []
+    return Wire
+
+
+def run(*args):
+    return CliRunner().invoke(app, list(args))
+
+
+def test_ask_sends_mode_only_when_given(wire):
+    wire.reply = httpx.Response(200, json={"answer": "A", "conversation_id": 1})
+    assert run("cloud", "chat", "ask", "how do I release the entity?", "--mode", "help").exit_code == 0
+    assert wire.calls[0]["json"] == {"question": "how do I release the entity?", "function_code": "CHAT-USER", "mode": "help"}
+    assert run("cloud", "chat", "ask", "hello").exit_code == 0
+    assert "mode" not in wire.calls[1]["json"]
+    assert run("cloud", "chat", "ask", "hello", "--mode", "support").exit_code != 0
+
+
+def test_search_takes_space_and_structured_filter(wire):
+    wire.reply = httpx.Response(200, json={"documents": []})
+    flt = {"document_types": ["TDOC_cartola"], "attributes": [{"field": "language", "operator": "EQ", "value": "es"}]}
+    result = run("cloud", "search", "cartolas", "--space", "12", "--filter", json.dumps(flt), "-o", "json")
+    assert result.exit_code == 0, result.output
+    body = wire.calls[0]["json"]
+    assert wire.calls[0]["url"].endswith("/v1/documents/search")
+    assert body["query"] == "cartolas" and body["space_id"] == 12 and body["filter"] == flt
+    assert run("cloud", "search", "x", "--filter", "[1]").exit_code != 0  # a filter is a JSON object
+
+
+def test_catalog_commands_call_the_public_catalog_routes(wire):
+    wire.reply = httpx.Response(200, json={"document_types": [{"code": "T1", "name": "Statement", "parent_code": None, "document_count": 3}]})
+    assert run("cloud", "document-type", "list", "--entity", "E1", "-o", "id").output.strip() == "T1"
+    assert wire.calls[0]["url"].endswith("/v1/catalog/document-types") and wire.calls[0]["params"] == {"entity_code": "E1"}
+    wire.reply = httpx.Response(200, json={"characteristics": []})
+    assert run("cloud", "characteristic", "list", "--document-type", "T1", "--document-type", "T2", "-o", "json").exit_code == 0
+    assert wire.calls[1]["url"].endswith("/v1/catalog/characteristics")
+    assert wire.calls[1]["params"] == {"document_types": "T1,T2"}
+
+
+def test_space_commands_cover_compose_read_refresh_and_promote(wire):
+    wire.reply = httpx.Response(200, json={"space_id": 9})
+    assert run("cloud", "space", "compose", "difference", "1", "2", "--name", "N", "--type", "SPACE").exit_code == 0
+    assert wire.calls[0]["url"].endswith("/v1/spaces/compose")
+    assert wire.calls[0]["json"] == {"operation": "difference", "space_id_a": 1, "space_id_b": 2, "name": "N", "space_type": "SPACE"}
+    assert run("cloud", "space", "read", "9", "--resolution", "chunks", "--query", "q", "--limit", "5").exit_code == 0
+    assert wire.calls[1]["url"].endswith("/v1/spaces/9/read")
+    assert wire.calls[1]["json"] == {"resolution": "chunks", "query": "q", "limit": 5}
+    assert run("cloud", "space", "refresh", "9").exit_code == 0 and wire.calls[2]["url"].endswith("/v1/spaces/9/refresh")
+    assert run("cloud", "space", "promote", "9").exit_code == 0 and wire.calls[3]["url"].endswith("/v1/spaces/9/promote")

ragfly_cli-1.19.1/ragfly_cli/__init__.py

@@ -1 +0,0 @@
-__version__ = "1.19.1"