yuxi-cli 0.1.0__tar.gz

yuxi_cli-0.1.0/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: yuxi-cli
+Version: 0.1.0
+Summary: Yuxi command line client
+Author: Wenjie Zhang
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/xerrors/Yuxi
+Project-URL: Repository, https://github.com/xerrors/Yuxi
+Project-URL: Issues, https://github.com/xerrors/Yuxi/issues
+Keywords: yuxi,cli,rag,knowledge-base,agent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Requires-Dist: langfuse>=4.0.0
+Requires-Dist: packaging>=24
+Requires-Dist: questionary>=2.1.0
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.16
+
+# yuxi-cli
+
+Yuxi command line client.
+
+First-stage scope:
+
+- remote management through `~/.yuxi/config.toml`
+- browser login
+- API Key import through `--api-key`
+- `whoami`, `status`, and `logout`
+- server discovery and compatibility check for Yuxi `>=0.7.1`
+- `yuxi agent eval` for running existing Langfuse dataset experiments with a logged-in remote
+
+## Next
+
+- yuxi kb upload <dir>

yuxi_cli-0.1.0/README.md

@@ -0,0 +1,16 @@
+# yuxi-cli
+
+Yuxi command line client.
+
+First-stage scope:
+
+- remote management through `~/.yuxi/config.toml`
+- browser login
+- API Key import through `--api-key`
+- `whoami`, `status`, and `logout`
+- server discovery and compatibility check for Yuxi `>=0.7.1`
+- `yuxi agent eval` for running existing Langfuse dataset experiments with a logged-in remote
+
+## Next
+
+- yuxi kb upload <dir>

yuxi_cli-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=80", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "yuxi-cli"
+version = "0.1.0"
+description = "Yuxi command line client"
+readme = "README.md"
+requires-python = ">=3.12"
+authors = [{ name = "Wenjie Zhang" }]
+license = "MIT"
+keywords = ["yuxi", "cli", "rag", "knowledge-base", "agent"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "httpx>=0.27",
+    "langfuse>=4.0.0",
+    "packaging>=24",
+    "questionary>=2.1.0",
+    "rich>=13.7",
+    "typer>=0.16",
+]
+
+[project.urls]
+Homepage = "https://github.com/xerrors/Yuxi"
+Repository = "https://github.com/xerrors/Yuxi"
+Issues = "https://github.com/xerrors/Yuxi/issues"
+
+[project.scripts]
+yuxi = "yuxi_cli.main:app"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[dependency-groups]
+test = [
+    "pytest>=8",
+]

yuxi_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

