axi-cli 0.0.3__tar.gz

axi_cli-0.0.3/.gitignore

@@ -0,0 +1,14 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+test
+.claude
+axi.json
+.axi/

axi_cli-0.0.3/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## [0.0.3] - 2026-04-01
+
+### Added
+- BM25 关键词搜索（bm25s + jieba 分词，支持中英文）
+- Embedding 语义搜索（Jina/OpenAI，通过 LangChain 接入，可选）
+- 混合搜索（BM25 + Embedding，RRF 融合排序，分数归一化 0-1）
+- `axi grep` 命令：独立的正则表达式搜索
+- `axi daemon status` 输出 JSON 格式状态信息（PID、运行时长、工具统计）
+- Daemon idle 超时自动关闭机制
+- `config.py` 统一配置模块（`axi.json` 解析 + Pydantic 模型）
+- `docs/configuration.md` 配置参考文档
+- Embedding 文件缓存（`.axi/` 目录）
+- MCP 工具调用失败时自动重连一次
+
+### Changed
+- `axi search` 从子串匹配改为 BM25 混合搜索
+- 搜索结果新增 `score` 字段
+- `ToolResolveError` 拆分为 `ToolNotFoundError` 和 `AmbiguousToolError`
+- Daemon 启动不再需要 `--config` 参数，统一从 `axi.json` 读取
+- MCP/原生工具配置统一通过 `config.py` 管理，移除分散的配置解析逻辑
+
+## [0.0.2] - 2026-03-30
+
+### Changed
+- 原生工具 schema 提取改用 Pydantic `create_model`，支持 Literal、Optional、list[T]、嵌套 BaseModel、Annotated[..., Field()] 等高级类型
+- 版本号从 0.1.0 调整为 0.0.2，反映项目早期阶段
+- 代码格式化统一（ruff format）
+
+## [0.1.0] - 2026-03-29
+
+### Added
+- 初始版本：原生工具注册、MCP 对接、daemon 模式

