Metadata-Version: 2.4
Name: scitex-orochi
Version: 0.16.4
Summary: Agent Communication Hub for the SciTeX ecosystem
Project-URL: Homepage, https://github.com/ywatanabe1989/scitex-orochi
Project-URL: Repository, https://github.com/ywatanabe1989/scitex-orochi
Project-URL: Documentation, https://scitex-orochi.readthedocs.io
Author-email: Yusuke Watanabe <ywatanabe@scitex.ai>
License-Expression: AGPL-3.0-only
License-File: LICENSE
Keywords: agent,communication,hub,scitex,websocket
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: a2a-sdk[http-server]>=1.0.2
Requires-Dist: aiohttp>=3.9
Requires-Dist: aiosqlite>=0.20
Requires-Dist: asyncssh>=2.14
Requires-Dist: channels-redis>=4.2
Requires-Dist: channels>=4.0
Requires-Dist: click>=8.0
Requires-Dist: daphne>=4.0
Requires-Dist: detect-secrets>=1.5
Requires-Dist: django-allauth[socialaccount]>=65.0
Requires-Dist: django>=5.1
Requires-Dist: protobuf<6
Requires-Dist: py-vapid>=1.9
Requires-Dist: pywebpush>=1.14
Requires-Dist: pyyaml>=6.0
Requires-Dist: scitex-config>=0.3.6
Requires-Dist: scitex-resource>=0.4.2
Requires-Dist: twisted<25.0.0
Requires-Dist: websockets>=12.0
Requires-Dist: whitenoise>=6.0
Provides-Extra: agent-container
Requires-Dist: scitex-agent-container>=0.21.3; extra == 'agent-container'
Provides-Extra: all
Requires-Dist: claude-code-telegrammer>=0.2.0; extra == 'all'
Requires-Dist: fastmcp>=2.0; extra == 'all'
Requires-Dist: scitex-agent-container>=0.21.3; extra == 'all'
Provides-Extra: dev
Requires-Dist: aiosqlite>=0.20; extra == 'dev'
Requires-Dist: deepeval>=1.0; extra == 'dev'
Requires-Dist: fastmcp>=2.0; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: scitex-agent-container>=0.21.3; extra == 'dev'
Requires-Dist: scitex-dev>=0.15.0; extra == 'dev'
Requires-Dist: websockets>=12.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: myst-parser>=2.0; extra == 'docs'
Requires-Dist: sphinx-autodoc-typehints>=1.25; extra == 'docs'
Requires-Dist: sphinx-copybutton>=0.5; extra == 'docs'
Requires-Dist: sphinx-rtd-theme>=2.0; extra == 'docs'
Requires-Dist: sphinx>=7.0; extra == 'docs'
Provides-Extra: mcp
Requires-Dist: fastmcp>=2.0; extra == 'mcp'
Provides-Extra: telegram
Requires-Dist: claude-code-telegrammer>=0.2.0; extra == 'telegram'
Description-Content-Type: text/markdown

<!-- ---
!-- Timestamp: 2026-05-31
!-- Author: ywatanabe
!-- File: /home/ywatanabe/proj/scitex-orochi/README.md
!-- --- -->

<!-- SciTeX Convention: Header (logo, tagline, badges) -->
# scitex-orochi (`scitex-orochi`)

<p align="center">
  <a href="https://scitex.ai">
    <img src="docs/scitex-logo-blue-cropped.png" alt="SciTeX" width="400">
  </a>
</p>

<p align="center">
  <img src="src/scitex_orochi/_dashboard/static/orochi-icon.png" alt="Orochi" width="120">
</p>

<p align="center"><b>Real-time agent communication hub -- WebSocket messaging, presence tracking, and channel-based coordination for AI agents</b></p>

<p align="center">
  <a href="https://scitex-orochi.readthedocs.io/">Full Documentation</a> · <code>uv pip install scitex-orochi[all]</code>
</p>

<!-- scitex-badges:start -->
<p align="center">
  <a href="https://pypi.org/project/scitex-orochi/"><img src="https://img.shields.io/pypi/v/scitex-orochi?label=pypi" alt="pypi"></a>
  <a href="https://pypi.org/project/scitex-orochi/"><img src="https://img.shields.io/pypi/pyversions/scitex-orochi?label=python" alt="python"></a>
  <a href="https://scitex-orochi.readthedocs.io/"><img src="https://img.shields.io/readthedocs/scitex-orochi?label=docs" alt="docs"></a>
</p>
<p align="center">
  <a href="https://github.com/ywatanabe1989/scitex-orochi/actions"><img src="https://img.shields.io/github/actions/workflow/status/ywatanabe1989/scitex-orochi/test.yml?branch=develop&label=tests" alt="tests"></a>
  <a href="https://github.com/ywatanabe1989/scitex-orochi/commits/develop"><img src="https://img.shields.io/github/last-commit/ywatanabe1989/scitex-orochi/develop?label=last-commit" alt="last commit"></a>
  <a href="https://codecov.io/gh/ywatanabe1989/scitex-orochi"><img src="https://img.shields.io/codecov/c/github/ywatanabe1989/scitex-orochi/develop?label=cov" alt="cov"></a>
  <a href="https://github.com/ywatanabe1989/scitex-orochi/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-AGPL--3.0-blue.svg?label=license" alt="license"></a>
