Metadata-Version: 2.4
Name: omnyx-hermes
Version: 0.1.2
Summary: Omnyx personality adaptation for Hermes desktop AI assistant
License: MIT
Requires-Python: >=3.10
Requires-Dist: click>=8.1.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: platformdirs>=4.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: websocket-client>=1.6.0
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# Omnyx Hermes Plugin

Personality-driven adaptation for [Hermes](https://github.com/nousresearch/hermes-agent) — the self-improving AI agent from Nous Research.

> **✅ NO FORK REQUIRED** — Uses Hermes' native MCP (Model Context Protocol) support

## Installation

```bash
pip install omnyx-hermes
```

## Quick Start (MCP Integration - Recommended)

```bash
# 1. Setup with your Omnyx dashboard API key
omnyx-hermes setup --api-key omx_your_key_here

# 2. Configure Hermes MCP (adds to ~/.hermes/config.yaml)
omnyx-hermes setup-hermes

# 3. Restart Hermes — Omnyx tools auto-discover
hermes

# 4. In Hermes chat, try: @omnyx get_profile
```

## Alternative: Bridge Mode (Legacy)

For proxy/WebSocket integration (requires Hermes configuration):

```bash
omnyx-hermes setup --api-key omx_your_key_here
omnyx-hermes run  # Start bridge service
```

## How It Works

Hermes is a **desktop AI assistant** that integrates with your OS (file system, applications, browser). Unlike Codex (terminal) or Devin (autonomous), Hermes is:
- **Always available** — hotkey-activated from anywhere
- **Context-aware** — sees your screen, knows your open files
- **Conversational** — ongoing chat history, not one-off commands

Omnyx Hermes adapts the assistant's **personality and interaction style**:

| Trait | Adaptation |
|-------|-----------|
| **High Conscientiousness** → | Structured responses, step-by-step plans, checklist format |
| **Low Conscientiousness** → | Free-form, brainstorming mode, "here are some ideas" |
| **High Openness** → | Creative suggestions, "what if we tried...", novel approaches |
| **Low Openness** → | Practical, proven solutions, conservative recommendations |
| **High Extraversion** → | Warm, enthusiastic, proactive suggestions, explains reasoning |
| **Low Extraversion** → | Direct, minimal pleasantries, gets to the point |
| **High Agreeableness** → | Collaborative tone, asks clarifying questions, checks understanding |
| **Low Agreeableness** → | Challenger mode, points out flaws, debate-style |
| **High Neuroticism** → | Cautious warnings, multiple fallback options, risk highlighting |
| **Low Neuroticism** → | Confident recommendations, assumes success, optimistic framing |

## Commands

```bash
omnyx-hermes setup              # Configure API key and preferences
omnyx-hermes start             # Start background bridge service
omnyx-hermes stop              # Stop the bridge service
omnyx-hermes status            # Show connection and profile
omnyx-hermes run               # Run bridge in foreground (debug mode)
omnyx-hermes config            # View/change settings
omnyx-hermes test "prompt"     # Test adaptation on a sample prompt
omnyx-hermes suggest           # Review pending personalization suggestions
omnyx-hermes forget            # Clear all local data
```

## Architecture

### MCP Mode (Recommended — No Fork)

```
┌─────────────┐ MCP   ┌──────────────────┐     ┌─────────────────┐
│   Hermes    │──────▶│  omnyx-hermes    │────▶│  Omnyx Backend  │
│   Agent     │◄──────│   MCP Server     │◄────│  (/api/agentic) │
│             │stdio   │  (stdio/HTTP)    │     │                 │
└─────────────┘       └──────────────────┘     └─────────────────┘

Hermes calls tools:
• omnyx_get_profile → Returns personality profile
• omnyx_adapt_prompt → Returns adapted prompt with context
• omnyx_get_context → Returns system prompt addition
```

The MCP server:
1. Runs as stdio server (managed by Hermes)
2. Exposes tools Hermes can call
3. Gets adaptation from Omnyx backend
4. Returns formatted results to Hermes

### Bridge Mode (Alternative)

WebSocket/HTTP proxy for scenarios where MCP isn't available:
```bash
omnyx-hermes run  # Starts WebSocket on localhost:8765
```

## MCP Tools

Once connected, Hermes can call these tools:

| Tool | Purpose |
|------|---------|
| `omnyx_get_profile` | Get personality profile and confidence |
| `omnyx_adapt_prompt` | Get personality-adapted prompt |
| `omnyx_get_context` | Get system prompt context |
| `omnyx_get_suggestions` | Check for pending suggestions |
| `omnyx_accept_suggestion` | Accept a suggestion |

## Configuration

Hermes MCP config is auto-installed by `setup-hermes`, or manually:

```yaml
# ~/.hermes/config.yaml
mcp_servers:
  omnyx:
    command: "omnyx-hermes"
    args: ["mcp"]
    env:
      OMNYX_API_KEY: "omx_your_key_here"
    enabled: true
```

## Privacy Modes

- **`raw_prompts`** (default): Full prompt context for best adaptation
- **`summaries_only`**: Send conversation summaries, not full history
- **`paused`**: No data transmission, Hermes runs normally

Configure: `omnyx-hermes config --privacy-mode summaries_only`

## Context Awareness

Hermes can share context with Omnyx:
- Active application (Chrome, VS Code, etc.)
- Selected text or file path
- Time of day (morning focus vs evening wind-down)

This enables **situationally-aware adaptation**:
- High C user + morning + coding task → "Let's plan your approach"
- Same user + evening + general chat → More relaxed, exploratory

## Suggestion System

After 20-30 interactions with >70% confidence, Omnyx may suggest:

> **"You often ask for code explanations after receiving solutions. Would you like me to proactively include brief explanations with all code responses?"**

Suggestions appear in the dashboard and can be accepted/dismissed. Accepted suggestions become part of the adaptation profile.
