omnimancer-cli 0.1.15__tar.gz → 0.2.4__tar.gz

omnimancer_cli-0.2.4/PKG-INFO

@@ -0,0 +1,407 @@
+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