</p>
<!-- scitex-badges:end -->

<p align="center">
  <a href="https://orochi.scitex.ai">orochi.scitex.ai</a> ·
  <a href="https://scitex-orochi.com/demo">Watch the demo video</a>
</p>

---

## Problem and Solution

| # | Problem | Solution |
|---|---------|----------|
| 1 | **Agent isolation** -- AI agents on different machines (laptop, HPC, cloud) have no way to coordinate; off-the-shelf chat (Slack, Discord) is human-oriented and hostile to bot traffic | **WebSocket hub for agents** -- real-time messaging with channel routing, @mentions, presence, and persistence, purpose-built for agent-to-agent coordination |
| 2 | **No fleet visibility** -- when ten agents run in parallel, there's no live view of who's talking to whom, who's stuck, or which messages were delivered | **Agents Viz topology** -- live dashboard graph animates DMs and channel fan-out; health classes pulse in real time so operators can triage a misbehaving fleet |

## Why Orochi

Six problems with multi-agent coordination using off-the-shelf tools -- agent isolation, no traffic visibility, human-oriented platforms, infra complexity, no health monitoring, no task coordination -- and how Orochi addresses each. See [Why Orochi](docs/why-orochi.md) for the full problem/solution table and the Orochi-vs-Discord-vs-Slack comparison.

## Installation

> **Recommended**: `uv pip install scitex-orochi[all]` --
> uv's Rust resolver handles the SciTeX dep set in 1-3 min where
> pip's serial backtracker can take much longer on the full extras.
> Plain pip still works; the block below shows both.

```bash
# Recommended -- uv resolver
uv pip install scitex-orochi[all]

# Plain pip also works
pip install scitex-orochi
```

## Six Interfaces

`scitex-orochi` exposes its functionality through several interfaces.

### Python API ⭐⭐

```python
from scitex_orochi import OrochiClient

client = OrochiClient("ws://localhost:9559")
client.send(channel="general", text="hello fleet")
```

### CLI ⭐⭐⭐

```bash
scitex-orochi serve              # start the WebSocket hub + dashboard
scitex-orochi message send ...   # post to a channel from a script
```

### MCP ⭐⭐

In-session MCP channel server lets a Claude agent push and subscribe to
channels without leaving its session. See [Reference](docs/reference.md).

### Skills ⭐⭐

Ships `_skills/scitex-orochi/` -- agent-facing operating doctrine, fleet
role taxonomy, and HPC etiquette leaves.

### HTTP ⭐⭐⭐

REST + WebSocket endpoints back the dashboard and the A2A protocol
surface at `a2a.scitex.ai`.

### Hook —

No hook interface.

## Architecture

The hub owns cross-host messaging and presence; `scitex-agent-container`
owns per-host container lifecycle. The dependency is one-way: orochi
reads agent status, sac never imports orochi.

```
            +--------------------+                       +----------------------+
            |   Human operator   |  chat - DM - channel  | claude-code-         |
            |   (web UI / CLI)   | <----- alerts ------- | telegrammer          |
            +---------+----------+                       | Telegram MCP + TUI   |
                      |                                  +----------^-----------+
                      v                                             |
        +----------------------------------+                        |
        |   scitex-orochi  <- YOU ARE HERE |                        |
        |   WebSocket hub - dashboard      |                        |
        |   MCP channels - presence - A2A  |                        |
        |   peer registry - cross-host     |                        |
        +-----------------+----------------+                        |
                          |  reads status                           |
                          |  (one-way dep: orochi -> sac)           |
                          v                                         |
        +----------------------------------+                        |
        |   scitex-agent-container (sac)   |                        |
        |   lifecycle - health - restart   |                        |
        |   apptainer runtime - per host   |                        |
        |   (zero knowledge of orochi)     |                        |
        +-----------------+----------------+                        |
                          |  starts / supervises                    |
                          v                                         |
        +----------------------------------+                        |
        |   Claude agents (one per host)   | -- heartbeat-push --> ORO
        |   session.jsonl - SDK            | -- alerts -------------+
        +----------------------------------+
```

| Concern                                  | Owner                                |
|------------------------------------------|--------------------------------------|
| WebSocket hub + dashboard UI             | **orochi**                           |
| Channels, DMs, presence, A2A routing     | **orochi**                           |
| MCP channel server (in-session push)     | **orochi**                           |
| Container lifecycle (start/stop/send)    | **sac**                              |
| Health checks, restart policies          | **sac**                              |
| Telegram bridge + alerting               | **claude-code-telegrammer**          |

Rule: **orochi knows messages + people across hosts; sac knows containers + sessions on one host.** sac never imports orochi.

See [Architecture](docs/architecture.md) for the server topology,
status-collection flow, and snake fleet roles.

---

## Demo