yuxi_cli-0.1.0/src/yuxi_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Yuxi CLI package."""
+
+__version__ = "0.1.0"

yuxi_cli-0.1.0/src/yuxi_cli/__main__.py

@@ -0,0 +1,3 @@
+from yuxi_cli.main import app
+
+app()

yuxi_cli-0.1.0/src/yuxi_cli/agent_eval.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+import os
+import uuid
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Any
+
+from langfuse import Langfuse
+from rich.console import Console
+
+from yuxi_cli.client import YuxiClient
+from yuxi_cli.config import ConfigStore
+
+
+class AgentEvalError(Exception):
+    pass
+
+
+@dataclass
+class AgentEvalOptions:
+    dataset_name: str
+    agent_slug: str
+    experiment_name: str | None = None
+    max_concurrency: int = 1
+    timeout_seconds: float = 900
+
+
+def _env(name: str, default: str | None = None) -> str | None:
+    value = os.getenv(name)
+    return value if value else default
+
+
+def build_langfuse_client() -> Langfuse:
+    kwargs: dict[str, Any] = {
+        "public_key": _env("LANGFUSE_PUBLIC_KEY"),
+        "secret_key": _env("LANGFUSE_SECRET_KEY"),
+    }
+    host = _env("LANGFUSE_BASE_URL")
+    if host:
+        kwargs["host"] = host
+    return Langfuse(**kwargs)
+
+
+def extract_query(item_input: Any) -> str:
+    if isinstance(item_input, str):
+        return item_input
+    if isinstance(item_input, dict):
+        for key in ("input", "query", "question", "prompt"):
+            value = item_input.get(key)
+            if isinstance(value, str) and value.strip():
+                return value
+    raise AgentEvalError(f"无法从 Langfuse dataset item input 中提取 query: {item_input!r}")
+
+
+def run_langfuse_agent_experiment(
+    store: ConfigStore,
+    remote_name: str | None,
+    options: AgentEvalOptions,
+    console: Console,
+    *,
+    langfuse_factory=build_langfuse_client,
+    client_factory=YuxiClient,
+) -> None:
+    config = store.load()
+    remote = config.get_remote(remote_name)
+    if not remote.api_key:
+        raise AgentEvalError(f"remote 尚未登录: {remote.name}。请先运行 yuxi login。")
+
+    if options.max_concurrency < 1:
+        raise AgentEvalError("--max-concurrency 必须大于等于 1")
+    if options.timeout_seconds <= 0:
+        raise AgentEvalError("--timeout-seconds 必须大于 0")
+
+    experiment_name = options.experiment_name or f"yuxi-agent-eval-{datetime.now(UTC).strftime('%Y%m%dT%H%M%SZ')}"
+    langfuse_client = langfuse_factory()
+    dataset = langfuse_client.get_dataset(options.dataset_name)
+
+    def task(*, item, **_kwargs):
+        return _run_agent_eval_item(
+            remote=remote,
+            agent_slug=options.agent_slug,
+            dataset_name=options.dataset_name,
+            experiment_name=experiment_name,
+            item=item,
+            timeout_seconds=options.timeout_seconds,
+            client_factory=client_factory,
+        )
+
+    result = dataset.run_experiment(
+        name=experiment_name,
+        task=task,
+        max_concurrency=options.max_concurrency,
+        metadata={
+            "source": "agent_evaluation",
+            "agent_slug": options.agent_slug,
+            "dataset_name": options.dataset_name,
+            "remote": remote.name,
+        },
+    )
+    console.print(result.format(include_item_results=True))
+    langfuse_client.flush()
+    processed_count = len(result.item_results)
+    total_count = len(dataset.items)
+    if processed_count != total_count:
+        raise AgentEvalError(f"Langfuse experiment 部分失败: {processed_count}/{total_count} 个 item 成功写入")
+
+
+def _run_agent_eval_item(
+    *,
+    remote,
+    agent_slug: str,
+    dataset_name: str,
+    experiment_name: str,
+    item: Any,
+    timeout_seconds: float,
+    client_factory,
+) -> str:
+    query = extract_query(item.input)
+    item_id = str(getattr(item, "id", "") or "")
+    request_id = f"eval-{uuid.uuid4()}"
+    evaluation = {
+        "dataset_name": dataset_name,
+        "dataset_item_id": item_id,
+        "experiment_name": experiment_name,
+    }
+    with client_factory(remote, timeout=timeout_seconds) as client:
+        result = client.run_agent_eval(
+            query=query,
+            agent_slug=agent_slug,
+            evaluation=evaluation,
+            meta={"request_id": request_id},
+            timeout_seconds=timeout_seconds,
+        )
+
+    if result.get("status") != "completed":
+        raise AgentEvalError(f"Agent eval run failed for dataset item {item_id}: {result}")
+    return str(result.get("output") or "")

yuxi_cli-0.1.0/src/yuxi_cli/client.py

@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlencode
+
+import httpx
+
+from yuxi_cli.config import Remote, build_url
+
+
+class ClientError(Exception):
+    def __init__(self, message: str, *, error_code: str | None = None, status_code: int | None = None):
+        super().__init__(message)
+        self.error_code = error_code
+        self.status_code = status_code
+
+
+@dataclass
+class CLIAuthSession:
+    device_code: str
+    user_code: str
+    verification_uri: str
+    expires_in: int
+    interval: int
+
+    @property
+    def authorize_path(self) -> str:
+        params = urlencode({"user_code": self.user_code})
+        separator = "&" if "?" in self.verification_uri else "?"
+        return f"{self.verification_uri}{separator}{params}"
+
+
+class YuxiClient:
+    def __init__(self, remote: Remote, timeout: float = 30.0):
+        self.remote = remote
+        self.client = httpx.Client(timeout=timeout)
+
+    def close(self) -> None:
+        self.client.close()
+
+    def __enter__(self) -> YuxiClient:
+        return self
+
+    def __exit__(self, *_exc) -> None:
+        self.close()
+
+    def health(self) -> dict:
+        return self._request("GET", "/system/health", auth=False)
+
+    def discovery(self) -> dict:
+        return self._request("GET", "/system/discovery", auth=False)
+
+    def me(self, api_key: str | None = None) -> dict:
+        return self._request("GET", "/auth/me", api_key=api_key)
+
+    def create_cli_session(self) -> CLIAuthSession:
+        data = self._request("POST", "/auth/cli/sessions", json={}, auth=False)
+        return CLIAuthSession(
+            device_code=data["device_code"],
+            user_code=data["user_code"],
+            verification_uri=data["verification_uri"],
+            expires_in=int(data.get("expires_in") or 600),
+            interval=int(data.get("interval") or 2),
+        )
+
+    def exchange_cli_token(self, device_code: str) -> dict:
+        return self._request("POST", "/auth/cli/sessions/token", json={"device_code": device_code}, auth=False)
+
+    def delete_api_key(self, api_key_id: str) -> dict:
+        return self._request("DELETE", f"/user/apikey/{api_key_id}")
+
+    def get_database(self, kb_id: str) -> dict:
+        return self._request("GET", f"/knowledge/databases/{kb_id}")
+
+    def list_databases(self) -> dict:
+        return self._request("GET", "/knowledge/databases")
+
+    def get_knowledge_base_types(self) -> dict:
+        return self._request("GET", "/knowledge/types")
+
+    def get_supported_file_types(self) -> dict:
+        return self._request("GET", "/knowledge/files/supported-types")
+
+    def upload_knowledge_file(self, kb_id: str, path: Path, *, timeout_seconds: float = 300) -> dict:
+        with path.open("rb") as fp:
+            return self._request(
+                "POST",
+                "/knowledge/files/upload",
+                params={"kb_id": kb_id},
+                files={"file": (path.name, fp, "application/octet-stream")},
+                timeout=timeout_seconds,
+            )
+
+    def add_uploaded_documents(self, kb_id: str, items: list[str], params: dict) -> dict:
+        return self._request(
+            "POST",
+            f"/knowledge/databases/{kb_id}/documents/add",
+            json={"items": items, "params": params},
+        )
+
+    def run_agent_eval(
+        self,
+        *,
+        query: str,
+        agent_slug: str,
+        evaluation: dict,
+        meta: dict | None = None,
+        image_content: str | None = None,
+        model_spec: str | None = None,
+        timeout_seconds: float = 900,
+    ) -> dict:
+        payload = {
+            "query": query,
+            "agent_slug": agent_slug,
+            "evaluation": evaluation,
+            "meta": meta or {},
+            "image_content": image_content,
+            "model_spec": model_spec,
+        }
+        return self._request("POST", "/agent/eval/runs", json=payload, timeout=timeout_seconds)
+
+    def authorize_url(self, session: CLIAuthSession) -> str:
+        return build_url(self.remote.url, session.authorize_path)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        auth: bool = True,
+        api_key: str | None = None,
+        json: Any | None = None,
+        params: dict | None = None,
+        files: dict | None = None,
+        data: dict | None = None,
+        timeout: float | None = None,
+    ) -> dict:
+        headers = {}
+        token = api_key if api_key is not None else self.remote.api_key
+        if auth and token:
+            headers["Authorization"] = f"Bearer {token}"
+
+        url = f"{self.remote.api_base_url}{path if path.startswith('/') else f'/{path}'}"
+        request_kwargs: dict[str, Any] = {"headers": headers}
+        if params is not None:
+            request_kwargs["params"] = params
+        if files is not None:
+            request_kwargs["files"] = files
+        if data is not None:
+            request_kwargs["data"] = data
+        if json is not None:
+            request_kwargs["json"] = json
+        if timeout is not None:
+            request_kwargs["timeout"] = timeout
+        try:
+            response = self.client.request(method, url, **request_kwargs)
+        except httpx.HTTPError as exc:
+            # 网络层错误（连接失败、超时等）没有 HTTP 状态码，视为可重试的瞬时错误。
+            raise ClientError(f"请求远程失败: {exc}") from exc
+
+        if response.status_code >= 400:
+            error_code, error_message = _parse_http_error(response)
+            raise ClientError(error_message, error_code=error_code, status_code=response.status_code)
+        if not response.content:
+            return {}
+        try:
+            data = response.json()
+        except ValueError as exc:
+            raise ClientError("远程响应不是 JSON") from exc
+        if not isinstance(data, dict):
+            raise ClientError("远程响应格式无效")
+        return data
+
+
+def _parse_http_error(response: httpx.Response) -> tuple[str | None, str]:
+    """解析远程错误，返回 (机器可读 error code, 人类可读 message)。"""
+    try:
+        detail = response.json().get("detail")
+    except ValueError:
+        detail = response.text.strip()
+
+    if isinstance(detail, dict):
+        error = detail.get("error")
+        message = detail.get("message")
+        if error and message:
+            return str(error), f"{error}: {message}"
+        if error:
+            return str(error), str(error)
+        if message:
+            return None, str(message)
+    if detail:
+        return None, str(detail)
+    return None, f"HTTP {response.status_code}"

yuxi_cli-0.1.0/src/yuxi_cli/commands.py

@@ -0,0 +1,201 @@
+from __future__ import annotations
+
+import sys
+import time
+import webbrowser
+from collections.abc import Callable
+
+from rich.console import Console
+from rich.table import Table
+
+from yuxi_cli.client import ClientError, YuxiClient
+from yuxi_cli.config import ConfigStore, Remote
+from yuxi_cli.discovery import ServerCompatibilityError, ensure_server_compatible
+
+PENDING_ERRORS = ("authorization_pending", "slow_down")
+
+
+class CommandError(Exception):
+    pass
+
+
+def remote_add(store: ConfigStore, name: str, url: str) -> Remote:
+    config = store.load()
+    remote = config.set_remote(name, url)
+    store.save(config)
+    return remote
+
+
+def remote_use(store: ConfigStore, name: str) -> Remote:
+    config = store.load()
+    remote = config.use_remote(name)
+    store.save(config)
+    return remote
+
+
+def remote_list(store: ConfigStore, console: Console) -> None:
+    config = store.load()
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("Current", width=7)
+    table.add_column("Name")
+    table.add_column("URL")
+    table.add_column("Auth")
+    for name, remote in config.remotes.items():
+        table.add_row("*" if name == config.current else "", name, remote.url, "API Key" if remote.has_api_key else "-")
+    console.print(table)
+
+
+def remote_ping(store: ConfigStore, name: str | None, console: Console, client_factory=YuxiClient) -> None:
+    config = store.load()
+    remote = config.get_remote(name)
+    with client_factory(remote) as client:
+        data = client.health()
+    console.print(f"{remote.name}: {data.get('status', 'ok')} {data.get('version', '')}".rstrip())
+
+
+def login_with_api_key(
+    store: ConfigStore,
+    remote_name: str | None,
+    api_key: str,
+    console: Console,
+    client_factory=YuxiClient,
+) -> Remote:
+    if not api_key.startswith("yxkey_"):
+        raise CommandError("API Key 格式无效，应以 yxkey_ 开头")
+
+    config = store.load()
+    remote = config.get_remote(remote_name)
+    with client_factory(remote) as client:
+        _ensure_server_compatible(client, "cli.api_key_auth")
+        client.me(api_key=api_key)  # 校验 Key 是否可用
+
+    remote.api_key = api_key
+    remote.api_key_id = ""
+    store.save(config)
+    console.print(f"已保存 {remote.name} 的 API Key。")
+    return remote
+
+
+def login_with_browser(
+    store: ConfigStore,
+    remote_name: str | None,
+    no_open: bool,
+    console: Console,
+    *,
+    client_factory=YuxiClient,
+    open_browser: Callable[[str], bool] = webbrowser.open,
+    sleep: Callable[[float], None] = time.sleep,
+    monotonic: Callable[[], float] = time.monotonic,
+) -> Remote:
+    config = store.load()
+    remote = config.get_remote(remote_name)
+
+    with client_factory(remote) as client:
+        _ensure_server_compatible(client, "cli.browser_login")
+        session = client.create_cli_session()
+        authorize_url = client.authorize_url(session)
+        console.print(f"授权码: {session.user_code}")
+        console.print(f"浏览器授权地址: {authorize_url}")
+        if not no_open:
+            open_browser(authorize_url)
+
+        deadline = monotonic() + session.expires_in
+        while monotonic() < deadline:
+            try:
+                data = client.exchange_cli_token(session.device_code)
+                api_key = data.get("secret") or ""
+                api_key_meta = data.get("api_key") or {}
+                if not api_key:
+                    raise CommandError("远程未返回 API Key secret")
+
+                remote.api_key = api_key
+                remote.api_key_id = str(api_key_meta.get("id") or "")
+                store.save(config)
+                console.print(f"已完成 {remote.name} 的浏览器登录。")
+                return remote
+            except ClientError as exc:
+                if not _should_keep_polling(exc):
+                    raise
+            sleep(max(1, session.interval))
+
+    raise CommandError("浏览器授权超时")
+
+
+def _should_keep_polling(exc: ClientError) -> bool:
+    """轮询期间是否应继续重试：等待授权、限流，或瞬时网络/服务端错误。"""
+    if exc.error_code in PENDING_ERRORS or str(exc).startswith(PENDING_ERRORS):
+        return True
+    # status_code 为 None 表示网络层错误；5xx 为服务端瞬时错误，均可重试。
+    return exc.status_code is None or exc.status_code >= 500
+
+
+def whoami(store: ConfigStore, remote_name: str | None, console: Console, client_factory=YuxiClient) -> None:
+    config = store.load()
+    remote = config.get_remote(remote_name)
+    if not remote.api_key:
+        raise CommandError(f"remote 尚未登录: {remote.name}")
+    with client_factory(remote) as client:
+        user = client.me()
+    console.print(f"{user.get('username')} ({user.get('uid')}) - {user.get('role')}")
+
+
+def status(store: ConfigStore, remote_name: str | None, console: Console, client_factory=YuxiClient) -> None:
+    config = store.load()
+    remote = config.get_remote(remote_name)
+    with client_factory(remote) as client:
+        health = client.health()
+        auth = "未登录"
+        if remote.api_key:
+            try:
+                user = client.me()
+                auth = f"{user.get('username')} ({user.get('uid')})"
+            except ClientError:
+                auth = "API Key 无效"
+
+    table = Table(show_header=False)
+    table.add_row("Remote", remote.name)
+    table.add_row("URL", remote.url)
+    table.add_row("Health", f"{health.get('status', 'ok')} {health.get('version', '')}".rstrip())
+    table.add_row("Auth", auth)
+    console.print(table)
+
+
+def logout(
+    store: ConfigStore,
+    remote_name: str | None,
+    local_only: bool,
+    console: Console,
+    client_factory=YuxiClient,
+) -> Remote:
+    config = store.load()
+    remote = config.get_remote(remote_name)
+    if remote.api_key and remote.api_key_id and not local_only:
+        with client_factory(remote) as client:
+            client.delete_api_key(remote.api_key_id)
+
+    remote.api_key = ""
+    remote.api_key_id = ""
+    store.save(config)
+    console.print(f"已退出 {remote.name}。")
+    return remote
+
+
+def select_login_mode(console: Console) -> str:
+    console.print("选择登录方式:")
+    console.print("> 1. 浏览器登录（推荐）")
+    console.print("  2. API Key")
+    if not sys.stdin.isatty():
+        return "browser"
+    value = input("直接回车使用浏览器登录，输入 2 使用 API Key: ").strip()
+    return "api_key" if value == "2" else "browser"
+
+
+def _ensure_server_compatible(client: YuxiClient, required_capability: str) -> None:
+    try:
+        discovery = client.discovery()
+    except ClientError as exc:
+        raise CommandError(f"无法读取服务端 discovery，请确认远程是 Yuxi 0.7.1 或更高版本: {exc}") from exc
+    try:
+        ensure_server_compatible(discovery, required_capability)
+    except ServerCompatibilityError as exc:
+        raise CommandError(str(exc)) from exc