deepflow-openagent-cli 0.1.4__tar.gz → 0.1.5__tar.gz

{deepflow_openagent_cli-0.1.4 → deepflow_openagent_cli-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepflow-openagent-cli
-Version: 0.1.4
+Version: 0.1.5
 Summary: Command-line client for OpenAgent OpenAPI (agents, conversations, SSE chat, tools, channels, knowledge bases).
 Author: DeepFlow AI
 Project-URL: Repository, https://github.com/DeepFlowAI/OpenAgent
@@ -66,6 +66,21 @@ deepflow_openagent_cli docs show chat.stream --json
 deepflow_openagent_cli knowledge list --page 1 --per-page 10
 deepflow_openagent_cli knowledge documents 1
 deepflow_openagent_cli knowledge query-document 6670 --slice-id 512208 --line 1720
+
+# Knowledge-base file library (requires config scope)
+deepflow_openagent_cli knowledge directories create 1 --name "Policies"
+deepflow_openagent_cli knowledge files create 1 \
+  --directory-id 2 --name "Product Manual" --custom-version v1 \
+  --original ./manual.pdf --markdown ./manual.md
+deepflow_openagent_cli knowledge files list 1 --markdown-filter has-missing
+deepflow_openagent_cli knowledge versions upload 1 3 \
+  --custom-version v2 --original ./manual-v2.pdf
+deepflow_openagent_cli knowledge versions attach-markdown 1 3 4 \
+  --markdown ./manual-v2.md
+deepflow_openagent_cli knowledge versions set-current 1 3 4
+deepflow_openagent_cli knowledge versions original 1 3 4 --output ./manual-v2.pdf
+deepflow_openagent_cli knowledge versions markdown 1 3 4 --output ./manual-v2.md
+
 deepflow_openagent_cli chat 1 --message "Hello"
 deepflow_openagent_cli steps 1 42
 deepflow_openagent_cli steps get 1 42 100

{deepflow_openagent_cli-0.1.4 → deepflow_openagent_cli-0.1.5}/README.md

@@ -45,6 +45,21 @@ deepflow_openagent_cli docs show chat.stream --json
 deepflow_openagent_cli knowledge list --page 1 --per-page 10
 deepflow_openagent_cli knowledge documents 1
 deepflow_openagent_cli knowledge query-document 6670 --slice-id 512208 --line 1720
+
+# Knowledge-base file library (requires config scope)
+deepflow_openagent_cli knowledge directories create 1 --name "Policies"
+deepflow_openagent_cli knowledge files create 1 \
+  --directory-id 2 --name "Product Manual" --custom-version v1 \
+  --original ./manual.pdf --markdown ./manual.md
+deepflow_openagent_cli knowledge files list 1 --markdown-filter has-missing
+deepflow_openagent_cli knowledge versions upload 1 3 \
+  --custom-version v2 --original ./manual-v2.pdf
+deepflow_openagent_cli knowledge versions attach-markdown 1 3 4 \
+  --markdown ./manual-v2.md
+deepflow_openagent_cli knowledge versions set-current 1 3 4
+deepflow_openagent_cli knowledge versions original 1 3 4 --output ./manual-v2.pdf
+deepflow_openagent_cli knowledge versions markdown 1 3 4 --output ./manual-v2.md
+
 deepflow_openagent_cli chat 1 --message "Hello"
 deepflow_openagent_cli steps 1 42
 deepflow_openagent_cli steps get 1 42 100

{deepflow_openagent_cli-0.1.4 → deepflow_openagent_cli-0.1.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepflow-openagent-cli"
-version = "0.1.4"
+version = "0.1.5"
 description = "Command-line client for OpenAgent OpenAPI (agents, conversations, SSE chat, tools, channels, knowledge bases)."
 readme = "README.md"
 requires-python = ">=3.11"

{deepflow_openagent_cli-0.1.4 → deepflow_openagent_cli-0.1.5}/src/deepflow_openagent_cli/__init__.py

@@ -1,3 +1,3 @@
 """DeepFlow OpenAgent CLI — published PyPI package."""
 
-__version__ = "0.1.4"
+__version__ = "0.1.5"

{deepflow_openagent_cli-0.1.4 → deepflow_openagent_cli-0.1.5}/src/deepflow_openagent_cli/cli.py

@@ -9,14 +9,18 @@ from __future__ import annotations
 
 import argparse
 import json
+import mimetypes
 import os
 import sys
+import tempfile
+from collections.abc import Iterator
 from dataclasses import asdict, dataclass, field
 from pathlib import Path
 from typing import Any
 from urllib.error import HTTPError, URLError
 from urllib.parse import urlencode
 from urllib.request import Request, urlopen
+from uuid import uuid4
 
 
 DEFAULT_HOST = "http://localhost:5001"
@@ -53,6 +57,72 @@ class EndpointDoc:
     example: str = ""
 
 
+class MultipartBody:
+    """Replayable multipart body that streams file content in bounded chunks."""
+
+    chunk_size = 1024 * 1024
+
+    def __init__(
+        self,
+        fields: dict[str, str | int | None],
+        files: dict[str, Path | None],
+    ) -> None:
+        self.boundary = f"openagent-{uuid4().hex}"
+        self._parts: list[bytes | Path] = []
+        boundary = self.boundary.encode("ascii")
+        for name, value in fields.items():
+            if value is None:
+                continue
+            self._parts.extend(
+                [
+                    b"--" + boundary + b"\r\n",
+                    f'Content-Disposition: form-data; name="{name}"\r\n\r\n'.encode(
+                        "utf-8"
+                    ),
+                    str(value).encode("utf-8"),
+                    b"\r\n",
+                ]
+            )
+        for name, path in files.items():
+            if path is None:
+                continue
+            resolved = path.expanduser()
+            if not resolved.is_file():
+                raise CliError(f"Upload file does not exist: {path}")
+            content_type = mimetypes.guess_type(resolved.name)[0] or "application/octet-stream"
+            escaped_name = resolved.name.replace('"', "")
+            self._parts.extend(
+                [
+                    b"--" + boundary + b"\r\n",
+                    (
+                        f'Content-Disposition: form-data; name="{name}"; '
+                        f'filename="{escaped_name}"\r\n'
+                        f"Content-Type: {content_type}\r\n\r\n"
+                    ).encode("utf-8"),
+                    resolved,
+                    b"\r\n",
+                ]
+            )
+        self._parts.append(b"--" + boundary + b"--\r\n")
+        self.content_length = sum(
+            part.stat().st_size if isinstance(part, Path) else len(part)
+            for part in self._parts
+        )
+
+    @property
+    def content_type(self) -> str:
+        return f"multipart/form-data; boundary={self.boundary}"
+
+    def __iter__(self) -> Iterator[bytes]:
+        for part in self._parts:
+            if isinstance(part, Path):
+                with part.open("rb") as file_object:
+                    while chunk := file_object.read(self.chunk_size):
+                        yield chunk
+            else:
+                yield part
+
+
 def _param(name: str, type_: str, required: bool, description: str) -> ParamDoc:
     return ParamDoc(name=name, type=type_, required=required, description=description)
 
@@ -121,6 +191,326 @@ ENDPOINTS: tuple[EndpointDoc, ...] = (
         errors=["401 missing or invalid API key", "403 scope missing", "404 knowledge base not found", "422 validation error"],
         example="deepflow_openagent_cli knowledge documents 1 --page 1 --per-page 20",
     ),
+    EndpointDoc(
+        key="knowledge.file_directories.list",
+        method="GET",
+        path="/api/v1/knowledge-bases/{kb_id}/file-directories",
+        scope="config",
+        summary="List the file-library directory tree.",
+        path_params=[_param("kb_id", "integer", True, "Knowledge base ID.")],
+        response="Directory list and total file count.",
+        errors=["401 invalid API key", "403 config scope missing", "404 knowledge base not found"],
+        example="deepflow_openagent_cli knowledge directories list 1",
+    ),
+    EndpointDoc(
+        key="knowledge.file_directories.create",
+        method="POST",
+        path="/api/v1/knowledge-bases/{kb_id}/file-directories",
+        scope="config",
+        summary="Create a file-library directory.",
+        path_params=[_param("kb_id", "integer", True, "Knowledge base ID.")],
+        body_fields=[
+            _param("name", "string", True, "Directory name, 1-50 chars."),
+            _param("parent_id", "integer", False, "Parent directory ID."),
+        ],
+        response="Created directory.",
+        errors=["400 validation error", "401 invalid API key", "403 config scope missing", "404 knowledge base not found"],
+        example="deepflow_openagent_cli knowledge directories create 1 --name Policies",
+    ),
+    EndpointDoc(
+        key="knowledge.file_directories.update",
+        method="PUT",
+        path="/api/v1/knowledge-bases/{kb_id}/file-directories/{directory_id}",
+        scope="config",
+        summary="Rename, move, or reorder a file-library directory.",
+        path_params=[
+            _param("kb_id", "integer", True, "Knowledge base ID."),
+            _param("directory_id", "integer", True, "Directory ID."),
+        ],
+        body_fields=[
+            _param("name", "string", False, "Directory name, 1-50 chars."),
+            _param("parent_id", "integer|null", False, "Parent directory ID."),
+            _param("sort_order", "integer", False, "Non-negative sort order."),
+        ],
+        response="Updated directory.",
+        errors=["400 validation error", "401 invalid API key", "403 config scope missing", "404 directory not found"],
+        example="deepflow_openagent_cli knowledge directories update 1 2 --name Regulations",
+    ),
+    EndpointDoc(
+        key="knowledge.file_directories.delete",
+        method="DELETE",
+        path="/api/v1/knowledge-bases/{kb_id}/file-directories/{directory_id}",
+        scope="config",
+        summary="Delete an empty file-library directory.",
+        path_params=[
+            _param("kb_id", "integer", True, "Knowledge base ID."),
+            _param("directory_id", "integer", True, "Directory ID."),
+        ],
+        response="Deletion confirmation.",
+        errors=["400 directory not empty", "401 invalid API key", "403 config scope missing", "404 directory not found"],
+        example="deepflow_openagent_cli knowledge directories delete 1 2",
+    ),
+    EndpointDoc(
+        key="knowledge.files.list",
+        method="GET",
+        path="/api/v1/knowledge-bases/{kb_id}/files",
+        scope="config",
+        summary="List and filter file-library file objects.",
+        path_params=[_param("kb_id", "integer", True, "Knowledge base ID.")],
+        query_params=[
+            _param("directory_id", "integer", False, "Directory ID."),
+            _param("search", "string", False, "Name, description, or version search."),
+            _param("markdown", "string", False, "all, missing-current, has-missing, or complete."),
+            _param("page", "integer", False, "Page number."),
+            _param("per_page", "integer", False, "Items per page, 1-50."),
+        ],
+        response="Paginated file objects with current version and version counts.",
+        errors=["401 invalid API key", "403 config scope missing", "404 knowledge base not found", "422 validation error"],
+        example="deepflow_openagent_cli knowledge files list 1 --markdown-filter has-missing",
+    ),
+    EndpointDoc(
+        key="knowledge.files.create",
+        method="POST",
+        path="/api/v1/knowledge-bases/{kb_id}/files",
+        scope="config",
+        summary="Create a file object and its first version using multipart upload.",
+        path_params=[_param("kb_id", "integer", True, "Knowledge base ID.")],
+        body_fields=[
+            _param("directory_id", "integer", True, "Directory ID."),
+            _param("name", "string", True, "File object name, 1-200 chars."),
+            _param("custom_version", "string", True, "Business version, 1-100 chars."),
+            _param("description", "string", False, "Description, max 500 chars."),
+            _param("note", "string", False, "Version note, max 200 chars."),
+            _param("original", "file", True, "Original file."),
+            _param("markdown", "file", False, "Optional Markdown file."),
+        ],
+        response="Created file detail.",
+        errors=["400 validation or duplicate error", "401 invalid API key", "403 config scope missing", "404 directory not found", "413 file too large"],
+        example="deepflow_openagent_cli knowledge files create 1 --directory-id 2 --name Manual --custom-version v1 --original manual.pdf",
+    ),
+    EndpointDoc(
+        key="knowledge.files.get",
+        method="GET",
+        path="/api/v1/knowledge-bases/{kb_id}/files/{file_id}",
+        scope="config",
+        summary="Get a file object and filtered version history.",
+        path_params=[
+            _param("kb_id", "integer", True, "Knowledge base ID."),
+            _param("file_id", "integer", True, "File object ID."),
+        ],
+        query_params=[_param("markdown", "string", False, "Version Markdown filter.")],
+        response="File detail and version history.",
+        errors=["401 invalid API key", "403 config scope missing", "404 file not found"],
+        example="deepflow_openagent_cli knowledge files get 1 3 --markdown-filter missing",
+    ),
+    EndpointDoc(
+        key="knowledge.files.update",
+        method="PUT",
+        path="/api/v1/knowledge-bases/{kb_id}/files/{file_id}",
+        scope="config",
+        summary="Rename, describe, or move a file object.",
+        path_params=[
+            _param("kb_id", "integer", True, "Knowledge base ID."),
+            _param("file_id", "integer", True, "File object ID."),
+        ],
+        body_fields=[
+            _param("name", "string", False, "File object name."),
+            _param("description", "string|null", False, "Description."),
+            _param("directory_id", "integer", False, "Target directory ID."),
+        ],
+        response="Updated file detail.",
+        errors=["400 validation or duplicate error", "401 invalid API key", "403 config scope missing", "404 file not found"],
+        example="deepflow_openagent_cli knowledge files update 1 3 --name NewManual",
+    ),
+    EndpointDoc(
+        key="knowledge.files.delete",
+        method="DELETE",
+        path="/api/v1/knowledge-bases/{kb_id}/files/{file_id}",
+        scope="config",
+        summary="Delete a file object and all versions.",
+        path_params=[
+            _param("kb_id", "integer", True, "Knowledge base ID."),
+            _param("file_id", "integer", True, "File object ID."),
+        ],
+        response="Deletion confirmation.",
+        errors=["401 invalid API key", "403 config scope missing", "404 file not found"],
+        example="deepflow_openagent_cli knowledge files delete 1 3",
+    ),
+    EndpointDoc(
+        key="knowledge.file_versions.create",
+        method="POST",
+        path="/api/v1/knowledge-bases/{kb_id}/files/{file_id}/versions",
+        scope="config",
+        summary="Upload a new version using multipart upload.",
+        path_params=[
+            _param("kb_id", "integer", True, "Knowledge base ID."),
+            _param("file_id", "integer", True, "File object ID."),
+        ],
+        body_fields=[
+            _param("custom_version", "string", True, "Business version."),
+            _param("note", "string", False, "Version note."),
+            _param("original", "file", True, "Original file."),
+            _param("markdown", "file", False, "Optional Markdown file."),
+        ],
+        response="Created version detail.",
+        errors=["400 validation or duplicate error", "401 invalid API key", "403 config scope missing", "404 file not found", "413 file too large"],
+        example="deepflow_openagent_cli knowledge versions upload 1 3 --custom-version v2 --original manual-v2.pdf",
+    ),
+    EndpointDoc(
+        key="knowledge.file_versions.get",
+        method="GET",
+        path="/api/v1/knowledge-bases/{kb_id}/files/{file_id}/versions/{version_id}",
+        scope="config",
+        summary="Get one file version.",
+        path_params=[
+            _param("kb_id", "integer", True, "Knowledge base ID."),
+            _param("file_id", "integer", True, "File object ID."),
+            _param("version_id", "integer", True, "Version ID."),
+        ],
+        response="Version detail.",
+        errors=["401 invalid API key", "403 config scope missing", "404 version not found"],
+        example="deepflow_openagent_cli knowledge versions get 1 3 4",
+    ),
+    EndpointDoc(
+        key="knowledge.file_versions.update",
+        method="PUT",
+        path="/api/v1/knowledge-bases/{kb_id}/files/{file_id}/versions/{version_id}",
+        scope="config",
+        summary="Update a custom version label or note.",
+        path_params=[
+            _param("kb_id", "integer", True, "Knowledge base ID."),
+            _param("file_id", "integer", True, "File object ID."),
+            _param("version_id", "integer", True, "Version ID."),
+        ],
+        body_fields=[
+            _param("custom_version", "string", False, "Business version."),
+            _param("note", "string|null", False, "Version note."),
+        ],
+        response="Updated version detail.",
+        errors=["400 validation or duplicate error", "401 invalid API key", "403 config scope missing", "404 version not found"],
+        example="deepflow_openagent_cli knowledge versions update 1 3 4 --custom-version v2.1",
+    ),
+    EndpointDoc(
+        key="knowledge.file_versions.delete",
+        method="DELETE",
+        path="/api/v1/knowledge-bases/{kb_id}/files/{file_id}/versions/{version_id}",
+        scope="config",
+        summary="Delete a non-current file version.",
+        path_params=[
+            _param("kb_id", "integer", True, "Knowledge base ID."),
+            _param("file_id", "integer", True, "File object ID."),
+            _param("version_id", "integer", True, "Version ID."),
+        ],
+        response="Deletion confirmation.",
+        errors=["401 invalid API key", "403 config scope missing", "404 version not found", "409 current version conflict"],
+        example="deepflow_openagent_cli knowledge versions delete 1 3 4",
+    ),
+    EndpointDoc(
+        key="knowledge.file_versions.original",
+        method="GET",
+        path="/api/v1/knowledge-bases/{kb_id}/files/{file_id}/versions/{version_id}/original",
+        scope="config",
+        summary="Download the original file for a version.",
+        path_params=[
+            _param("kb_id", "integer", True, "Knowledge base ID."),
+            _param("file_id", "integer", True, "File object ID."),
+            _param("version_id", "integer", True, "Version ID."),
+        ],
+        response="Original file bytes.",
+        errors=["401 invalid API key", "403 config scope missing", "404 version not found"],
+        example="deepflow_openagent_cli knowledge versions original 1 3 4 --output manual.pdf",
+    ),
+    EndpointDoc(
+        key="knowledge.file_versions.attach_markdown",
+        method="POST",
+        path="/api/v1/knowledge-bases/{kb_id}/files/{file_id}/versions/{version_id}/markdown",
+        scope="config",
+        summary="Attach or replace a version Markdown file.",
+        path_params=[
+            _param("kb_id", "integer", True, "Knowledge base ID."),
+            _param("file_id", "integer", True, "File object ID."),
+            _param("version_id", "integer", True, "Version ID."),
+        ],
+        body_fields=[_param("markdown", "file", True, "Markdown file.")],
+        response="Updated version detail with processing status.",
+        errors=["400 invalid Markdown", "401 invalid API key", "403 config scope missing", "404 version not found", "413 file too large"],
+        example="deepflow_openagent_cli knowledge versions attach-markdown 1 3 4 --markdown manual.md",
+    ),
+    EndpointDoc(
+        key="knowledge.file_versions.markdown",
+        method="GET",
+        path="/api/v1/knowledge-bases/{kb_id}/files/{file_id}/versions/{version_id}/markdown",
+        scope="config",
+        summary="Download the bound Markdown file.",
+        path_params=[
+            _param("kb_id", "integer", True, "Knowledge base ID."),
+            _param("file_id", "integer", True, "File object ID."),
+            _param("version_id", "integer", True, "Version ID."),
+        ],
+        response="Markdown file bytes.",
+        errors=["401 invalid API key", "403 config scope missing", "404 Markdown not found"],
+        example="deepflow_openagent_cli knowledge versions markdown 1 3 4 --output manual.md",
+    ),
+    EndpointDoc(
+        key="knowledge.file_versions.remove_markdown",
+        method="DELETE",
+        path="/api/v1/knowledge-bases/{kb_id}/files/{file_id}/versions/{version_id}/markdown",
+        scope="config",
+        summary="Remove the bound Markdown and parsed content.",
+        path_params=[
+            _param("kb_id", "integer", True, "Knowledge base ID."),
+            _param("file_id", "integer", True, "File object ID."),
+            _param("version_id", "integer", True, "Version ID."),
+        ],
+        response="Updated version detail.",
+        errors=["401 invalid API key", "403 config scope missing", "404 version not found"],
+        example="deepflow_openagent_cli knowledge versions remove-markdown 1 3 4",
+    ),
+    EndpointDoc(
+        key="knowledge.file_versions.reprocess",
+        method="POST",
+        path="/api/v1/knowledge-bases/{kb_id}/files/{file_id}/versions/{version_id}/reprocess",
+        scope="config",
+        summary="Reprocess the bound Markdown.",
+        path_params=[
+            _param("kb_id", "integer", True, "Knowledge base ID."),
+            _param("file_id", "integer", True, "File object ID."),
+            _param("version_id", "integer", True, "Version ID."),
+        ],
+        response="Updated version detail with processing status.",
+        errors=["400 Markdown missing", "401 invalid API key", "403 config scope missing", "404 version not found"],
+        example="deepflow_openagent_cli knowledge versions reprocess 1 3 4",
+    ),
+    EndpointDoc(
+        key="knowledge.file_versions.current",
+        method="POST",
+        path="/api/v1/knowledge-bases/{kb_id}/files/{file_id}/versions/{version_id}/current",
+        scope="config",
+        summary="Set a version as the current searchable version.",
+        path_params=[
+            _param("kb_id", "integer", True, "Knowledge base ID."),
+            _param("file_id", "integer", True, "File object ID."),
+            _param("version_id", "integer", True, "Version ID."),
+        ],
+        response="Updated current version detail.",
+        errors=["401 invalid API key", "403 config scope missing", "404 version not found"],
+        example="deepflow_openagent_cli knowledge versions set-current 1 3 4",
+    ),
+    EndpointDoc(
+        key="knowledge.file_versions.content",
+        method="GET",
+        path="/api/v1/knowledge-bases/{kb_id}/files/{file_id}/versions/{version_id}/content",
+        scope="config",
+        summary="Get parsed Markdown, metadata, TOC, and slices.",
+        path_params=[
+            _param("kb_id", "integer", True, "Knowledge base ID."),
+            _param("file_id", "integer", True, "File object ID."),
+            _param("version_id", "integer", True, "Version ID."),
+        ],
+        response="Processed document content and slices.",
+        errors=["400 processing not ready", "401 invalid API key", "403 config scope missing", "404 version not found"],
+        example="deepflow_openagent_cli knowledge versions content 1 3 4",
+    ),
     EndpointDoc(
         key="documents.query",
         method="POST",
@@ -347,10 +737,11 @@ ENDPOINTS: tuple[EndpointDoc, ...] = (
         method="PUT",
         path="/api/v1/agents/{agent_id}/engine-config",
         scope="config",
-        summary="Partially update system_prompt, model, selected_tool_ids, context, or pre_recall.",
+        summary="Partially update system_prompt, runtime_context, model, selected_tool_ids, context, or pre_recall.",
         path_params=[_param("agent_id", "integer", True, "Agent ID.")],
         body_fields=[
             _param("system_prompt", "string", False, "System prompt, max 30000 chars."),
+            _param("runtime_context", "string", False, "Per-LLM-call runtime context template, max 30000 chars."),
             _param("model", "object", False, "Model config."),
             _param("selected_tool_ids", "array[integer]", False, "Enabled tool IDs."),
             _param("context", "object", False, "Context policy."),
@@ -358,7 +749,7 @@ ENDPOINTS: tuple[EndpointDoc, ...] = (
         ],
         response="AgentResponse with updated engine_config.",
         errors=["401 missing or invalid API key", "403 scope missing", "404 agent not found", "422 validation error"],
-        example="deepflow_openagent_cli agents engine-config 1 --json '{\"system_prompt\":\"You are helpful.\"}'",
+        example="deepflow_openagent_cli agents engine-config 1 --json '{\"runtime_context\":\"Date: {{current_date}}\"}'",
     ),
     EndpointDoc(
         key="tools.list",
@@ -619,6 +1010,82 @@ class OpenApiClient:
         except URLError as exc:
             raise CliError(f"Failed to connect to {url}: {exc.reason}") from exc
 
+    def request_multipart(
+        self,
+        endpoint_key: str,
+        path_params: dict[str, Any],
+        fields: dict[str, str | int | None],
+        files: dict[str, Path | None],
+    ) -> bytes:
+        endpoint = get_endpoint(endpoint_key)
+        if endpoint.scope and not self.api_key:
+            raise CliError(f"Missing API key. Set {ENV_API_KEY} or pass --api-key.")
+
+        url = self._build_url(endpoint, path_params, {})
+        body = MultipartBody(fields, files)
+        headers = {
+            "Accept": "application/json",
+            "Content-Type": body.content_type,
+            "Content-Length": str(body.content_length),
+        }
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        request = Request(url, data=body, headers=headers, method=endpoint.method)
+        try:
+            with urlopen(request) as response:  # noqa: S310 - user-provided API host.
+                return response.read()
+        except HTTPError as exc:
+            payload = exc.read().decode("utf-8", errors="replace")
+            raise CliError(f"HTTP {exc.code} for {endpoint_key}: {payload}") from exc
+        except URLError as exc:
+            raise CliError(f"Failed to connect to {url}: {exc.reason}") from exc
+
+    def download(
+        self,
+        endpoint_key: str,
+        output_path: Path,
+        path_params: dict[str, Any],
+        query: dict[str, Any] | None = None,
+    ) -> int:
+        endpoint = get_endpoint(endpoint_key)
+        if endpoint.scope and not self.api_key:
+            raise CliError(f"Missing API key. Set {ENV_API_KEY} or pass --api-key.")
+        output_path = output_path.expanduser()
+        if not output_path.parent.is_dir():
+            raise CliError(f"Output directory does not exist: {output_path.parent}")
+        if output_path.is_dir():
+            raise CliError(f"Output path is a directory: {output_path}")
+
+        url = self._build_url(endpoint, path_params, query or {})
+        headers = {"Accept": "application/octet-stream"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        request = Request(url, headers=headers, method=endpoint.method)
+        temporary_name: str | None = None
+        try:
+            with urlopen(request) as response:  # noqa: S310 - user-provided API host.
+                with tempfile.NamedTemporaryFile(
+                    mode="wb",
+                    dir=output_path.parent,
+                    prefix=f".{output_path.name}.",
+                    delete=False,
+                ) as temporary:
+                    temporary_name = temporary.name
+                    size = 0
+                    while chunk := response.read(1024 * 1024):
+                        temporary.write(chunk)
+                        size += len(chunk)
+            os.replace(temporary_name, output_path)
+            return size
+        except HTTPError as exc:
+            payload = exc.read().decode("utf-8", errors="replace")
+            raise CliError(f"HTTP {exc.code} for {endpoint_key}: {payload}") from exc
+        except URLError as exc:
+            raise CliError(f"Failed to connect to {url}: {exc.reason}") from exc
+        finally:
+            if temporary_name and os.path.exists(temporary_name):
+                os.unlink(temporary_name)
+
     def _build_url(self, endpoint: EndpointDoc, path_params: dict[str, Any], query: dict[str, Any]) -> str:
         path = endpoint.path
         for param in endpoint.path_params:
@@ -765,6 +1232,51 @@ def run_request(
     return 0
 
 
+def run_multipart_request(
+    args: argparse.Namespace,
+    endpoint_key: str,
+    path_params: dict[str, Any],
+    fields: dict[str, str | int | None],
+    files: dict[str, Path | None],
+) -> int:
+    data = client_from_args(args).request_multipart(
+        endpoint_key,
+        path_params,
+        fields,
+        files,
+    )
+    print_output(data, pretty=args.pretty, raw=args.raw)
+    return 0
+
+
+def run_download(
+    args: argparse.Namespace,
+    endpoint_key: str,
+    path_params: dict[str, Any],
+) -> int:
+    output = Path(args.output).expanduser()
+    size = client_from_args(args).download(
+        endpoint_key,
+        output,
+        path_params,
+        query={"download": True},
+    )
+    payload = json.dumps(
+        {"output": str(output.absolute()), "size": size},
+        ensure_ascii=False,
+    ).encode("utf-8")
+    print_output(payload, pretty=args.pretty, raw=args.raw)
+    return 0
+
+
+def _file_version_path(args: argparse.Namespace) -> dict[str, int]:
+    return {
+        "kb_id": args.kb_id,
+        "file_id": args.file_id,
+        "version_id": args.version_id,
+    }
+
+
 def handle_knowledge(args: argparse.Namespace) -> int:
     if args.knowledge_action == "list":
         return run_request(args, "knowledge.list", query={"page": args.page, "per_page": args.per_page})
@@ -788,6 +1300,124 @@ def handle_knowledge(args: argparse.Namespace) -> int:
                 "line": args.line,
             },
         )
+    if args.knowledge_action == "directories":
+        path = {"kb_id": args.kb_id}
+        if args.directory_action == "list":
+            return run_request(args, "knowledge.file_directories.list", path)
+        if args.directory_action == "create":
+            body = merge_payload(
+                args,
+                {"name": args.name, "parent_id": args.parent_id},
+            )
+            return run_request(args, "knowledge.file_directories.create", path, body=body)
+        path["directory_id"] = args.directory_id
+        if args.directory_action == "update":
+            body = merge_payload(
+                args,
+                {
+                    "name": args.name,
+                    "parent_id": args.parent_id,
+                    "sort_order": args.sort_order,
+                },
+            )
+            return run_request(args, "knowledge.file_directories.update", path, body=body)
+        return run_request(args, "knowledge.file_directories.delete", path)
+    if args.knowledge_action == "files":
+        path = {"kb_id": args.kb_id}
+        if args.file_action == "list":
+            return run_request(
+                args,
+                "knowledge.files.list",
+                path,
+                query={
+                    "directory_id": args.directory_id,
+                    "search": args.search,
+                    "markdown": args.markdown_filter,
+                    "page": args.page,
+                    "per_page": args.per_page,
+                },
+            )
+        if args.file_action == "create":
+            return run_multipart_request(
+                args,
+                "knowledge.files.create",
+                path,
+                fields={
+                    "directory_id": args.directory_id,
+                    "name": args.name,
+                    "custom_version": args.custom_version,
+                    "description": args.description,
+                    "note": args.note,
+                },
+                files={
+                    "original": Path(args.original),
+                    "markdown": Path(args.markdown) if args.markdown else None,
+                },
+            )
+        path["file_id"] = args.file_id
+        if args.file_action == "get":
+            return run_request(
+                args,
+                "knowledge.files.get",
+                path,
+                query={"markdown": args.markdown_filter},
+            )
+        if args.file_action == "update":
+            body = merge_payload(
+                args,
+                {
+                    "name": args.name,
+                    "description": args.description,
+                    "directory_id": args.directory_id,
+                },
+            )
+            return run_request(args, "knowledge.files.update", path, body=body)
+        return run_request(args, "knowledge.files.delete", path)
+    if args.knowledge_action == "versions":
+        if args.version_action == "upload":
+            return run_multipart_request(
+                args,
+                "knowledge.file_versions.create",
+                {"kb_id": args.kb_id, "file_id": args.file_id},
+                fields={
+                    "custom_version": args.custom_version,
+                    "note": args.note,
+                },
+                files={
+                    "original": Path(args.original),
+                    "markdown": Path(args.markdown) if args.markdown else None,
+                },
+            )
+        path = _file_version_path(args)
+        if args.version_action == "get":
+            return run_request(args, "knowledge.file_versions.get", path)
+        if args.version_action == "update":
+            body = merge_payload(
+                args,
+                {"custom_version": args.custom_version, "note": args.note},
+            )
+            return run_request(args, "knowledge.file_versions.update", path, body=body)
+        if args.version_action == "delete":
+            return run_request(args, "knowledge.file_versions.delete", path)
+        if args.version_action == "original":
+            return run_download(args, "knowledge.file_versions.original", path)
+        if args.version_action == "attach-markdown":
+            return run_multipart_request(
+                args,
+                "knowledge.file_versions.attach_markdown",
+                path,
+                fields={},
+                files={"markdown": Path(args.markdown)},
+            )
+        if args.version_action == "markdown":
+            return run_download(args, "knowledge.file_versions.markdown", path)
+        endpoint = {
+            "remove-markdown": "knowledge.file_versions.remove_markdown",
+            "reprocess": "knowledge.file_versions.reprocess",
+            "set-current": "knowledge.file_versions.current",
+            "content": "knowledge.file_versions.content",
+        }[args.version_action]
+        return run_request(args, endpoint, path)
     return run_request(args, "knowledge.markdown", {"kb_id": args.kb_id, "doc_id": args.doc_id})
 
 
@@ -1010,6 +1640,113 @@ def build_parser() -> argparse.ArgumentParser:
     knowledge_markdown = knowledge_sub.add_parser("markdown")
     knowledge_markdown.add_argument("kb_id", type=int)
     knowledge_markdown.add_argument("doc_id", type=int)
+
+    knowledge_directories = knowledge_sub.add_parser("directories")
+    directory_sub = knowledge_directories.add_subparsers(
+        dest="directory_action", required=True
+    )
+    directory_list = directory_sub.add_parser("list")
+    directory_list.add_argument("kb_id", type=int)
+    directory_create = directory_sub.add_parser("create")
+    directory_create.add_argument("kb_id", type=int)
+    directory_create.add_argument("--name", required=True)
+    directory_create.add_argument("--parent-id", type=int)
+    add_json_args(directory_create)
+    directory_update = directory_sub.add_parser("update")
+    directory_update.add_argument("kb_id", type=int)
+    directory_update.add_argument("directory_id", type=int)
+    directory_update.add_argument("--name")
+    directory_update.add_argument("--parent-id", type=int)
+    directory_update.add_argument("--sort-order", type=int)
+    add_json_args(directory_update)
+    directory_delete = directory_sub.add_parser("delete")
+    directory_delete.add_argument("kb_id", type=int)
+    directory_delete.add_argument("directory_id", type=int)
+
+    knowledge_files = knowledge_sub.add_parser("files")
+    file_sub = knowledge_files.add_subparsers(dest="file_action", required=True)
+    file_list = file_sub.add_parser("list")
+    file_list.add_argument("kb_id", type=int)
+    file_list.add_argument("--directory-id", type=int)
+    file_list.add_argument("--search")
+    file_list.add_argument(
+        "--markdown-filter",
+        choices=["all", "missing-current", "has-missing", "complete"],
+    )
+    file_list.add_argument("--page", type=int)
+    file_list.add_argument("--per-page", type=int)
+    file_create = file_sub.add_parser("create")
+    file_create.add_argument("kb_id", type=int)
+    file_create.add_argument("--directory-id", type=int, required=True)
+    file_create.add_argument("--name", required=True)
+    file_create.add_argument("--custom-version", required=True)
+    file_create.add_argument("--description")
+    file_create.add_argument("--note")
+    file_create.add_argument("--original", required=True)
+    file_create.add_argument("--markdown")
+    file_get = file_sub.add_parser("get")
+    file_get.add_argument("kb_id", type=int)
+    file_get.add_argument("file_id", type=int)
+    file_get.add_argument(
+        "--markdown-filter",
+        choices=["all", "missing", "bound", "processing", "ready", "failed"],
+    )
+    file_update = file_sub.add_parser("update")
+    file_update.add_argument("kb_id", type=int)
+    file_update.add_argument("file_id", type=int)
+    file_update.add_argument("--name")
+    file_update.add_argument("--description")
+    file_update.add_argument("--directory-id", type=int)
+    add_json_args(file_update)
+    file_delete = file_sub.add_parser("delete")
+    file_delete.add_argument("kb_id", type=int)
+    file_delete.add_argument("file_id", type=int)
+
+    knowledge_versions = knowledge_sub.add_parser("versions")
+    version_sub = knowledge_versions.add_subparsers(
+        dest="version_action", required=True
+    )
+    version_upload = version_sub.add_parser("upload")
+    version_upload.add_argument("kb_id", type=int)
+    version_upload.add_argument("file_id", type=int)
+    version_upload.add_argument("--custom-version", required=True)
+    version_upload.add_argument("--note")
+    version_upload.add_argument("--original", required=True)
+    version_upload.add_argument("--markdown")
+    for action in [
+        "get",
+        "delete",
+        "remove-markdown",
+        "reprocess",
+        "set-current",
+        "content",
+    ]:
+        version_parser = version_sub.add_parser(action)
+        version_parser.add_argument("kb_id", type=int)
+        version_parser.add_argument("file_id", type=int)
+        version_parser.add_argument("version_id", type=int)
+    version_update = version_sub.add_parser("update")
+    version_update.add_argument("kb_id", type=int)
+    version_update.add_argument("file_id", type=int)
+    version_update.add_argument("version_id", type=int)
+    version_update.add_argument("--custom-version")
+    version_update.add_argument("--note")
+    add_json_args(version_update)
+    version_original = version_sub.add_parser("original")
+    version_original.add_argument("kb_id", type=int)
+    version_original.add_argument("file_id", type=int)
+    version_original.add_argument("version_id", type=int)
+    version_original.add_argument("--output", required=True)
+    version_attach = version_sub.add_parser("attach-markdown")
+    version_attach.add_argument("kb_id", type=int)
+    version_attach.add_argument("file_id", type=int)
+    version_attach.add_argument("version_id", type=int)
+    version_attach.add_argument("--markdown", required=True)
+    version_markdown = version_sub.add_parser("markdown")
+    version_markdown.add_argument("kb_id", type=int)
+    version_markdown.add_argument("file_id", type=int)
+    version_markdown.add_argument("version_id", type=int)
+    version_markdown.add_argument("--output", required=True)
     knowledge.set_defaults(handler=handle_knowledge)
 
     conversations = subparsers.add_parser("conversations", help="Conversation endpoints.")

{deepflow_openagent_cli-0.1.4 → deepflow_openagent_cli-0.1.5}/src/deepflow_openagent_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepflow-openagent-cli
-Version: 0.1.4
+Version: 0.1.5
 Summary: Command-line client for OpenAgent OpenAPI (agents, conversations, SSE chat, tools, channels, knowledge bases).
 Author: DeepFlow AI
 Project-URL: Repository, https://github.com/DeepFlowAI/OpenAgent
@@ -66,6 +66,21 @@ deepflow_openagent_cli docs show chat.stream --json
 deepflow_openagent_cli knowledge list --page 1 --per-page 10
 deepflow_openagent_cli knowledge documents 1
 deepflow_openagent_cli knowledge query-document 6670 --slice-id 512208 --line 1720
+
+# Knowledge-base file library (requires config scope)
+deepflow_openagent_cli knowledge directories create 1 --name "Policies"
+deepflow_openagent_cli knowledge files create 1 \
+  --directory-id 2 --name "Product Manual" --custom-version v1 \
+  --original ./manual.pdf --markdown ./manual.md
+deepflow_openagent_cli knowledge files list 1 --markdown-filter has-missing
+deepflow_openagent_cli knowledge versions upload 1 3 \
+  --custom-version v2 --original ./manual-v2.pdf
+deepflow_openagent_cli knowledge versions attach-markdown 1 3 4 \
+  --markdown ./manual-v2.md
+deepflow_openagent_cli knowledge versions set-current 1 3 4
+deepflow_openagent_cli knowledge versions original 1 3 4 --output ./manual-v2.pdf
+deepflow_openagent_cli knowledge versions markdown 1 3 4 --output ./manual-v2.md
+
 deepflow_openagent_cli chat 1 --message "Hello"
 deepflow_openagent_cli steps 1 42
 deepflow_openagent_cli steps get 1 42 100

{deepflow_openagent_cli-0.1.4 → deepflow_openagent_cli-0.1.5}/tests/test_cli.py

@@ -8,6 +8,7 @@ from deepflow_openagent_cli import __version__
 from deepflow_openagent_cli.cli import (
     CliError,
     ENDPOINTS,
+    MultipartBody,
     OpenApiClient,
     build_parser,
     client_from_args,
@@ -30,12 +31,26 @@ def test_catalog_has_stable_unique_keys() -> None:
     assert len(keys) == len(set(keys))
     assert "knowledge.list" in keys
     assert "knowledge.documents" in keys
+    assert "knowledge.files.create" in keys
+    assert "knowledge.file_versions.attach_markdown" in keys
     assert "documents.query" in keys
     assert "chat.stream" in keys
     assert "steps.get" in keys
     assert "channels.secret_key" in keys
 
 
+def test_agent_engine_config_docs_include_runtime_context() -> None:
+    endpoint = get_endpoint("agents.engine_config")
+
+    runtime_context = next(
+        field for field in endpoint.body_fields if field.name == "runtime_context"
+    )
+    assert runtime_context.type == "string"
+    assert runtime_context.required is False
+    assert "runtime_context" in endpoint.summary
+    assert "runtime_context" in endpoint.example
+
+
 def test_get_endpoint_unknown_key_raises_clear_error() -> None:
     with pytest.raises(CliError, match="Unknown endpoint"):
         get_endpoint("missing.endpoint")
@@ -59,6 +74,29 @@ def test_build_url_formats_path_and_query() -> None:
     assert url == "http://localhost:5001/api/v1/knowledge-bases/1/documents?page=2&per_page=20"
 
 
+def test_multipart_body_streams_fields_and_files(tmp_path: Path) -> None:
+    original = tmp_path / "manual.pdf"
+    original.write_bytes(b"pdf-content")
+    body = MultipartBody(
+        {"name": "Manual", "directory_id": 2, "description": None},
+        {"original": original, "markdown": None},
+    )
+
+    payload = b"".join(body)
+
+    assert len(payload) == body.content_length
+    assert b'name="name"' in payload
+    assert b"Manual" in payload
+    assert b'name="original"; filename="manual.pdf"' in payload
+    assert b"pdf-content" in payload
+    assert body.content_type.startswith("multipart/form-data; boundary=openagent-")
+
+
+def test_multipart_body_rejects_missing_file(tmp_path: Path) -> None:
+    with pytest.raises(CliError, match="Upload file does not exist"):
+        MultipartBody({}, {"original": tmp_path / "missing.pdf"})
+
+
 def test_client_from_args_reads_openagent_env(monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.setenv("OPENAGENT_HOST", "https://api.example.com")
     monkeypatch.setenv("OPENAGENT_API_KEY", "sk-openagent")
@@ -135,6 +173,97 @@ def test_query_document_command_posts_body(
     ]
 
 
+def test_create_knowledge_file_posts_multipart(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    tmp_path: Path,
+) -> None:
+    original = tmp_path / "manual.pdf"
+    markdown = tmp_path / "manual.md"
+    original.write_bytes(b"pdf")
+    markdown.write_text("# Manual", encoding="utf-8")
+    calls = []
+
+    def fake_request_multipart(self, endpoint_key, path_params, fields, files):
+        calls.append((endpoint_key, path_params, fields, files))
+        return b'{"id": 3}'
+
+    monkeypatch.setattr(OpenApiClient, "request_multipart", fake_request_multipart)
+
+    exit_code = main(
+        [
+            "--api-key",
+            "sk-test",
+            "knowledge",
+            "files",
+            "create",
+            "1",
+            "--directory-id",
+            "2",
+            "--name",
+            "Manual",
+            "--custom-version",
+            "v1",
+            "--original",
+            str(original),
+            "--markdown",
+            str(markdown),
+        ]
+    )
+
+    captured = capsys.readouterr()
+    assert exit_code == 0
+    assert json.loads(captured.out) == {"id": 3}
+    assert calls == [
+        (
+            "knowledge.files.create",
+            {"kb_id": 1},
+            {
+                "directory_id": 2,
+                "name": "Manual",
+                "custom_version": "v1",
+                "description": None,
+                "note": None,
+            },
+            {"original": original, "markdown": markdown},
+        )
+    ]
+
+
+def test_download_version_original_writes_output_atomically(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    class FakeResponse:
+        def __init__(self) -> None:
+            self.chunks = [b"first", b"second", b""]
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *_args):
+            return False
+
+        def read(self, _size: int) -> bytes:
+            return self.chunks.pop(0)
+
+    monkeypatch.setattr(
+        "deepflow_openagent_cli.cli.urlopen",
+        lambda _request: FakeResponse(),
+    )
+    output = tmp_path / "manual.pdf"
+
+    size = OpenApiClient("http://localhost:5001", "sk-test").download(
+        "knowledge.file_versions.original",
+        output,
+        {"kb_id": 1, "file_id": 2, "version_id": 3},
+    )
+
+    assert size == 11
+    assert output.read_bytes() == b"firstsecond"
+    assert list(tmp_path.iterdir()) == [output]
+
+
 def test_steps_list_keeps_legacy_short_form(
     monkeypatch: pytest.MonkeyPatch,
     capsys: pytest.CaptureFixture[str],