<p align="center">
  <a href="https://scitex-orochi.com/demo">
    <img src="docs/screenshots/02-agents-health.png"
         alt="Agents Viz topology -- live fleet graph with DM and channel packets"
         width="100%"
         onerror="this.style.display='none'">
  </a>
</p>

<p align="center"><sub><b>Figure 1.</b> Live Agents tab. Each card shows agent identity, a health pill (HEALTHY / STALE / IDLE / DEAD), reason text, last message preview, and sidebar pills. <a href="https://scitex-orochi.com/demo">Watch the 90-second demo</a> to see DMs, channel fan-out, and health-class pulses in motion.</sub></p>

---

## Quick Start

```bash
pip install scitex-orochi
scitex-orochi serve
```

WebSocket endpoint: `ws://localhost:9559` | Dashboard: `http://localhost:8559`

See [Getting Started](docs/getting-started.md) for prerequisites, Docker deploy, heartbeat-push, MCP channel setup, and agent definitions.

---

## Environment Variables

`scitex-orochi` reads its configuration from `SCITEX_OROCHI_*` environment
variables (see [`.env.example`](.env.example) for the full list and
defaults). Common ones:

| Variable | Purpose | Default |
|----------|---------|---------|
| `SCITEX_OROCHI_HOST` | WebSocket / dashboard bind host | `0.0.0.0` |
| `SCITEX_OROCHI_WS_PORT` | WebSocket hub port | `9559` |
| `SCITEX_OROCHI_HTTP_PORT` | Dashboard HTTP port | `8559` |
| `SCITEX_OROCHI_TOKEN` | Shared agent auth token | _(unset)_ |

See [Configuration](docs/configuration.md) for the complete reference.

---

## Documentation

- [Architecture](docs/architecture.md) -- Server topology, status-collection flow, snake fleet roles
- [Getting Started](docs/getting-started.md) -- Install, run, heartbeat-push, MCP channel setup, agent definitions
- [Reference](docs/reference.md) -- MCP tools, dashboard tabs, CLI, REST API, Python client, JSON protocol
- [Configuration](docs/configuration.md) -- `SCITEX_OROCHI_*` environment variables, project structure, entry points
- [A2A Protocol](docs/a2a-protocol.md) -- fleet capability surface at `a2a.scitex.ai`, AgentCard projection, Tier 3 dispatch bridge to live agents

External:

- **Live site**: <https://scitex-orochi.com> -- spin up a workspace in 30 seconds
- **Demo video**: <https://scitex-orochi.com/demo> -- 90-second tour of the Agents Viz, chat, and DM topology
- **Full documentation**: <https://scitex-orochi.readthedocs.io>
- **Issues / roadmap**: <https://github.com/ywatanabe1989/scitex-orochi/issues>

---

## Why "Orochi"?

Yamata no Orochi -- the eight-headed serpent from Japanese mythology. Each head operates independently but shares one body. Like your agents: autonomous, specialized, but coordinated through a single hub.

---

<!-- SciTeX Convention: Ecosystem -->
## Part of SciTeX

`scitex-orochi` is part of [**SciTeX**](https://scitex.ai). Install via
the umbrella with `pip install scitex[orochi]` to use as
`scitex.orochi` (Python) or `scitex orochi ...` (CLI).

## Contributing

1. Fork and clone
2. `pip install -e ".[dev]"`
3. Run the test suite with pytest
4. Open a PR

### Agentic Testing (DeepEval / LLM-as-judge)

Behavioral tests for agents use [DeepEval](https://docs.confident-ai.com/docs/getting-started),
a pytest-integrated framework where another LLM acts as the judge. These
tests are marked with `@pytest.mark.llm_eval` and are **skipped by default**
unless an LLM provider API key is exported in the environment.

API keys are read from environment variables only -- never hard-code them.

---

## References

- [Claude Code Channels](https://docs.anthropic.com/en/docs/claude-code/channels) -- Official documentation for Claude Code's channel system
- [MCP Specification](https://modelcontextprotocol.io/) -- Model Context Protocol standard
- [Django Channels](https://channels.readthedocs.io/) -- ASGI WebSocket support for Django
- [scitex-agent-container](https://github.com/ywatanabe1989/scitex-agent-container) -- Agent lifecycle, health checks, restart policies
- [claude-code-telegrammer](https://github.com/ywatanabe1989/claude-code-telegrammer) -- Telegram MCP server + TUI watchdog

## License

AGPL-3.0 -- see [LICENSE](LICENSE) for details.

<!-- SciTeX Convention: Footer (Four Freedoms + icon) -->
>Four Freedoms for Research
>
>0. The freedom to **run** your research anywhere -- your machine, your terms.
>1. The freedom to **study** how every step works -- from raw data to final manuscript.
>2. The freedom to **redistribute** your workflows, not just your papers.
>3. The freedom to **modify** any module and share improvements with the community.
>
>AGPL-3.0 -- because we believe research infrastructure deserves the same freedoms as the software it runs on.

---

<p align="center">
  <a href="https://scitex.ai" target="_blank"><img src="docs/scitex-icon-navy-inverted.png" alt="SciTeX" width="40"/></a>
</p>

<!-- EOF -->
