Metadata-Version: 2.4
Name: uag
Version: 0.5.57
Summary: A powerful tool execution agent
Author-email: Hirofumi Ukawa <hirofumi@ukawa.biz>
License-Expression: Apache-2.0
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE-THIRD-PARTY.md
Requires-Dist: openai>=2.45.0
Requires-Dist: tiktoken>=0.13.0
Requires-Dist: anthropic>=0.116.0
Requires-Dist: google-genai>=2.11.0
Requires-Dist: xai-sdk>=1.17.0
Requires-Dist: requests>=2.33.1
Requires-Dist: httpx>=0.28.1
Requires-Dist: urllib3>=2.6.3
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: tqdm>=4.67.3
Requires-Dist: prompt-toolkit>=3.0.52
Requires-Dist: llmcapa>=0.4.1
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: certifi>=2026.2.25
Requires-Dist: numpy>=2.4.4
Requires-Dist: pyreadline3>=3.5.4; sys_platform == "win32"
Requires-Dist: pywin32>=311; sys_platform == "win32"
Requires-Dist: jinja2>=3.1.6
Requires-Dist: python-multipart>=0.0.22
Requires-Dist: websockets>=16.0
Provides-Extra: zai
Requires-Dist: zai-sdk; extra == "zai"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/awaku7/agentcli/main/assets/uag-logo.svg" alt="uag logo" width="720">
</p>

<h1 align="center">uag — Universal AI Gateway</h1>

<p align="center">
  <b>U</b>niversal <b>A</b>I <b>G</b>ateway — Your environment, your freedom.
</p>

<p align="center">
  File ops / Web search / Image generation &amp; analysis / PDF &amp; Excel extraction / IoT control / MCP integration<br>
  20+ providers / 3 UIs / Parallel tool execution / Agent Skills marketplace
</p>

<p align="center">
  <a href="https://github.com/awaku7/agentcli">GitHub</a>
  ·
  <a href="https://pypi.org/project/uag/">PyPI</a>
  ·
  <a href="https://github.com/awaku7/agentcli/blob/main/docs/README.translations.md">Read this in your language</a>
</p>

______________________________________________________________________

## Why uag?

**Break free from vendor lock-in.** Most AI assistants tie you to a specific provider or cloud service. uag is different.

- **Runs locally** on your machine. Your data stays with you (except API calls you make).
- **Provider freedom**: OpenAI, Claude, Gemini, DeepSeek, Ollama, Azure, Bedrock, Novita, HuggingFace... 23 providers, all accessible from a single interface. Swap between them by reconfiguring environment variables — no reinstall, no migration.
- **170 tools**: File I/O, web search, image generation, Gmail, BLE device scanning, MCP server integration — **111 are parallel-safe** (up to 8 execute concurrently via thread pool, configurable via `UAGENT_PARALLEL_WORKERS`). When the LLM fires multiple tool calls at once, uag automatically parallelizes them.
- **3 UIs + A2A**: CLI, GUI, Web, and Agent-to-Agent protocol. Same engine, any interface.
- **IoT ready**: SwitchBot, ECHONET Lite, Matter, UPnP — control your home devices through AI.
- **Agent Skills**: Install community-built skills from the marketplace. Extend uag endlessly.

uag is **your AI assistant on your terms**. Not tied to a provider, not tied to an interface, not tied to a platform.

## Quick Start

```bash
pip install uag
uag
```

