inkcre-cli 0.1.0__tar.gz

inkcre_cli-0.1.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: inkcre-cli
+Version: 0.1.0
+Summary: An agent-friendly REST interface to InKCre
+License-Expression: GPL-3.0-only
+Project-URL: Repository, https://github.com/InKCre/core-py
+Requires-Python: >=3.12
+Requires-Dist: click<9,>=8.1
+Requires-Dist: pydantic<3,>=2.10
+Requires-Dist: httpx<0.29,>=0.28.1
+Requires-Dist: PyJWT<3,>=2.10
+Description-Content-Type: text/markdown
+
+# inkcre-cli
+
+InKCre 的独立命令行界面，通过 Core REST API 检索信息、读取 Resolver 内容和管理部署。
+它不安装 Core、不访问数据库，也不是执行 Job 的 Peer。
+
+```sh
+python -m pip install inkcre-cli
+inkcre-cli --help
+inkcre-cli connection set personal --input connection.json
+inkcre-cli recall 'Agent 工具' --mode lexical --json
+inkcre-cli get block:42 relation:8 --json
+inkcre-cli resolver invoke block:42 --method get_solved_content
+```
+
+connection.json 包含 `base_url` 与 `jwt_secret`。默认连接文件是
+`~/.inkcre/cli/connections.json`；可用 `--connections-file` 指定隔离文件。
+这里的地址是 Core REST 入口，不是 PostgREST 或 MCP endpoint。
+首个连接自动成为默认连接；`connection use personal` 修改默认值，`--connection NAME` 只选择本次接入。
+
+`--help` 离线可用；有结构化输入的命令提供 `--schema`，从当前 Core 发现准确合同。
+使用 `--input FILE`、`--input -` 或 `--input-json JSON` 提供输入。
+`--json` 输出完整紧凑 JSON；二进制内容保存为文件，不做 Base64 编码。
+`--output-dir DIR` 显式保存完整结果，stdout 返回入口文件路径。
+
+## 发现与管理
+
+先发现 exact type、method 或 schema，再提交它所描述的输入。例如：
+
+```sh
+inkcre-cli source types --json
+inkcre-cli source create --type SOURCE_TYPE --schema
+inkcre-cli source create --type SOURCE_TYPE --input source.json
+inkcre-cli source collect 42 --input-json '{}'
+inkcre-cli job wait 17 --for 10s --json
+inkcre-cli job abort 17
+inkcre-cli cron create --job-type core.source.collect.v1 --schema
+inkcre-cli agent tools --json
+inkcre-cli ai models --json
+inkcre-cli config schemas --json
+```
+
+这里的 ID 仅为示例，应使用实际创建回执或查询返回的 ID。`source collect`、`source backfill` 和
+`organization ruminate` 创建 Job，而不是在 CLI 或接入 Core 中同步执行。`job wait --for 10s` 最多观察
+十秒，可能返回仍为 pending/running 的记录；停止观察不取消 Job。`job abort` 请求 best-effort 停止，
+`abort_requested: true` 不代表执行端已经完成清理。只有后续记录才能说明实际结果。
+
+`connection` 只管理本机连接，`config` 管理远端 deployment config；Agent definition 由 `agent` 管理，
+模型目录由 `ai` 发现。Extension 配置和运行目标使用 `extension`，不混入 connection。
+
+## 输出与续读
+
+结果写 stdout，命令错误写 stderr。退出码 0 表示命令成功，1 表示远端/IO/部分结果失败，2 表示本机输入
+错误，130 表示观察被中断。读取一个状态为 failed 的 Job 仍是成功读取，脚本应检查 Job 的实际 status。
+批量读取与混合 recall 保留各项结果，不因一项失败丢弃其它成功项。
+
+支持分页的目录使用 `--limit`、`--cursor` 和返回的 `next_cursor`；CLI 不自动翻页。
+检索仍保留各模式自身的 limit 和结果结构，混合 recall 不融合排名。
+
+人类可读输出过长时显示摘要和完整文件路径；`--json` 不截断、不 pretty-print。
+二进制自动保存为文件；显式 `--output-dir DIR` 导出的入口 JSON 使用相对文件引用，整个子目录可以搬移。
+这些是同一次 HTTP 响应的本地文件，不是新下载会话，也不会再次调用 Resolver。
+
+开发使用独立 PDM 项目：`pdm install -p cli`、`pdm run -p cli check`、`pdm build -p cli`。
+0.0.0 是未发布的开发版本；首次发行由仓库的 Release PR 准备。

