Metadata-Version: 2.4
Name: clio-agent
Version: 0.5.1
Summary: CLIO Agent — Autonomous AI agent framework for scientific data management. Part of the IOWarp platform.
Project-URL: Homepage, https://github.com/iowarp/clio-agent
Project-URL: Documentation, https://github.com/iowarp/clio-agent/tree/main/ai-docs
Project-URL: Repository, https://github.com/iowarp/clio-agent
Project-URL: Issues, https://github.com/iowarp/clio-agent/issues
Author-email: Antonis Kougkas <a.kougkas@gmail.com>, Gnosis Research Center <gra@iit.edu>
Maintainer-email: Antonis Kougkas <a.kougkas@gmail.com>
License: BSD-3-Clause
License-File: LICENSE
Keywords: a2a-protocol,adios,agent-registry,arc-memory,autonomous-agent,clio,clio-agent,data-io-optimization,data-science,fastmcp,hdf5,hpc,iowarp,llm-agents,mcp,multi-agent,optimizer-layer,parquet,react-pattern,scientific-computing,self-improving,slurm
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.12
Requires-Dist: dspy>=3.1.3
Requires-Dist: fastapi>=0.104.0
Requires-Dist: fastmcp>=3.2.4
Requires-Dist: h5py>=3.10.0
Requires-Dist: lru-dict>=1.3.0
Requires-Dist: matplotlib>=3.8.0
Requires-Dist: msgspec>=0.18.0
Requires-Dist: prompt-toolkit>=3.0.0
Requires-Dist: pyarrow>=14.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: rich>=14.2.0
Requires-Dist: sortedcontainers>=2.4.0
Requires-Dist: sse-starlette>=1.6.0
Requires-Dist: uvicorn>=0.24.0
Provides-Extra: all
Requires-Dist: globus-sdk>=3.0.0; extra == 'all'
Requires-Dist: mypy>=1.7.0; extra == 'all'
Requires-Dist: numpy>=1.24.0; extra == 'all'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'all'
Requires-Dist: pytest-cov>=4.1.0; extra == 'all'
Requires-Dist: pytest>=7.4.0; extra == 'all'
Requires-Dist: pyzmq>=25.0.0; extra == 'all'
Requires-Dist: ruff>=0.1.0; extra == 'all'
Requires-Dist: scipy>=1.11.0; extra == 'all'
Provides-Extra: argonne
Requires-Dist: globus-sdk>=3.0.0; extra == 'argonne'
Provides-Extra: dev
Requires-Dist: mypy>=1.7.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: iowarp
Requires-Dist: pyzmq>=25.0.0; extra == 'iowarp'
Provides-Extra: optimizers
Requires-Dist: numpy>=1.24.0; extra == 'optimizers'
Requires-Dist: scipy>=1.11.0; extra == 'optimizers'
Provides-Extra: tools
Description-Content-Type: text/markdown

<p align="center">
  <img src="docs/images/banner.png" alt="CLIO Agent — Cognitive Layer for Adaptive Universal Data & Intelligent Operations" width="820">
</p>

<p align="center">
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.12+-blue.svg" alt="Python 3.12+"></a>
  <a href="https://github.com/astral-sh/uv"><img src="https://img.shields.io/badge/UV-enabled-orange.svg" alt="UV"></a>
  <a href="https://github.com/jlowin/fastmcp"><img src="https://img.shields.io/badge/FastMCP-enabled-purple.svg" alt="FastMCP"></a>
  <a href="https://iowarp.org"><img src="https://img.shields.io/badge/IOWarp-Intelligence%20Layer-teal.svg" alt="IOWarp"></a>
</p>

---

## What is CLIO Agent?

