Metadata-Version: 2.4
Name: ai-synapse
Version: 1.0.0
Summary: Free multi-provider AI SDK with terminal TUI, OpenAI-compatible API, and 27+ provider routing
Author: AI Engine Contributors
License: MIT
Project-URL: Homepage, https://github.com/mihir0209/AI_engine
Project-URL: Documentation, https://github.com/mihir0209/AI_engine/tree/main/docs
Project-URL: Repository, https://github.com/mihir0209/AI_engine
Project-URL: Issues, https://github.com/mihir0209/AI_engine/issues
Keywords: ai,llm,openai,anthropic,inference,free-ai,groq,gemini,sdk
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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 :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: python-dotenv>=0.19.0
Requires-Dist: pydantic>=2.5.0
Provides-Extra: server
Requires-Dist: aiohttp>=3.8.0; extra == "server"
Requires-Dist: fastapi<0.116.0,>=0.104.0; extra == "server"
Requires-Dist: uvicorn[standard]>=0.24.0; extra == "server"
Requires-Dist: starlette<0.37.0,>=0.36.0; extra == "server"
Requires-Dist: jinja2<3.2.0,>=3.1.0; extra == "server"
Requires-Dist: python-multipart>=0.0.6; extra == "server"
Requires-Dist: aiofiles>=23.0.0; extra == "server"
Requires-Dist: prometheus-client>=0.17.0; extra == "server"
Requires-Dist: slowapi>=0.1.0; extra == "server"
Provides-Extra: tui
Requires-Dist: textual>=1.0.0; extra == "tui"
Requires-Dist: rapidfuzz>=3.0.0; extra == "tui"
Requires-Dist: pillow>=10.0.0; extra == "tui"
Requires-Dist: rich-pixels>=3.0.0; extra == "tui"
Provides-Extra: all
Requires-Dist: ai-synapse[server]; extra == "all"
Requires-Dist: ai-synapse[tui]; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.20.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: openai>=2.0.0; extra == "dev"
Dynamic: license-file

# AI Synapse

[![PyPI](https://img.shields.io/pypi/v/ai-synapse)](https://pypi.org/project/ai-synapse/)
[![Python](https://img.shields.io/pypi/pyversions/ai-synapse)](https://pypi.org/project/ai-synapse/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![OpenAI Compatible](https://img.shields.io/badge/OpenAI-compatible-412991)]()

**Free multi-provider AI SDK** — drop-in OpenAI client, optional local server, and a terminal chat UI. Routes across 27+ providers with automatic failover, model caching, and intent-aware routing.

```bash
pip install ai-synapse          # SDK
pip install ai-synapse[tui]     # + terminal chat UI
pip install ai-synapse[all]    # SDK + TUI + server extras
```

---

## Terminal UI (recommended)

ChatGPT-style chat in your terminal:

```bash
python -m ai_engine tui
```

| Feature | How |
|--------|-----|
| Model picker | `F2` — search, favorites (☆), paginated list |
| Provider | `F3` — auto or pinned provider |
| Attach files | `@filename` fuzzy picker, or **Attach** button |
| Read file into prompt | `/read` + fuzzy picker |
| Slash commands | `/help`, `/persona`, `/export`, `/defaults`, … |
| Defaults | `/defaults` save · `/defaults clear` restore · shown in sidebar |
| Sidebar | `Ctrl+B` collapse · hidden scrollbar chat list |
| Copy | `Ctrl+C` / `y` — selection first, then last reply |

Data lives under `~/.ai-engine/` (chats, preferences, personas).

---

## Python SDK

No server required — call providers directly:

```python
from ai_engine import OpenAI

client = OpenAI()
response = client.chat.completions.create(
    model="llama-3.3-70b-versatile",
    messages=[{"role": "user", "content": "Hello!"}],
    provider="groq",  # optional; auto-routes if omitted
)
print(response.choices[0].message.content)
```

Streaming:

```python
stream = client.chat.completions.create(
    model="default",
    messages=[{"role": "user", "content": "Tell me a joke"}],
    stream=True,
)
for chunk in stream:
    piece = chunk.choices[0].delta.content or ""
    print(piece, end="", flush=True)
```

CLI:

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

---

## Local server (optional)

OpenAI-compatible HTTP API + web dashboard:

```bash
cp .env.example .env   # add free-tier API keys
pip install ai-synapse[server]
python -m ai_engine serve
# API: http://localhost:8000/v1/  ·  Docs: http://localhost:8000/docs
```

Use with the official OpenAI Python client:

```python
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="dummy")
```

---

## Providers

**No key:** Pollinations, Hermes, G4F proxies, OpenCode Zen, and more.

**Free tier (signup):** Groq, OpenRouter, Gemini, NVIDIA, Cerebras, Cloudflare, GitHub Models, Mistral, Cohere, Hugging Face, Vercel, Kilo.

**Bring your own key:** hcnsec, LLM7, PaxSenix, Ollama, self-hosted G4F.

Provider list and keys: see [docs/collect_api.md](docs/collect_api.md). CDN config sync can refresh provider definitions at runtime (`CDN_CONFIG_URL=default`).

---

## Configuration

```bash
cp .env.example .env
```

Set any keys you have — more keys mean more failover paths. The engine skips providers without credentials.

| Variable | Purpose |
|----------|---------|
| `GROQ_API_KEY` | Groq free tier |
| `OPENROUTER_API_KEY` | OpenRouter free models |
| `GEMINI_API_KEY` | Google Gemini |
| `GITHUB_TOKEN` | GitHub Models |
| … | See `.env.example` |

---

## Project layout

| Path | Role |
|------|------|
| `ai_engine/` | PyPI package — SDK, TUI, CLI |
| `core/` | Provider engine, cache, capabilities |
| `server.py` | Standalone FastAPI server (repo checkout) |
| `docs/` | API, deployment, security guides |

---

## Development

```bash
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/
```

---

## Documentation

- [API Reference](docs/API.md)
- [User Guide](docs/USER_GUIDE.md)
- [Deployment](docs/DEPLOYMENT.md)
- [Provider setup](docs/collect_api.md)

---

## License

MIT — see [LICENSE](LICENSE).