inkcre_cli-0.1.0/README.md

@@ -0,0 +1,64 @@
+# inkcre-cli
+
+InKCre 的独立命令行界面，通过 Core REST API 检索信息、读取 Resolver 内容和管理部署。
+它不安装 Core、不访问数据库，也不是执行 Job 的 Peer。
+
+```sh
+python -m pip install inkcre-cli
+inkcre-cli --help
+inkcre-cli connection set personal --input connection.json
+inkcre-cli recall 'Agent 工具' --mode lexical --json
+inkcre-cli get block:42 relation:8 --json
+inkcre-cli resolver invoke block:42 --method get_solved_content
+```
+
+connection.json 包含 `base_url` 与 `jwt_secret`。默认连接文件是
+`~/.inkcre/cli/connections.json`；可用 `--connections-file` 指定隔离文件。
+这里的地址是 Core REST 入口，不是 PostgREST 或 MCP endpoint。
+首个连接自动成为默认连接；`connection use personal` 修改默认值，`--connection NAME` 只选择本次接入。
+
+`--help` 离线可用；有结构化输入的命令提供 `--schema`，从当前 Core 发现准确合同。
+使用 `--input FILE`、`--input -` 或 `--input-json JSON` 提供输入。
+`--json` 输出完整紧凑 JSON；二进制内容保存为文件，不做 Base64 编码。
+`--output-dir DIR` 显式保存完整结果，stdout 返回入口文件路径。
+
+## 发现与管理
+
+先发现 exact type、method 或 schema，再提交它所描述的输入。例如：
+
+```sh
+inkcre-cli source types --json
+inkcre-cli source create --type SOURCE_TYPE --schema
+inkcre-cli source create --type SOURCE_TYPE --input source.json
+inkcre-cli source collect 42 --input-json '{}'
+inkcre-cli job wait 17 --for 10s --json
+inkcre-cli job abort 17
+inkcre-cli cron create --job-type core.source.collect.v1 --schema
+inkcre-cli agent tools --json
+inkcre-cli ai models --json
+inkcre-cli config schemas --json
+```
+
+这里的 ID 仅为示例，应使用实际创建回执或查询返回的 ID。`source collect`、`source backfill` 和
+`organization ruminate` 创建 Job，而不是在 CLI 或接入 Core 中同步执行。`job wait --for 10s` 最多观察
+十秒，可能返回仍为 pending/running 的记录；停止观察不取消 Job。`job abort` 请求 best-effort 停止，
+`abort_requested: true` 不代表执行端已经完成清理。只有后续记录才能说明实际结果。
+
+`connection` 只管理本机连接，`config` 管理远端 deployment config；Agent definition 由 `agent` 管理，
+模型目录由 `ai` 发现。Extension 配置和运行目标使用 `extension`，不混入 connection。
+
+## 输出与续读
+
+结果写 stdout，命令错误写 stderr。退出码 0 表示命令成功，1 表示远端/IO/部分结果失败，2 表示本机输入
+错误，130 表示观察被中断。读取一个状态为 failed 的 Job 仍是成功读取，脚本应检查 Job 的实际 status。
+批量读取与混合 recall 保留各项结果，不因一项失败丢弃其它成功项。
+
+支持分页的目录使用 `--limit`、`--cursor` 和返回的 `next_cursor`；CLI 不自动翻页。
+检索仍保留各模式自身的 limit 和结果结构，混合 recall 不融合排名。
+
+人类可读输出过长时显示摘要和完整文件路径；`--json` 不截断、不 pretty-print。
+二进制自动保存为文件；显式 `--output-dir DIR` 导出的入口 JSON 使用相对文件引用，整个子目录可以搬移。
+这些是同一次 HTTP 响应的本地文件，不是新下载会话，也不会再次调用 Resolver。
+
+开发使用独立 PDM 项目：`pdm install -p cli`、`pdm run -p cli check`、`pdm build -p cli`。
+0.0.0 是未发布的开发版本；首次发行由仓库的 Release PR 准备。