An autonomous agent for **scientific data management** — HDF5, Parquet, and CSV inspection through a FastMCP tool gateway, with a Bubbletea terminal UI ([gact](https://github.com/iowarp/gact-tui)) for interactive work. CLIO is the Intelligence Layer (CEI) of the [IOWarp](https://iowarp.org) platform.

The agent runs in three tiers: a main orchestrator (planner loop over registered tools and experts), domain experts (data / analysis / visualization), and ephemeral nanoagents for parallel sub-tasks. State lives in a local-first memory layer (ARC) that all tiers read and write.

- Multi-expert orchestration with capability-based routing
- FastMCP tool gateway, HDF5 + Parquet servers out of the box
- ARC memory with O(log N) context retrieval
- Optimizer layer for offline tuning + online learning
- Runtime doctor for LM / gateway / file-policy health
- Works with LM Studio, Ollama, OpenAI, Anthropic, and the Argonne ALCF inference gateway

---

## Quick Start

One line installs `clio-agent` + the `gact` TUI, builds them, and drops a `clio` command on your PATH.

**Linux / macOS**
```sh
curl -fsSL https://raw.githubusercontent.com/iowarp/clio-agent/main/install/install.sh | sh
clio
```

**Windows (PowerShell)**
```powershell
irm https://raw.githubusercontent.com/iowarp/clio-agent/main/install/install.ps1 | iex
clio
```

`clio` boots the server (if it isn't already up) and attaches the TUI. On first connect, pick an LM provider in the modal and you're chatting.

Prerequisites: `git`, [`uv`](https://astral.sh/uv), and `go` 1.26+ — the installer tells you if any are missing.

---

## Using the `clio` command

`clio` with no arguments is the one-command UX. The subcommands manage the backing server without hunting PIDs:

| Command | What it does |
|---|---|
| `clio` | ensure the server is up, then attach the TUI |
| `clio start` / `stop` / `restart` | server lifecycle (process-tree kill on stop) |
| `clio status` / `ps` | PID, port, health |
| `clio logs [N]` | tail server + TUI stderr logs |
| `clio doctor` | check prerequisites and install layout |
| `clio report` | diagnostics bundle for filing GitHub issues |
| `clio completion <shell>` | tab-completion (bash / zsh / powershell) |
| `clio uninstall` | remove CLIO (`--purge` / `-Purge` to drop config too) |

Override paths with `CLIO_PREFIX` / `CLIO_BIN_DIR` and the server port with `CLIO_PORT`. Full install + uninstall reference: [install/README.md](install/README.md).

---

## Architecture

<p align="center">
  <img src="docs/images/architecture.png" alt="CLIO Agent architecture: user interfaces, the Intelligence Layer (CEI) with the orchestrator and tier-2 experts, tier-3 nanoagents, ARC memory, the optimizer layer, and CTE multi-tier storage" width="900">
</p>

For the design rationale (three-tier hierarchy, ARC memory, optimizer layer, IOWarp integration), see [docs/CLIO_AGENT_ARCHITECTURE.md](docs/CLIO_AGENT_ARCHITECTURE.md).

---

## Documentation

| Doc | What's in it |
|---|---|
| [docs/CLIO_AGENT_ARCHITECTURE.md](docs/CLIO_AGENT_ARCHITECTURE.md) | Three-tier design, ARC memory, optimizer layer |
| [docs/SYSTEM_IDENTITY.md](docs/SYSTEM_IDENTITY.md) | What the agent is, design principles |
| [docs/SETUP.md](docs/SETUP.md) | From-scratch install + smoke test (manual path) |
| [docs/CONTRIBUTOR_QUICKSTART.md](docs/CONTRIBUTOR_QUICKSTART.md) | Dev environment, quality checks, where to put code |
| [docs/MCP_TOOL_INTEGRATION.md](docs/MCP_TOOL_INTEGRATION.md) | Adding tools via FastMCP |
| [docs/EXPERT_SYSTEM_DESIGN.md](docs/EXPERT_SYSTEM_DESIGN.md) | Adding new experts |
| [docs/ARC_MEMORY_LAYER.md](docs/ARC_MEMORY_LAYER.md) | Memory model and storage |
| [docs/SELF_IMPROVEMENT.md](docs/SELF_IMPROVEMENT.md) | Optimizer layer |
| [docs/PERMISSIONS.md](docs/PERMISSIONS.md) | Tool permission system |
| [docs/providers/](docs/providers/) | LM provider configuration |
| [docs/CAPABILITIES_MATRIX.md](docs/CAPABILITIES_MATRIX.md) | Feature matrix |
| [PLAN.md](PLAN.md) | Roadmap |

---

## Contributing

Start with [docs/CONTRIBUTOR_QUICKSTART.md](docs/CONTRIBUTOR_QUICKSTART.md). For guidance specific to AI agents working on the codebase, see [AGENTS.md](AGENTS.md).

---

## License + Citation

BSD-3-Clause.

```bibtex
@software{clioagent2026,
  title  = {CLIO Agent: Autonomous Agent for Scientific Data Management},
  author = {IOWarp Team},
  year   = {2026},
  url    = {https://github.com/iowarp/clio-agent},
}
```
