Metadata-Version: 2.4
Name: echotools
Version: 2.4.8
Summary: 通用基础设施 SDK：配置、日志、事件、调度、插件、协议、调用链
Home-page: https://github.com/nichengfuben/echotools
Author: nichengfuben
License: MIT
Project-URL: Homepage, https://github.com/nichengfuben/echotools
Project-URL: Repository, https://github.com/nichengfuben/echotools
Project-URL: Issues, https://github.com/nichengfuben/echotools/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: typing-extensions>=4.7.0
Provides-Extra: toml
Requires-Dist: tomlkit>=0.11.0; extra == "toml"
Requires-Dist: tomli>=2.0.0; python_version < "3.11" and extra == "toml"
Provides-Extra: watch
Requires-Dist: watchdog>=3.0.0; extra == "watch"
Provides-Extra: http
Requires-Dist: aiohttp>=3.8.0; extra == "http"
Provides-Extra: socks
Requires-Dist: aiohttp-socks>=0.8.0; extra == "socks"
Provides-Extra: ssh
Requires-Dist: paramiko>=3.0.0; extra == "ssh"
Provides-Extra: terminal
Requires-Dist: pywinpty>=2.0.0; sys_platform == "win32" and extra == "terminal"
Provides-Extra: console
Requires-Dist: rich>=13.0; extra == "console"
Requires-Dist: wcwidth>=0.2; extra == "console"
Provides-Extra: all
Requires-Dist: tomlkit>=0.11.0; extra == "all"
Requires-Dist: tomli>=2.0.0; python_version < "3.11" and extra == "all"
Requires-Dist: watchdog>=3.0.0; extra == "all"
Requires-Dist: aiohttp>=3.8.0; extra == "all"
Requires-Dist: aiohttp-socks>=0.8.0; extra == "all"
Requires-Dist: paramiko>=3.0.0; extra == "all"
Requires-Dist: pywinpty>=2.0.0; sys_platform == "win32" and extra == "all"
Requires-Dist: rich>=13.0; extra == "all"
Requires-Dist: wcwidth>=0.2; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"

# echotools

通用基础设施 SDK：配置、日志、事件、调度、插件、调用链，以及 **entml** LLM 工具调用协议与终端 Console UI。

完全项目无关，兼容 Python 3.8–3.14。当前版本：**2.4.8**（详见 [CHANGELOG](docs/CHANGELOG.md)）。

## 安装

```bash
# 核心（仅 typing-extensions）
pip install echotools

# 完整功能（含 TOML、Web、终端、Console UI 等）
pip install echotools[all]
```

### 可选依赖

| Extra | 用途 |
|-------|------|
| `toml` | TOML 配置读写 |
| `watch` | watchdog 文件监视 |
| `http` | aiohttp Web 层 |
| `socks` | SOCKS 代理 |
| `ssh` | SSH 终端 |
| `terminal` | Windows ConPTY |
| `console` | Rich 终端 UI（渐变、表格、交互选择） |
| `all` | 全部可选依赖 |
| `dev` | pytest、ruff、mypy |

## 快速开始

### 基础设施

```python
from echotools import EchoTools

et = EchoTools(service_name="myapp")
et.logger.configure(level="INFO", color=True)
cfg = et.config
cfg.load("config.toml")

with et.tracer.trace("request") as trace:
    with et.tracer.span(trace, "db") as span:
        span.set_tag("query", "select 1")

await et.shutdown()
```

### entml 工具调用

内置 **entml**（`<entml:*>` 熵标记语言）协议，负责 prompt 注入与模型输出解析。

```python
from echotools import FncallStreamParser, get_protocol, inject_fncall

tools = [
    {
        "name": "Bash",
        "description": "Run a shell command",
        "input_schema": {
            "type": "object",
            "properties": {"command": {"type": "string"}},
            "required": ["command"],
        },
    }
]
messages = [{"role": "user", "content": "列出当前目录"}]

proto = get_protocol()
out_messages = inject_fncall(messages, tools, proto, lang="zh")

parser = FncallStreamParser(proto, tools=tools)
for chunk in model_stream:
    parser.feed(chunk)
    if parser.get_ready_tool_calls():
        ...
result = parser.finalize()
```

能力包括：prompt 注入（history / 工具结果 / thinking 模式）、batch `parse()`、流式
`partial_text` / `input_json_delta`、伪 history 剥离、工具循环检测。

### 终端 Console UI

需要 `pip install echotools[console]`（或 `[all]`）：

```python
from echotools.media.console import (
    create_themed_ui,
    render_gradient_banner,
    render_text_lines,
    run_select,
)

ui = create_themed_ui(theme_name="ocean")  # ocean / forest / sunset / violet / rose / slate / cyan
print(render_gradient_banner(render_text_lines("echotools"), theme_name="ocean"))
choice = run_select(ui, "选择主题", ["ocean", "forest", "sunset"])
```

## 能力总览

| 模块 | 说明 |
|------|------|
| `EchoTools` | 门面：配置、日志、事件、调度、插件等统一入口 |
| `ConfigCenter` | 点路径配置 + 热重载 + 类型绑定 |
| `LoggerManager` | 调用链注入 + 颜色 + 轮转 |
| `EventBus` | 同步/异步事件 |
| `Tracer` | 轻量调用链 |
| `TaskDispatcher` | 单发/竞速 + 贝叶斯自适应选择 |
| `PluginRegistry` | 自动发现 + 热重载 |
| `get_protocol` / `inject_fncall` | entml 工具协议与 prompt 注入 |
| `FncallStreamParser` | 流式工具调用解析 |
| `media.console` | Rich 终端 UI、多主题、交互选择与 ANSI 渐变 |
| `PrintStream` | 动态速度打印流 |
| `ProxyManager` | HTTP/HTTPS/SOCKS |
| `WebApplication` | aiohttp Web（需 `[http]`） |
| `LocalTerminal` / `SSHTerminal` | 终端会话（需 `[terminal]` / `[ssh]`） |
| `AutoUpdater` | git 自动更新 |
| `FileWatcher` | 轮询文件监视 |
| `plat.capture` | 跨平台音频监控/录音/截图（纯 ctypes，零第三方依赖） |

## 开发

```bash
pip install -e ".[dev,all]"
make -C docs lint
make -C docs test
make -C docs cov
```

模块指南见 [docs/modules.md](docs/modules.md)，API 参考见 [docs/api.md](docs/api.md)。

## 变更记录

见 [docs/CHANGELOG.md](docs/CHANGELOG.md)。

## 许可证

MIT