On first launch, the setup wizard walks you through provider configuration.
See [docs/ENVIRONMENT.md](https://github.com/awaku7/agentcli/blob/main/docs/ENVIRONMENT.md) for all environment variables.

## Features

### 🧠 Multi-Provider Architecture

OpenAI / Azure / Bedrock / OpenRouter / Ollama / Gemini / Vertex AI / Claude / Grok / NVIDIA / Novita / DeepSeek / Z.AI (Zhipu AI) / HuggingFace / Alibaba Cloud (Qwen) / KIMI (Moonshot AI) / Xiaomi MiMo / LM Studio / MiniMax / **Sakana AI (Fugu)** / **SAKURA AI Engine** / **Together AI** / **Vercel AI Gateway**

All providers share the same toolset and interface. Switch by setting `UAGENT_PROVIDER` — no code changes, no separate installations.

### ⚡ Parallel Tool Execution

When the LLM requests multiple tools simultaneously, uag **automatically parallelizes** them.
111 tools are marked `x_parallel_safe` and execute concurrently via a `ThreadPoolExecutor` (8 threads by default; set `UAGENT_PARALLEL_WORKERS` to change).

**Example**: Ask "Check the weather in Nordic capitals" → LLM fires `search_web` × 5 countries → all 5 searches run in parallel → results collected in one batch.

Read-only tools (file search, hash calculation, directory listing, translation, DB queries, etc.) are aggressively parallelized.

### 🧩 Plugin System (Claude Code Compatible)

uagent implements a **Claude Code-compatible plugin system**. Plugins bundle skills, agents, MCP servers, hooks, and more into self-contained directories with a `.claude-plugin/plugin.json` manifest.

**Supported components**: Skills, Sub-agents, MCP servers, Hooks (12 lifecycle events), Slash commands, Output styles, userConfig, Dependencies, Channels, Marketplaces

**CLI commands**:
```
:plugin list                         # List installed plugins
:plugin install <source> [--scope]   # Install (dir/zip/git/http)
:plugin install <name>@<marketplace>  # Install from marketplace
:plugin remove <name>                # Uninstall
:plugin enable/disable <name>        # Toggle
:plugin marketplace add/remove/list  # Manage marketplaces
:plugin init <name>                  # Scaffold new plugin
```

See [DEVELOP_PLUGIN.md](src/uagent/docs/DEVELOP_PLUGIN.md) for full documentation.

### 🔄 Session Continuity

- **Switch providers mid-session** with `UAGENT_PROVIDER` — conversation history is preserved.
- **Reload past sessions** with `:load <index>` — pick up where you left off.
- **Tool result caching** avoids redundant re-execution when the same tool call repeats.

### 🛠 183 Tools

| Category | Tools |
|---|---|
| **File Operations** | read/write/create/delete/search/grep/hash/zip, file_type, parse_eml (.eml files) |
| **Web** | fetch_url, search_web, screenshot, browser_playwright |
| **Media** | generate_image, analyze_image, img2img, audio_speech, audio_transcribe |
| **Documents** | PDF/PPTX/DOCX/RTF/ODT extraction, Excel structured extraction |
| **Forecast** | Time series forecasting with 9 models (AutoARIMA, Prophet, LightGBM, CatBoost, TimesFM, etc.), auto model selection, plot generation, i18n |
| **Communication** | gmail_send, gmail_read, bluesky, discord_channel, teams_webhook — see [COMMUNICATION.md](https://github.com/awaku7/agentcli/blob/main/docs/COMMUNICATION.md) |
| **IoT** | SwitchBot (Cloud + BLE), ECHONET Lite, Matter, UPnP, reverse_geocode |
| **Dev Tools** | git_ops, python_compile, lint_format, run_tests, db_query, **13 source code navigators (idx family)** |
| **MCP** | Connect to external MCP servers, list tools, execute |
| **A2A** | Agent-to-agent communication (with other uag instances or A2A-compatible servers) |
| **System** | env vars, system specs, time, date calculation, uuid_gen, slugify |
| **Source Nav** | **13 idx tools** for Python, PHP, TypeScript, Java, C#, Dart, C/C++, Rust, Go, Swift, Kotlin, COBOL — get a function/class index or specific definition without reading the whole file |

### 🖥 4 Interfaces + VS Code Extension

| Mode | Command | Purpose |
|---|---|---|
| **CLI** | `uag` | Fast terminal-based operation |
| **GUI** | `uagg` | Desktop UI via tkinter |
| **Web** | `uagw` | Browser-based access |
| **A2A Server** | `uaga` | Agent2Agent protocol for multi-agent communication |
| **VS Code** | — | [Extension](https://github.com/awaku7/agentcli/blob/main/docs/VSCODE.md) with Chat Panel, Explain, Refactor, Fix Error, and Tools Tree View |

See [VSCODE.md](https://github.com/awaku7/agentcli/blob/main/docs/VSCODE.md) for details on the VS Code extension — installation, commands, keybindings, and configuration.

### 🏠 IoT Device Control

- **BACnet**: Read/write BACnet/IP devices (HVAC, lighting, power meters). COV subscription for push notifications
- **Modbus TCP**: Read/write holding/input registers and coils. Polling-based change monitoring
- **OPC UA**: Browse address space, read/write variables, subscribe to data changes
- **SwitchBot**: Cloud batch control & BLE scan/control. Polling-based subscription
- **ECHONET Lite**: Discover, control, and subscribe to INF notifications from home appliances (AC, lights, water heaters, etc.)
- **Matter**: Read/write control + attribute subscription for state change monitoring
- **UPnP**: Device discovery & IGD port forwarding

See [IOT_USECASE.md](https://github.com/awaku7/agentcli/blob/main/docs/IOT_USECASE.md)

### 🎯 Agent Skills Marketplace

`:skills mp_search` to browse [SkillsMP](https://skillsmp.com) and [ClawHub](https://clawhub.ai) for community skills.
Install and extend uag's capabilities on the fly.

### 🤖 Auto-Pilot (`:auto`)

uag can **autonomously pursue a goal across multiple LLM rounds**. Perfect for complex, multi-step tasks that need iterative refinement.

- **How it works**: Each round has a main query (Step A) followed by a reviewer judgment (Step B) that decides "COMPLETE or CONTINUE?"
- **Same provider, same API**: The reviewer judgment uses the identical code path as the main query — including Responses API support.
- **Separate judge LLM** (optional): Set `UAGENT_AP_PROVIDER` to use a different provider/model for the reviewer (e.g. use a cheaper model for judging).
- **Exit anytime**: Press `x` key to stop immediately, even mid-response. Or let the reviewer decide when the goal is met.
- **Configurable**: `--max-rounds N` to control the budget.

See [README_AUTO.md](https://github.com/awaku7/agentcli/blob/main/docs/README_AUTO.md) for full documentation.

### 🧩 Batch State Manager

uag can track progress across long-running multi-file tasks. When the LLM processes dozens of files, `batch_state` persists the list of pending, completed, and failed files to disk. If the session ends or a round times out, the next run resumes from where it stopped — nothing gets lost.

### 🛡 Human-in-the-Loop

`human_ask` lets the LLM pause and ask for your confirmation before performing destructive operations (file deletion, overwrites, shell commands). You stay in control.

### 🛑 Interrupt (c-key / Stop button)

Stop LLM response generation at any time and inject a stop command back to the LLM.

| Interface | How to interrupt |
|---|---|
| **CLI** | Press `c` key during LLM streaming — the current response stops, and `"Stop"` is sent as a user message so the LLM responds accordingly |
| **WEB UI** | Click the red **■ Stop** button (appears automatically during LLM processing) |
| **Desktop GUI** | Click the red **■** button (appears automatically during LLM processing) |

The interrupt works as "prompt injection": instead of just aborting, it feeds `"Stop"` back to the LLM as a user message, allowing it to gracefully conclude or acknowledge the interruption.

Press `x` key to exit auto-pilot mode (see [README_AUTO.md](https://github.com/awaku7/agentcli/blob/main/docs/README_AUTO.md)).

### 🕵️ Browser Automation & Web Inspector

Two complementary Playwright-based tools:

- **browser_playwright**: Automate real browser sessions — navigate, click, fill forms, extract data, handle multi-page flows. Works headless or headed.
- **playwright_inspector**: Record browser transitions, capture DOM snapshots and screenshots at each step. Useful for debugging web interactions or auditing page changes over time.

### 🔄 Dynamic Tool Loading

`tool_catalog` and `tool_load` let you discover and enable tools at runtime.
No need to load everything at startup — activate only what you need, when you need it.

### 🦀 Rust Native Tools

`uuid_gen` and `slugify` are implemented in Rust (via PyO3) for performance.
They load directly from a pre-built `.pyd` — **no `pip install` required**.

External developers can also ship Rust-based tools: place a `.pyd` next to the
wrapper `.py`, use ``load_rust_pyd()`` from ``uagent.tools.rust_helper``, and
users get the tool without any extra dependencies. See
[TOOL_CREATOR_GUIDE.md](https://github.com/awaku7/agentcli/blob/main/TOOL_CREATOR_GUIDE.md).

### 🌐 i18n / L10n

日本語 / English / 简体中文 / 繁體中文 / 한국어 / Español / Français / Русский / and more.
Set `UAGENT_LANG` to switch. See [ADD_LOCALE.md](https://github.com/awaku7/agentcli/blob/main/src/uagent/docs/ADD_LOCALE.md) to add a new locale.

Translations of this README are available in [docs/README.translations.md](https://github.com/awaku7/agentcli/blob/main/docs/README.translations.md).

### 🔒 Encrypted Environment Variables

Store API keys and secrets in `.env.sec` — an encrypted `.env` file.
Manage with `uag_envsec`.

## Configuration & Details

- **Environment variables**: [docs/ENVIRONMENT.md](https://github.com/awaku7/agentcli/blob/main/docs/ENVIRONMENT.md)
- **Setup wizard**: `python -m uagent.setup_cli`
- **Encrypted env**: `uag_envsec` — encrypt `.env` as `.env.sec`
- **Responses API**: Set `UAGENT_RESPONSES=1` for Responses API mode (OpenAI/Azure/Bedrock/OpenRouter/Ollama/Alibaba/LM Studio/Sakana AI). Auto-enabled for Sakana AI (Fugu).
- **Developer docs**: [DEVELOP.md](https://github.com/awaku7/agentcli/blob/main/src/uagent/docs/DEVELOP.md)
- **Tool flow**: [TOOL_FLOW.md](https://github.com/awaku7/agentcli/blob/main/src/uagent/docs/TOOL_FLOW.md) — how tools are sent to LLMs (genre mask, tool_catalog, GPT-5.4+ native tool_search)
- **Small LLM tips**: [SLM_TIPS.md](https://github.com/awaku7/agentcli/blob/main/docs/SLM_TIPS.md)

## Project Philosophy

uag aspires to be **your AI, on your machine, on your terms.**

- No SaaS dependency — runs locally
- No provider lock-in — switch anytime
- No UI lock-in — CLI / GUI / Web / A2A
- No feature lock-in — extend with tools and skills

A free AI agent experience, free from vendor lock-in.

### ✨ Create Your Own Tools

Writing a new tool for uag is straightforward — create a single `.py` file with
`TOOL_SPEC` and `run_tool()`, place it in ``UAGENT_EXTERNAL_TOOLS_DIR``, and
it's immediately available. For Rust developers, ship a pre-built `.pyd` with
zero extra dependencies for users.

See [TOOL_CREATOR_GUIDE.md](https://github.com/awaku7/agentcli/blob/main/TOOL_CREATOR_GUIDE.md)
for the step-by-step guide.

## Contributing

Contributions are welcome! Bug reports, feature suggestions, documentation improvements, translations, and pull requests — all appreciated.

- **Issues**: Open a GitHub issue for bugs or feature requests.
- **Pull requests**: Fork the repo, make your changes, and submit a PR. See [DEVELOP.md](https://github.com/awaku7/agentcli/blob/main/src/uagent/docs/DEVELOP.md) for development setup and guidelines.
- **Translations**: README translations and locale additions are welcome. See [ADD_LOCALE.md](https://github.com/awaku7/agentcli/blob/main/src/uagent/docs/ADD_LOCALE.md).
- **Tools & Skills**: New tool plugins and Agent Skills can be contributed via the marketplace.

### Development checks (before PR)

```bash
python -m py_compile src/uagent/
ruff format src/ && ruff check src/
mypy src/uagent
pytest -q tests/<affected_area>
```

After locale (`.po`) edits: `python scripts/compile_locales.py` and `python scripts/po_qc_summary.py`.

Runtime policy (details in [DEVELOP.md](https://github.com/awaku7/agentcli/blob/main/src/uagent/docs/DEVELOP.md) §6.1): helpers raise instead of `sys.exit`; the tool host turns tool `SystemExit`/`Exception` into error strings so a single tool cannot kill the process. Startup fail-fast exits remain intentional.
