Metadata-Version: 2.4
Name: omnimancer-cli
Version: 0.2.4
Summary: A unified command-line interface for multiple AI language models
Author-email: Kellan Strong <kellan@jite.ai>
License: MIT
Project-URL: Homepage, https://github.com/nvasion/omnimancer
Project-URL: Repository, https://github.com/nvasion/omnimancer
Project-URL: Issues, https://github.com/nvasion/omnimancer/issues
Keywords: ai,cli,chat,openai,claude,language-model
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: cryptography>=41.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: certifi>=2023.0.0
Requires-Dist: aiofiles>=23.0.0
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: html2text>=2020.1.16
Requires-Dist: jsonschema>=4.17.0
Requires-Dist: readability-lxml>=0.8.1
Requires-Dist: PyYAML>=6.0.0
Requires-Dist: toml>=0.10.2
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# Omnimancer

A multi-model coding agent for the terminal. One tool, any LLM.

Omnimancer works like `claude -p` but isn't locked to a single provider. Point it at Claude, OpenAI, Gemini, Bedrock, Ollama, or any of 13+ supported backends and get a coding agent that reads files, writes code, runs commands, and iterates autonomously — with streaming responses, token/cost tracking, and structured JSON output for pipeline integration.

## Install

```bash
pip install omnimancer-cli
```

## Usage

### Headless (pipeline mode)

```bash
# Single prompt, JSON output — like claude -p
omn -p "refactor auth.py to use dependency injection"

# Pipe context in
cat error.log | omn -p "diagnose this crash and suggest a fix"

# Use a specific provider and model.
# Note: the prompt must come right after -p; put other flags after it.
omn -p "write tests for src/api/routes.py" --provider claude --model claude-sonnet-4
omn -p "explain this codebase" --provider openai --model gpt-4o
omn -p "review this diff" --provider ollama < changes.patch

# Output formats
omn -p "summarize this repo"                                # plain text (default)
omn -p "summarize this repo" --output-format json           # structured JSON
omn -p "summarize this" --output-format stream-json         # streaming JSON

# Auto-approve all tool operations (CI/scripts)
omn -p "fix the failing tests" --dangerously-skip-permissions
```

Headless mode with `--output-format json` emits a single structured result
object — including the tool calls the agent made along the way:

```json
{
  "type": "result",
  "subtype": "success",
  "is_error": false,
  "result": "Here's the refactored code...",
  "session_id": "…",
  "model": "claude-sonnet-4-20250514",
  "num_turns": 3,
  "tool_calls": [
    {"name": "file_read", "arguments": {"path": "src/auth.py"}, "error": null},
    {"name": "file_write", "arguments": {"path": "src/auth.py"}, "error": null}
  ],
  "usage": {"input_tokens": 1523, "output_tokens": 892, "total_cost_usd": 0.04},
  "total_cost_usd": 0.04,
  "stop_reason": "end_turn"
}
```

On failure it stays valid JSON (stdout), with the error and any tool calls made:

```json
{"type": "result", "subtype": "error", "is_error": true, "error": "…", "tool_calls": [...]}
```

For a live, line-by-line stream of what the agent is doing (assistant text,
each `tool_use`, each `tool_result`, then the final `result`), use
`--output-format stream-json`.

### Interactive mode

```bash
omn                        # start interactive REPL
omn --provider openai      # start with a specific provider
omn --no-approval          # skip approval prompts
```

Interactive mode gives you a REPL with streaming responses, token/cost display, and agent capabilities:

```
>>> read src/main.py and add error handling
[text streams in real-time as the model generates]
  tokens: 1523 in / 892 out | ~$0.0134

>>> /switch openai gpt-4o
>>> now review what we just changed
[switches to OpenAI, continues conversation]
```

### Streaming responses

Responses stream token-by-token as the model generates, so you see output immediately instead of waiting for the full response. After each response, a token/cost summary is displayed.

Streaming is automatic for providers that support it. Other providers fall back to displaying the full response once complete — no configuration needed.

| Provider | Streaming |
|----------|:---------:|
| Claude (Anthropic) | Yes |
| All others | Fallback (full response) |

Streaming works in both regular chat and agent mode (tool calling flow). The display uses a live-updating terminal panel that refreshes at 15fps.

### Agent mode

When agent mode is enabled (`/agent on`), the AI can autonomously:

- **Read and write files** with approval workflow
- **Execute shell commands** with security validation
- **Search codebases** with fuzzy file matching (70% similarity threshold)
- **Make HTTP requests** for API testing