inkcre_cli-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[project]
+name = "inkcre-cli"
+version = "0.1.0"
+description = "An agent-friendly REST interface to InKCre"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "GPL-3.0-only"
+dependencies = [
+    "click>=8.1,<9",
+    "pydantic>=2.10,<3",
+    "httpx>=0.28.1,<0.29",
+    "PyJWT>=2.10,<3",
+]
+
+[project.scripts]
+inkcre-cli = "inkcre_cli.main:main"
+
+[project.urls]
+Repository = "https://github.com/InKCre/core-py"
+
+[build-system]
+requires = [
+    "pdm-backend",
+]
+build-backend = "pdm.backend"
+
+[dependency-groups]
+dev = [
+    "ruff>=0.15,<0.16",
+    "pyrefly>=0.56,<0.57",
+]
+
+[tool.pdm]
+distribution = true
+
+[tool.pdm.scripts]
+lint = "ruff check src"
+format = "ruff format src"
+"format:check" = "ruff format --check src"
+typecheck = "pyrefly check"
+
+[tool.pdm.scripts.check]
+composite = [
+    "lint",
+    "format:check",
+    "typecheck",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+]
+
+[tool.pyrefly]
+project-includes = [
+    "src",
+]

inkcre_cli-0.1.0/src/inkcre_cli/__init__.py

@@ -0,0 +1 @@
+"""Independent InKCre REST consumer; no Core runtime imports."""

inkcre_cli-0.1.0/src/inkcre_cli/command.py