axi_cli-0.0.3/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: axi-cli
+Version: 0.0.3
+Summary: Agent eXecution Interface - unified tool layer for AI Agents
+Requires-Python: >=3.12
+Requires-Dist: bm25s>=0.3.3
+Requires-Dist: jieba>=0.42.1
+Requires-Dist: langchain-community>=0.4.1
+Requires-Dist: langchain-openai>=1.1.12
+Requires-Dist: mcp>=1.26.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: typer>=0.24.1
+Description-Content-Type: text/markdown
+
+# axi
+
+Agent eXecution Interface — AI Agent 与外部系统之间的统一工具层。
+
+通过 CLI 作为万能适配器，将 MCP server 和 Python 函数统一为可搜索、可描述、可调用的命令。Agent 无需猜测命令格式或解析人类可读输出，所有交互都是结构化 JSON。
+
+## 核心理念
+
+几乎所有主流 Agent 框架都把 bash 作为基础能力。axi 在这个"万能通道"之上建一层 Agent-native 的工具层：
+
+- **渐进式披露** — `search → describe → run`，按需获取信息，不吃 context window
+- **Agent-first 输出** — 统一紧凑 JSON，无表格、无颜色、无进度条
+- **双来源统一** — MCP server 和原生 Python 工具，对 Agent 来说是同一套接口
+
+## 安装
+
+```bash
+# 需要 Python 3.12+
+uv pip install -e .
+```
+
+## 快速开始
+
+```bash
+# 搜索工具
+axi search "web"
+
+# 查看工具详情
+axi describe jina/jina_search
+
+# 执行工具
+axi run jina/jina_search --query "hello world" --count 3
+```
+
+## 配置
+
+在项目根目录创建 `axi.json`（参考 `axi.json.example`）：
+
+```json
+{
+    "mcpServers": {
+        "jina": {
+            "command": "npx",
+            "args": ["jina-mcp-tools"],
+            "env": { "JINA_API_KEY": "your-key" }
+        }
+    },
+    "nativeTools": [
+        {"module": "my_project.tools"},
+        {"module": "./scripts/tools.py", "name": "scripts"}
+    ]
+}
+```
+
+- **mcpServers** — MCP server 配置，key 名作为工具命名空间
+- **nativeTools** — 原生 Python 工具，`module` 支持文件路径和模块路径，`name` 可选（省略则自动推导）
+
+## CLI 命令
+
+| 命令 | 说明 |
+|------|------|
+| `axi list [server]` | 列出所有 server 及工具 |
+| `axi search <query>` | 混合搜索工具（BM25 + Embedding，支持 `--top-k`） |
+| `axi grep <pattern>` | 正则表达式搜索工具（支持 `--top-k`） |
+| `axi describe <tool>` | 查看工具完整 schema |
+| `axi run <tool> --key value` | 执行工具（也支持 `-j '{...}'` 传 JSON） |
+| `axi daemon start\|status\|stop` | 管理 daemon 进程 |
+
+所有输出统一为紧凑 JSON。`axi run` 返回统一信封：
+
+```json
+{"status": "success", "data": "..."}
+{"status": "error", "error": "错误信息"}
+```
+
+## 注册原生工具
+
+```python
+from axi import tool
+
+@tool(name="query_orders", description="按区域查询订单")
+def query_orders(region: str, limit: int = 10) -> dict:
+    return {"orders": [...], "total": 42}
+```
+
+装饰器自动从函数签名提取参数 schema。注册后同时获得 CLI 调用和 PTC 调用能力。
+
+## PTC（Programmatic Tool Calling）
+
+Agent 可以写 Python 代码批量调用工具，在本地做数据过滤和聚合，避免反复 LLM round-trip：
+
+```python
+from axi import tool
+
+search = tool("jina/jina_search")
+results = search(query="python async", count=5)
+```
+
+## Daemon 模式
+
+MCP 工具通过后台 daemon 长连接执行，支持有状态 MCP server（如 browser MCP）。执行 `axi search/describe/run` 时自动启动 daemon，无需手动管理。
+
+```
+axi CLI ──(Unix socket)──> daemon ──(stdio)──> MCP server A
+                                   ──(stdio)──> MCP server B
+```
+
+## 技术栈
+
+Python 3.12+ / [Typer](https://typer.tiangolo.com/) / [Pydantic](https://docs.pydantic.dev/) / [MCP SDK](https://github.com/modelcontextprotocol/python-sdk)
+
+## License
+
+MIT

axi_cli-0.0.3/README.md

@@ -0,0 +1,114 @@
+# axi
+
+Agent eXecution Interface — AI Agent 与外部系统之间的统一工具层。
+
+通过 CLI 作为万能适配器，将 MCP server 和 Python 函数统一为可搜索、可描述、可调用的命令。Agent 无需猜测命令格式或解析人类可读输出，所有交互都是结构化 JSON。
+
+## 核心理念
+
+几乎所有主流 Agent 框架都把 bash 作为基础能力。axi 在这个"万能通道"之上建一层 Agent-native 的工具层：
+
+- **渐进式披露** — `search → describe → run`，按需获取信息，不吃 context window
+- **Agent-first 输出** — 统一紧凑 JSON，无表格、无颜色、无进度条
+- **双来源统一** — MCP server 和原生 Python 工具，对 Agent 来说是同一套接口
+
+## 安装
+
+```bash
+# 需要 Python 3.12+
+uv pip install -e .
+```
+
+## 快速开始
+
+```bash
+# 搜索工具
+axi search "web"
+
+# 查看工具详情
+axi describe jina/jina_search
+
+# 执行工具
+axi run jina/jina_search --query "hello world" --count 3
+```
+
+## 配置
+
+在项目根目录创建 `axi.json`（参考 `axi.json.example`）：
+
+```json
+{
+    "mcpServers": {
+        "jina": {
+            "command": "npx",
+            "args": ["jina-mcp-tools"],
+            "env": { "JINA_API_KEY": "your-key" }
+        }
+    },
+    "nativeTools": [
+        {"module": "my_project.tools"},
+        {"module": "./scripts/tools.py", "name": "scripts"}
+    ]
+}
+```
+
+- **mcpServers** — MCP server 配置，key 名作为工具命名空间
+- **nativeTools** — 原生 Python 工具，`module` 支持文件路径和模块路径，`name` 可选（省略则自动推导）
+
+## CLI 命令
+
+| 命令 | 说明 |
+|------|------|
+| `axi list [server]` | 列出所有 server 及工具 |
+| `axi search <query>` | 混合搜索工具（BM25 + Embedding，支持 `--top-k`） |
+| `axi grep <pattern>` | 正则表达式搜索工具（支持 `--top-k`） |
+| `axi describe <tool>` | 查看工具完整 schema |
+| `axi run <tool> --key value` | 执行工具（也支持 `-j '{...}'` 传 JSON） |
+| `axi daemon start\|status\|stop` | 管理 daemon 进程 |
+
+所有输出统一为紧凑 JSON。`axi run` 返回统一信封：
+
+```json
+{"status": "success", "data": "..."}
+{"status": "error", "error": "错误信息"}
+```
+
+## 注册原生工具
+
+```python
+from axi import tool
+
+@tool(name="query_orders", description="按区域查询订单")
+def query_orders(region: str, limit: int = 10) -> dict:
+    return {"orders": [...], "total": 42}
+```
+
+装饰器自动从函数签名提取参数 schema。注册后同时获得 CLI 调用和 PTC 调用能力。
+
+## PTC（Programmatic Tool Calling）
+
+Agent 可以写 Python 代码批量调用工具，在本地做数据过滤和聚合，避免反复 LLM round-trip：
+
+```python
+from axi import tool
+
+search = tool("jina/jina_search")
+results = search(query="python async", count=5)
+```
+
+## Daemon 模式
+
+MCP 工具通过后台 daemon 长连接执行，支持有状态 MCP server（如 browser MCP）。执行 `axi search/describe/run` 时自动启动 daemon，无需手动管理。
+
+```
+axi CLI ──(Unix socket)──> daemon ──(stdio)──> MCP server A
+                                   ──(stdio)──> MCP server B
+```
+
+## 技术栈
+
+Python 3.12+ / [Typer](https://typer.tiangolo.com/) / [Pydantic](https://docs.pydantic.dev/) / [MCP SDK](https://github.com/modelcontextprotocol/python-sdk)
+
+## License
+
+MIT

axi_cli-0.0.3/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "axi-cli"
+version = "0.0.3"
+description = "Agent eXecution Interface - unified tool layer for AI Agents"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "bm25s>=0.3.3",
+    "jieba>=0.42.1",
+    "langchain-community>=0.4.1",
+    "langchain-openai>=1.1.12",
+    "mcp>=1.26.0",
+    "pydantic>=2.12.5",
+    "typer>=0.24.1",
+]
+
+[project.scripts]
+axi = "axi.cli:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/axi"]
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+    ".github/",
+    ".python-version",
+    "CLAUDE.md",
+    "axi.json.example",
+    "docs/",
+    "tests/",
+    "uv.lock",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+    "ruff>=0.15.8",
+]