All destructive operations require explicit approval. Reads and searches are auto-approved.

Providers that support native tool calling (Claude, OpenAI, Gemini) use structured function calls. Others fall back to operation markers parsed from the response text.

```
>>> /agent on
>>> fix the failing test in tests/test_auth.py
[agent reads test file, reads source, edits code, runs pytest, iterates]
  tokens: 4210 in / 1893 out | ~$0.0412
```

## Supported Providers

| Provider | Tool Calling | Streaming | Notes |
|----------|:---:|:---:|-------|
| **Claude** (Anthropic) | Yes | Yes | Primary target. Best coding performance. |
| **OpenAI** | Yes | Fallback | GPT-4o, o1, etc. |
| **Gemini** (Google) | Yes | Fallback | Large context window. |
| **AWS Bedrock** | Yes | Fallback | Claude/Titan via AWS. |
| **Ollama** | No | Fallback | Local models. No API key needed. |
| **xAI** (Grok) | Yes | Fallback | |
| **Mistral** | No | Fallback | |
| **Perplexity** | No | Fallback | Web search built-in. |
| **Azure OpenAI** | Yes | Fallback | Enterprise Azure deployment. |
| **Vertex AI** | Yes | Fallback | Google Cloud deployment. |
| **OpenRouter** | No | Fallback | Access to 100+ models. |
| **DigitalOcean** | No | Fallback | OpenAI-compatible GenAI inference. Custom endpoint supported. |
| **Cohere** | No | Fallback | |

"Fallback" means the provider works but sends the full response at once instead of streaming token-by-token. The UI handles both modes transparently.

## Commands

| Command | Description |
|---------|-------------|
| `/help [command]` | Show help (optionally for a specific command) |
| `/quit` | Exit (also: `/exit`, Ctrl+D) |
| `/clear` | Clear terminal screen |
| `/switch <provider> [model]` | Switch provider or model |
| `/models [filter]` | List available models |
| `/providers` | List all providers with status |
| `/agent on\|off\|status` | Toggle agent mode |
| `/config show\|get\|set` | View or modify configuration |
| `/config set-provider <name> [--api-key …] [--base-url …] [--model …]` | Create/update a provider |
| `/config remove-provider <name>` | Remove a provider |
| `/validate [provider]` | Validate provider configurations |
| `/health [provider]` | Check provider health |
| `/save [name]` | Save conversation |
| `/load [name]` | Load conversation |
| `/list` | List saved conversations |
| `/history` | Manage conversation history |
| `/tools` | Show available MCP tools |
| `/mcp status\|health\|reload` | MCP server management |
| `/status` | System status |

## Configuration

### API keys

The simplest setup is environment variables:

```bash
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export GOOGLE_API_KEY="..."
export XAI_API_KEY="..."
omn
```

### Config file

Config is stored in `~/.omnimancer/config.json` (API keys are encrypted at rest).
You can edit it directly or, more conveniently, configure everything from the CLI:

```bash
omn
# Configure a provider in one step (api key is encrypted before storage)
>>> /config set-provider claude --api-key sk-ant-...
>>> /config set-provider openai --api-key sk-... --model gpt-4o
>>> /config set-provider openrouter --api-key sk-or-... --model anthropic/claude-3.5-sonnet

# Set or change individual fields
>>> /config set providers.openai.base_url https://my-proxy.example.com/v1
>>> /config set providers.openai.max_tokens 8192
>>> /config set default_provider claude

# Inspect / clean up
>>> /config show
>>> /config get default_provider
>>> /config remove-provider openai
```

### Multiple endpoints

Each of these is just a provider you can point anywhere via `base_url`, so you can run
several endpoints side by side and switch between them with `/switch <provider>`:

| Endpoint | Provider name | Default base URL |
|----------|---------------|------------------|
| Claude (direct) | `claude` | `https://api.anthropic.com/v1` |
| OpenAI | `openai` | `https://api.openai.com/v1` |
| OpenRouter | `openrouter` | `https://openrouter.ai/api/v1` |
| DigitalOcean inference | `digitalocean` | `https://inference.do-ai.run/v1` |

Any OpenAI-compatible service (local proxy, gateway, self-hosted model) works by
overriding `base_url` on the `openai` provider.

### Environment variable overrides

Environment variables take precedence over the saved config and are applied at
runtime only (never written back to disk). This makes them ideal for CI and for
testing endpoints without touching `config.json`.

