ai-synapse 1.0.2

Free multi-provider AI SDK with OpenAI-compatible server and 27+ provider routing

AI Synapse

Free multi-provider AI SDK with drop-in OpenAI compatibility, intelligent routing across 27+ providers, and an optional local server. Use it as a Python library, run your own OpenAI-compatible API, or add the terminal chat UI on top.

pip install ai-synapse              # SDK — routing, failover, OpenAI client
pip install ai-synapse[server]      # SDK + local OpenAI-compatible server
pip install ai-synapse[all]         # SDK + server + terminal chat (TUI)

---

Python SDK

Drop-in OpenAI client that routes requests across free-tier and self-hosted providers with automatic failover, key rotation, and model caching.

from ai_engine import OpenAI

client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)

CLI (included with the SDK):

ai-engine chat "Explain quantum tunneling"
ai-engine providers
ai-engine version

More examples: examples/sdk/

---

Local server

Run an OpenAI-compatible HTTP API on your machine — same routing engine as the SDK, plus a web dashboard, provider management, metrics, and chat persistence.

mkdir -p ~/.ai-engine && cp .env.example ~/.ai-engine/.env
# edit ~/.ai-engine/.env — add provider API keys

pip install ai-synapse[server]
python -m ai_engine serve

Endpoint	URL
OpenAI API	http://localhost:8000/v1/
Swagger UI	http://localhost:8000/docs
Health	http://localhost:8000/health

Point any OpenAI SDK or tool at base_url="http://localhost:8000/v1":

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="dummy")
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Routed through AI Synapse server"}],
)

Server docs: API reference · Server guide · Deployment

---

Configuration

Provider API keys and settings load in layers. When the same variable appears in multiple places, the higher layer wins. Different names are merged.

Priority	Source	Typical use
1 (highest)	Shell / container env (export GROQ_API_KEY=…)	CI, Docker, secrets managers
2	AI_SYNAPSE_ENV=/path/to/profile.env	Named profiles (work.env, personal.env)
3	./.env in the current working directory	Git clone, venv, per-project overrides
4 (lowest)	~/.ai-engine/.env	Global config after pip install (any cwd)

Global setup (pip install)

mkdir -p ~/.ai-engine
cp .env.example ~/.ai-engine/.env
# edit ~/.ai-engine/.env — GROQ_API_KEY, OPENROUTER_API_KEY, etc.

Project overrides (venv / git clone)

# ~/.ai-engine/.env     → shared keys
# ./.env                → overrides only what differs in this project
pip install -e ".[server]"
python -m ai_engine serve

Explicit profile

AI_SYNAPSE_ENV=~/configs/ai-work.env python -m ai_engine serve

Optional paths

File	Purpose
~/.ai-engine/config.json	Provider priorities / enable flags
~/.ai-engine/data/	Model cache, CDN config cache

See .env.example and provider keys guide.

---

Terminal chat (optional)

A Textual-based terminal UI for interactive chat — built on the same SDK routing layer. Install only if you want a local chat app in the terminal.

pip install ai-synapse[tui]    # or ai-synapse[all]
python -m ai_engine tui

Sidebar history, model/provider routing, slash commands, @ file attach, and vision support. Full walkthrough: docs/TUI.md.

---

Documentation

Doc	Contents
API reference	HTTP endpoints (server)
Server guide	Dashboard, providers, metrics
User guide	Web dashboard & chat UI
Architecture	Routing, failover, caching
Provider keys	Free-tier signup
Deployment	Docker, production
TUI guide	Terminal chat (optional)

---

Development

git clone https://github.com/mihir0209/AI_engine.git
cd AI_engine
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,all]"
pytest tests/

---

License

MIT — see LICENSE.