@@ -0,0 +1,187 @@
+"""Small shared Click options and one invocation's resources."""
+
+import sys
+from pathlib import Path
+from typing import Any, Literal
+from urllib.parse import quote
+
+import click
+from pydantic import BaseModel, TypeAdapter
+
+from . import connection
+from .errors import CommandError
+from .http import CoreRESTClient
+from .output import Output
+
+
+class Command(click.Command):
+    def parse_args(self, ctx: click.Context, args: list[str]) -> list[str]:
+        original = args.copy()
+        try:
+            return super().parse_args(ctx, args)
+        except click.UsageError:
+            # Click rejects unknown options before eager callbacks run. Its native
+            # tolerant parse can still find presentation options without scanning
+            # raw argv (which would mistake an --input-json value for an option).
+            with self.make_context(
+                ctx.info_name,
+                original,
+                parent=ctx.parent,
+                obj=ctx.obj,
+                resilient_parsing=True,
+                ignore_unknown_options=True,
+            ):
+                pass
+            raise
+
+
+class Group(Command, click.Group):
+    command_class = Command
+    group_class = type
+
+
+class Entity(BaseModel):
+    type: Literal["block", "relation"]
+    id: int
+
+
+def entity(value: str, *, block_only: bool = False) -> Entity:
+    kind, separator, identity = value.partition(":")
+    if not separator:
+        raise click.BadParameter("使用 block:<id> 或 relation:<id>")
+    result = Entity.model_validate({"type": kind, "id": identity})
+    if block_only and result.type != "block":
+        raise click.BadParameter("此操作需要 block:<id>")
+    return result
+
+
+def segment(value: str | int) -> str:
+    return quote(str(value), safe="")
+
+
+def duration(value: str) -> float:
+    suffix = value[-1:] if value[-1:].isalpha() else ""
+    scale = {"": 1, "s": 1, "m": 60, "h": 3600}
+    try:
+        result = float(value[:-1] if suffix else value) * scale[suffix]
+        if not 0 < result < float("inf"):
+            raise ValueError
+        return result
+    except (ValueError, KeyError) as error:
+        raise click.BadParameter("使用正数秒，或 30s / 2m / 1h") from error
+
+
+class Invocation:
+    def __init__(self):
+        self.connection_name: str | None = None
+        self.connections_file: Path | None = None
+        self.output = Output()
+        self._client: CoreRESTClient | None = None
+
+    @property
+    def local_file(self) -> Path:
+        return connection.file_path(self.connections_file)
+
+    @property
+    def client(self) -> CoreRESTClient:
+        if self._client is None:
+            _, selected = connection.select(connection.load(self.local_file), self.connection_name)
+            self._client = CoreRESTClient(selected)
+        return self._client
+
+    def close(self) -> None:
+        if self._client:
+            self._client.close()
+
+    def send(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict | None = None,
+        body: Any = None,
+        strip: tuple[str, ...] = (),
+        selectors: dict[str, str] | None = None,
+    ) -> Any:
+        try:
+            return self.client.request(method, path, params=params, body=body)
+        except CommandError as error:
+            if error.status == 422 and isinstance(error.detail, list):
+                detail = []
+                for item in error.detail:
+                    loc = list(item.get("loc", ()))
+                    if loc[:1] == ["body"]:
+                        loc = loc[1:]
+                        if loc[: len(strip)] == list(strip):
+                            loc = loc[len(strip) :]
+                        if loc and selectors and loc[0] in selectors:
+                            loc[0] = selectors[loc[0]]
+                    detail.append({**item, "loc": loc})
+                raise CommandError(detail, status=error.status) from error
+            raise
+
+    def show(self, value: Any, *, no_content: bool = False, partial_failure: bool = False) -> None:
+        self.output.emit(value, no_content=no_content)
+        if partial_failure:
+            raise CommandError("结果中存在逐项错误；成功项已保留")
+
+
+def _option(ctx: click.Context, parameter: click.Parameter, value: Any) -> Any:
+    invocation = ctx.ensure_object(Invocation)
+    if value is not None:
+        if parameter.name == "json_mode":
+            invocation.output.json_mode = value
+        elif parameter.name == "output_dir":
+            invocation.output.directory = value
+        else:
+            setattr(invocation, parameter.name, value)
+    return value
+
+
+def common(function):
+    options: list[tuple[tuple[str, ...], dict[str, Any]]] = [
+        (("--connection", "connection_name"), {"help": "本次使用的本机连接名"}),
+        (("--connections-file",), {"type": click.Path(path_type=Path), "help": "替换连接配置文件"}),
+        (
+            ("--output-dir",),
+            {"type": click.Path(path_type=Path), "help": "保存完整结果，返回入口文件"},
+        ),
+        (
+            ("--json", "json_mode"),
+            {"is_flag": True, "default": None, "is_eager": True, "help": "完整紧凑 JSON"},
+        ),
+    ]
+    for args, kwargs in options:
+        function = click.option(*args, callback=_option, expose_value=False, **kwargs)(function)
+    return function
+
+
+def input_options(function):
+    function = click.option("--schema", is_flag=True, help="只查询输入 JSON Schema，不执行操作")(
+        function
+    )
+    function = click.option("--input-json", help="直接提供 JSON 对象")(function)
+    return click.option(
+        "--input", "input_file", type=click.Path(path_type=Path), help="JSON 文件，- 表示 stdin"
+    )(function)
+
+
+def paging(function):
+    function = click.option("--cursor", help="前一页返回的 next_cursor；保留相同过滤条件")(function)
+    return click.option(
+        "--limit", type=click.IntRange(min=1), help="本次最多返回多少项；不自动翻页"
+    )(function)
+
+
+def load_input(input_file: Path | None, input_json: str | None) -> dict[str, Any]:
+    if input_file is not None and input_json is not None:
+        raise click.UsageError("--input 与 --input-json 不能同时使用")
+    if input_file is not None:
+        text = (
+            sys.stdin.read() if str(input_file) == "-" else input_file.read_text(encoding="utf-8")
+        )
+    elif input_json is not None:
+        text = input_json
+    else:
+        return {}
+    return TypeAdapter(dict[str, Any]).validate_json(text)

