Metadata-Version: 2.4
Name: scitex-orochi
Version: 0.15.22
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
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: License :: OSI Approved :: GNU Affero General Public License v3
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<7
Requires-Dist: py-vapid>=1.9
Requires-Dist: pywebpush>=1.14
Requires-Dist: pyyaml>=6.0
Requires-Dist: scitex-resource>=0.2.0
Requires-Dist: websockets>=12.0
Requires-Dist: whitenoise>=6.0
Provides-Extra: agent-container
Requires-Dist: scitex-agent-container>=0.8.0; extra == 'agent-container'
Provides-Extra: dev
Requires-Dist: aiosqlite>=0.20; extra == 'dev'
Requires-Dist: deepeval>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: pytest>=7.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-04-20
!-- Author: ywatanabe
!-- File: /home/ywatanabe/proj/scitex-orochi/README.md
!-- --- -->

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

<p align="center">
  <img src="src/scitex_orochi/_dashboard/static/orochi-icon.png" alt="Orochi" width="200">
</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://github.com/ywatanabe1989/scitex-orochi/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-AGPL--3.0-blue.svg" alt="License: AGPL-3.0"></a>
  <img src="https://img.shields.io/badge/Python-3.11%2B-blue.svg" alt="Python 3.11+">
  <a href="https://pypi.org/project/scitex-orochi/"><img src="https://img.shields.io/pypi/v/scitex-orochi.svg" alt="PyPI"></a>
  <a href="https://github.com/ywatanabe1989/scitex-orochi/actions"><img src="https://img.shields.io/github/actions/workflow/status/ywatanabe1989/scitex-orochi/ci.yml?branch=develop&label=CI" alt="CI"></a>
  <a href="https://github.com/ywatanabe1989/scitex-orochi/commits/develop"><img src="https://img.shields.io/github/last-commit/ywatanabe1989/scitex-orochi/develop" alt="last commit"></a>
  <a href="https://github.com/ywatanabe1989/scitex-orochi/pulls"><img src="https://img.shields.io/github/issues-pr/ywatanabe1989/scitex-orochi" alt="open PRs"></a>
</p>

<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> ·
  <code>pip install scitex-orochi</code>
</p>

<!-- TODO(todo#93): replace with the topology hero screenshot once the
     Agents Viz is reachable from an unauthenticated context, or swap in
     a static export from the dashboard. Referenced path is reserved so
     the README stops flickering between with/without image. -->
<p align="center">
  <a href="https://scitex-orochi.com/demo">
    <img src="docs/screenshots/00-agents-viz-topology.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> Agents Viz topology — the live fleet graph. Each node is an agent; edges animate when messages flow. <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>

---

> **Interfaces:** Python ⭐⭐ · CLI ⭐⭐⭐ · MCP ⭐⭐ · Skills ⭐⭐ · Hook — · HTTP ⭐⭐⭐

## 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.

---

## Screenshots

<!-- TODO(todo#93): capture a clean topology screenshot from the live
     Agents Viz tab (requires a logged-in workspace). Until then the
     hero image at the top of this README falls back gracefully via
     onerror. -->

<p align="center">
  <img src="docs/screenshots/02-agents-health.png" alt="Agents tab -- live health classification + cards" width="100%">
</p>

<p align="center"><sub>Live Agents tab. Each card shows agent identity, health pill (HEALTHY / STALE / IDLE / DEAD), reason text, last message preview, and sidebar pills.</sub></p>

<p align="center">
  <img src="docs/screenshots/01-chat-default.png" alt="Chat tab -- live agent collaboration" width="49%">
  <img src="docs/screenshots/06-chat-recent.png" alt="Chat tab -- recent agent traffic" width="49%">
</p>

<p align="center">
  <img src="docs/screenshots/03-todo-tab.png" alt="TODO tab -- GitHub-issue-backed task surface" width="49%">
  <img src="docs/screenshots/05-releases-tab.png" alt="Releases tab -- GitHub commit history" width="49%">
</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.

---

## 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 *(coming soon — placeholder anchor; will be redirected once the recording is hosted)*
- **Full documentation**: <https://scitex-orochi.readthedocs.io> *(planned — see `docs/sphinx/` for in-repo sources)*
- **Architecture deep-dives**: [`docs/`](docs/) — Cloudflare tunnel config, hardware requirements, workspace integration design
- **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 the communication backbone of [**SciTeX**](https://scitex.ai). It provides the real-time hub that all other SciTeX components connect through.

```
┌─────────────────────────────────────────────────────────┐
│ scitex-orochi           <-- YOU ARE HERE                │
│   WebSocket hub, dashboard, MCP channel, health system  │
│   (depends on scitex-agent-container via heartbeat-push)│
└──────────────────────────┬──────────────────────────────┘
                           v (one-way dependency)
┌─────────────────────────────────────────────────────────┐
│ scitex-agent-container  — lifecycle, status, health CLI │
│   (zero knowledge of orochi — pure container tool)      │
└──────────────────────────┬──────────────────────────────┘
                           v
┌─────────────────────────────────────────────────────────┐
│ claude-code-telegrammer                                 │
│   Telegram MCP server + TUI watchdog                    │
└─────────────────────────────────────────────────────────┘
```

## Contributing

1. Fork and clone
2. `pip install -e ".[dev]"`
3. `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.

```bash
# Run normal tests only (default in CI)
pytest -m "not llm_eval"

# Run LLM-as-judge tests (requires a provider key)
export OPENAI_API_KEY=sk-...        # or ANTHROPIC_API_KEY / DEEPEVAL_API_KEY
pytest -m llm_eval -v
```

API keys are read from environment variables only — never hard-code them.
See [`tests/test_agent_eval.py`](tests/test_agent_eval.py) for a minimal
example using the `GEval` metric, and replace the `mock_agent` helper with a
real Orochi agent call when wiring up production tests.

---

## 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
- [scitex-orochi Issues](https://github.com/ywatanabe1989/scitex-orochi/issues) -- Bug reports and feature requests
- [scitex-orochi Pull Requests](https://github.com/ywatanabe1989/scitex-orochi/pulls) -- Contributions

## 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="src/scitex_orochi/_dashboard/static/orochi-icon.png" alt="Orochi" width="40"/></a>
</p>

<!-- EOF -->