axi_cli-0.0.3/src/axi/__init__.py

@@ -0,0 +1,81 @@
+"""axi — Agent eXecution Interface."""
+
+import logging
+from typing import Any, Callable
+
+from axi.cli import get_executor, get_registry
+from axi.providers.native import register_tool
+
+__all__ = ["tool"]
+
+# 包级 logger：各子模块通过 logging.getLogger(__name__) 自动继承
+_logger = logging.getLogger("axi")
+_logger.addHandler(logging.NullHandler())
+
+
+def tool(
+    name: str | None = None,
+    description: str | None = None,
+    output_example: Any | None = None,
+) -> Callable:
+    """装饰器：注册一个 Python 函数为 axi 工具。
+
+    用法：
+        @tool(name="query_orders", description="按区域查询订单")
+        def query_orders(region: str, limit: int = 10) -> dict:
+            ...
+
+    也可以作为函数调用获取 PTC 可调用对象：
+        query = tool("query_orders")
+        result = query(region="cn")
+    """
+    # 当作为 PTC 调用时：tool("tool_name") 返回可调用对象
+    if name is not None and description is None and output_example is None:
+        # 先查本地原生工具
+        registry = get_registry()
+        meta = registry.get(name)
+        if meta is not None:
+            executor = get_executor()
+
+            def _native_caller(**kwargs: Any) -> Any:
+                result = executor.run(name, kwargs)  # type: ignore[arg-type]
+                if result.status == "error":
+                    raise RuntimeError(result.error)
+                return result.data
+
+            return _native_caller
+
+        # 再查 daemon（MCP 工具）
+        return _make_daemon_caller(name)
+
+    # 当作为装饰器时
+    def decorator(func: Callable) -> Callable:
+        meta = register_tool(
+            func,
+            name=name,
+            description=description,
+            output_example=output_example,
+        )
+        get_registry().register(meta)
+        return func
+
+    return decorator
+
+
+def _make_daemon_caller(tool_name: str) -> Callable:
+    """创建通过 daemon 调用 MCP 工具的 PTC 函数。"""
+    from axi.daemon.client import ensure_daemon, send_request
+    from axi.daemon.protocol import DaemonRequest
+
+    def _daemon_caller(**kwargs: Any) -> Any:
+        if not ensure_daemon():
+            raise RuntimeError("Daemon is not running. Start it with: axi daemon start")
+
+        resp = send_request(
+            DaemonRequest(method="call_tool", tool_name=tool_name, params=kwargs)
+        )
+        if resp.status == "error":
+            raise RuntimeError(resp.error)
+        return resp.data
+
+    return _daemon_caller