inkcre_cli-0.1.0/src/inkcre_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""Ordinary command groups, not an Extension command registry."""

inkcre_cli-0.1.0/src/inkcre_cli/commands/agent.py

@@ -0,0 +1,121 @@
+"""Agent definitions and read-only AI/profile discovery."""
+
+import click
+
+from ..command import Group, Invocation, common, input_options, load_input, paging, segment
+from ..schema import request_schema
+
+
+@click.group(cls=Group)
+def agent():
+    """管理 Agent definition；不启动对话或本机 Agent runtime。"""
+
+
+@agent.command("list")
+@paging
+@common
+@click.pass_obj
+def list_agents(inv: Invocation, limit, cursor):
+    """列出 Agent definition。"""
+    inv.show(inv.send("GET", "/agents", params={"limit": limit, "cursor": cursor}))
+
+
+@agent.command()
+@click.argument("agent_id", type=int)
+@common
+@click.pass_obj
+def get(inv: Invocation, agent_id):
+    """读取一个 Agent definition。"""
+    inv.show(inv.send("GET", f"/agents/{agent_id}"))
+
+
+@agent.command()
+@input_options
+@common
+@click.pass_obj
+def create(inv: Invocation, schema, input_file, input_json):
+    """创建 Agent definition；模型用 ai models、工具用 agent tools 发现。"""
+    if schema:
+        return inv.show(request_schema(inv.client, "/agents", "POST"))
+    inv.show(inv.send("POST", "/agents", body=load_input(input_file, input_json)))
+
+
+@agent.command()
+@click.argument("agent_id", type=int)
+@input_options
+@common
+@click.pass_obj
+def update(inv: Invocation, agent_id, schema, input_file, input_json):
+    """修改提交的 Agent definition 字段。"""
+    if schema:
+        return inv.show(request_schema(inv.client, "/agents/{agent_id}", "PATCH"))
+    inv.show(inv.send("PATCH", f"/agents/{agent_id}", body=load_input(input_file, input_json)))
+
+
+@agent.command()
+@click.argument("agent_id", type=int)
+@common
+@click.pass_obj
+def delete(inv: Invocation, agent_id):
+    """删除 Agent definition。"""
+    inv.show(inv.send("DELETE", f"/agents/{agent_id}"), no_content=True)
+
+
+@agent.command()
+@click.argument("tool_id", required=False)
+@paging
+@common
+@click.pass_obj
+def tools(inv: Invocation, tool_id, limit, cursor):
+    """列出本机已注册 Agent Tool；给定 ID 时取得完整合同，不执行工具。"""
+    inv.show(
+        inv.send(
+            "GET",
+            "/agent-tools" + ("/" + segment(tool_id) if tool_id else ""),
+            params={"limit": limit, "cursor": cursor},
+        )
+    )
+
+
+@click.group(cls=Group)
+def ai():
+    """发现 AI 模型，不混入 Agent definition 的管理范围。"""
+
+
+@ai.command()
+@click.argument("model_id", type=int, required=False)
+@paging
+@common
+@click.pass_obj
+def models(inv: Invocation, model_id, limit, cursor):
+    """列出 AIModel，或读取指定 ID；不返回 Provider 的 secret config。"""
+    inv.show(
+        inv.send(
+            "GET",
+            "/ai/models" + (f"/{model_id}" if model_id is not None else ""),
+            params={"limit": limit, "cursor": cursor},
+        )
+    )
+
+
+@click.group("embedding-profile", cls=Group)
+def embedding_profile():
+    """只读发现语义检索可选的 embedding profile。"""
+
+
+@embedding_profile.command("list")
+@paging
+@common
+@click.pass_obj
+def list_profiles(inv: Invocation, limit, cursor):
+    """列出 EmbeddingProfile。"""
+    inv.show(inv.send("GET", "/embedding-profiles", params={"limit": limit, "cursor": cursor}))
+
+
+@embedding_profile.command("get")
+@click.argument("profile_id", type=int)
+@common
+@click.pass_obj
+def get_profile(inv: Invocation, profile_id):
+    """读取 EmbeddingProfile。"""
+    inv.show(inv.send("GET", f"/embedding-profiles/{profile_id}"))

inkcre_cli-0.1.0/src/inkcre_cli/commands/config.py

@@ -0,0 +1,95 @@
+"""Deployment config values and their runtime-owned input schemas."""
+
+import click
+
+from ..command import Group, Invocation, common, input_options, load_input, paging, segment
+from ..schema import partial
+
+
+@click.group(cls=Group)
+def config():
+    """远端 deployment 配置，与本机 connection 文件分开。"""
+
+
+@config.command("list")
+@paging
+@common
+@click.pass_obj
+def list_configs(inv: Invocation, limit, cursor):
+    """列出保存的 deployment config，不要求 schema 已加载。"""
+    inv.show(inv.send("GET", "/configs", params={"limit": limit, "cursor": cursor}))
+
+
+@config.command()
+@click.argument("key")
+@common
+@click.pass_obj
+def get(inv: Invocation, key):
+    """读取配置的实际 schema/value。"""
+    inv.show(inv.send("GET", "/configs/" + segment(key)))
+
+
+@config.command()
+@click.argument("schema_id", required=False)
+@paging
+@common
+@click.pass_obj
+def schemas(inv: Invocation, schema_id, limit, cursor):
+    """发现接入 Peer 已加载的 schema；给出 ID 时读取输入合同。"""
+    inv.show(
+        inv.send(
+            "GET",
+            "/config-schemas" + ("/" + segment(schema_id) if schema_id else ""),
+            params={"limit": limit, "cursor": cursor},
+        )
+    )
+
+
+@config.command()
+@click.argument("key")
+@click.option("--schema-id", required=True)
+@input_options
+@common
+@click.pass_obj
+def replace(inv: Invocation, key, schema_id, schema, input_file, input_json):
+    """创建或完整替换；JSON 是 value 本身，不再包装 value。"""
+    if schema:
+        return inv.show(inv.send("GET", "/config-schemas/" + segment(schema_id))["input_schema"])
+    inv.show(
+        inv.send(
+            "PUT",
+            "/configs/" + segment(key),
+            body={
+                "schema": schema_id,
+                "value": load_input(input_file, input_json),
+            },
+            strip=("value",),
+            selectors={"schema": "--schema-id"},
+        )
+    )
+
+
+@config.command()
+@click.argument("key")
+@input_options
+@common
+@click.pass_obj
+def update(inv: Invocation, key, schema, input_file, input_json):
+    """更新 value 的提交字段；嵌套值按 owner 合同处理。"""
+    if schema:
+        existing = inv.send("GET", "/configs/" + segment(key))
+        return inv.show(
+            partial(
+                inv.send("GET", "/config-schemas/" + segment(existing["schema"]))["input_schema"]
+            )
+        )
+    inv.show(inv.send("PATCH", "/configs/" + segment(key), body=load_input(input_file, input_json)))
+
+
+@config.command()
+@click.argument("key")
+@common
+@click.pass_obj
+def delete(inv: Invocation, key):
+    """删除保存的配置值。"""
+    inv.show(inv.send("DELETE", "/configs/" + segment(key)), no_content=True)