c3-invoke 0.1.1

Unified interface to AI CLIs (Gemini, Claude, Codex) from Python or HTTP

C3 Invoke

Unified interface to AI CLIs (Gemini, Claude, Codex) from Python or HTTP.

Installation

pip install c3-invoke            # Core library (zero dependencies)
pip install c3-invoke[server]    # With FastAPI HTTP server

Quick Start

from c3_invoke import GeminiProvider, ClaudeProvider, parse_json_output
from c3_invoke.types import PromptRequest

# Call any AI CLI with a unified interface
gemini = GeminiProvider()
response = gemini.run(PromptRequest(prompt="Explain Python decorators"))
print(response.raw_output)

# Parse JSON from CLI output (handles markdown fences, embedded JSON)
data = parse_json_output(response.raw_output)

# Run multiple prompts in parallel
from c3_invoke import run_batch
responses = run_batch(gemini, [
    PromptRequest(prompt="Explain decorators"),
    PromptRequest(prompt="Explain generators"),
], max_workers=4)

Providers

Provider	CLI Binary	Status
GeminiProvider	gemini	Fully implemented
ClaudeProvider	claude	Fully implemented
CodexProvider	codex	Fully implemented

from c3_invoke import get_provider, list_providers

# Get a specific provider
provider = get_provider("claude")

# List all providers with availability status
for info in list_providers():
    print(f"{info.display_name}: {'available' if info.available else 'not found'}")

HTTP Server

pip install c3-invoke[server]
c3-invoke-server    # Starts on port 8766

Endpoint	Method	Description
/health	GET	Server status + available providers
/providers	GET	List all providers with availability
/providers/{name}/test	GET	Test specific provider
/prompt	POST	Send a single prompt to a provider
/batch	POST	Send multiple prompts in parallel

Example

# Single prompt
curl -X POST http://localhost:8766/prompt \
  -H "Content-Type: application/json" \
  -d '{"provider": "gemini", "prompt": "What is Python?"}'

# Batch prompts
curl -X POST http://localhost:8766/batch \
  -H "Content-Type: application/json" \
  -d '{"provider": "gemini", "prompts": [{"prompt": "Q1"}, {"prompt": "Q2"}]}'

Development

pip install -e ".[dev]"
pytest tests/ -v

Architecture

src/c3_invoke/
├── __init__.py             # Public API: get_provider(), list_providers()
├── types.py                # PromptRequest, PromptResponse, ProviderInfo
├── output.py               # parse_json_output()
├── pool.py                 # run_batch() — parallel execution
├── providers/
│   ├── base.py             # BaseProvider ABC
│   ├── gemini.py           # GeminiProvider
│   ├── claude.py           # ClaudeProvider
│   └── codex.py            # CodexProvider
└── server/                 # Optional FastAPI server
    ├── app.py
    ├── main.py
    └── routers/

Part of C3 Ecosystem

C3 Invoke is a standalone package in the C3 organization ecosystem. C3 Architecture Overview will be available soon.