```bash
# Conventional API keys
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export OPENROUTER_API_KEY="sk-or-..."
export DIGITALOCEAN_INFERENCE_KEY="..."

# Per-provider overrides: OMNIMANCER_<PROVIDER>_{API_KEY,BASE_URL,MODEL}
export OMNIMANCER_OPENAI_BASE_URL="http://localhost:1234/v1"
export OMNIMANCER_DIGITALOCEAN_MODEL="llama3.3-70b-instruct"

# Pick the default provider for this run
export OMNIMANCER_DEFAULT_PROVIDER="digitalocean"
omn
```

You can also override the endpoint for a single headless run with `--base-url`:

```bash
omn -p "summarize README.md" --provider openai --base-url http://localhost:1234/v1
omn -p "explain this repo" --provider digitalocean --model llama3.3-70b-instruct
```

### Provider-specific setup

**Claude (Anthropic):**
```bash
export ANTHROPIC_API_KEY="sk-ant-..."
# Models: claude-sonnet-4, claude-opus-4, claude-3-5-sonnet
```

**OpenAI:**
```bash
export OPENAI_API_KEY="sk-..."
# Models: gpt-4o, gpt-4-turbo, gpt-3.5-turbo
```

**Google Gemini:**
```bash
export GOOGLE_API_KEY="..."
# Models: gemini-1.5-pro, gemini-1.5-flash
```

**AWS Bedrock:**
```bash
# Uses AWS credentials (env vars, ~/.aws/credentials, or IAM role)
export AWS_DEFAULT_REGION="us-east-1"
# Models: anthropic.claude-3-5-sonnet, amazon.titan
```

**OpenRouter:**
```bash
export OPENROUTER_API_KEY="sk-or-..."
# Models: anthropic/claude-3.5-sonnet, openai/gpt-4o, and 100+ more
```

**DigitalOcean inference (OpenAI-compatible):**
```bash
export DIGITALOCEAN_INFERENCE_KEY="..."
# Default endpoint: https://inference.do-ai.run/v1
# Models: llama3.3-70b-instruct, llama3-8b-instruct, openai-gpt-4o
# Override the endpoint if needed:
export OMNIMANCER_DIGITALOCEAN_BASE_URL="https://inference.do-ai.run/v1"
```

**Ollama (local, no API key):**
```bash
ollama serve
ollama pull llama3.1
omn
>>> /switch ollama llama3.1
```

**Azure OpenAI:**
```bash
export AZURE_OPENAI_API_KEY="..."
export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
```

## Architecture

```
omnimancer/
├── cli/                    # CLI interface (modular)
│   ├── interface.py       # Core REPL loop, streaming integration
│   ├── command_dispatch.py # Slash command handlers
│   ├── agent_loop.py      # Marker-based agent workflow
│   ├── tool_handler.py    # Native tool call execution
│   ├── system_prompts.py  # Prompt building
│   ├── display.py         # Terminal output & token status
│   └── completion.py      # Tab completion
├── core/                   # Engine & business logic
│   ├── engine.py          # Provider abstraction & streaming delegation
│   ├── agent_engine.py    # Autonomous agent capabilities
│   ├── models.py          # Data models (ChatResponse, StreamEvent, etc.)
│   └── agent/             # File ops, approval, security
├── providers/              # 13+ AI provider implementations
│   ├── base.py            # Provider interface (streaming fallback)
│   ├── claude.py          # Anthropic (native streaming & tool calling)
│   ├── openai.py          # OpenAI (native tool calling)
│   └── ...
├── ui/                     # Terminal UI components
│   └── streaming_display.py # Rich Live streaming display
└── mcp/                    # Model Context Protocol
```

### Streaming architecture

Streaming uses async generators that flow through the full stack:

```
Provider (SSE parsing) → Engine (delegation) → Interface (display routing)
                                                  ↓
                                          StreamingDisplay (Rich Live panel)
```

Each layer yields `StreamEvent` objects. Providers that don't implement real streaming get an automatic fallback in `BaseProvider` that wraps the full response in the same event format, so the UI code works identically for all providers.

## Development

```bash
git clone https://gitlab.com/jite-ai/omnimancer
cd omnimancer
pip install -e ".[dev]"
pytest tests/ -v
```

Tests follow TDD. 1,260 tests across providers, CLI, streaming, agent operations, and integration scenarios.

## License

MIT
