Metadata-Version: 2.4
Name: smart-router-ns
Version: 0.1.0
Summary: Plug-and-play LLM router for agents, MCP tools, and models
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: litellm
Requires-Dist: instructor[litellm]
Requires-Dist: pydantic
Requires-Dist: pyyaml
Requires-Dist: python-dotenv
Dynamic: license-file

# Smart Router

Plug-and-play LLM router for agents, MCP tools, and models. The Python import
package is named `src`.

## Install

```bash
pip install smart-router-ns
```

Set the API key for the provider used by the model in your routes file. For the
Gemini model below:

```bash
export GEMINI_API_KEY="your-gemini-api-key"
```

Alternatively, create a `.env` file in your working directory with that setting.
Do not commit or share your `.env` file.

## Configure routes

Create a `routes.yaml` file in your working directory. This minimal example
shows the supported structure and route types:

```yaml
version: 1
default_route: general_chat
confidence_threshold: 0.70
max_history_messages: 10
model: "gemini/gemini-3.5-flash-lite"
temperature: 0.0

routes:
	- id: general_chat
		type: model
		description: Handles general questions and conversation.
		examples:
			- "Explain vector databases simply."

	- id: web_research
		type: mcp
		description: Finds current information on the public web.
		examples:
			- "Find the latest Azure AI Search pricing."

	- id: clarify
		type: fallback
		description: Asks for clarification when a request is ambiguous.
```

Route `type` must be `agent`, `mcp`, `model`, or `fallback`. Use a LiteLLM
model identifier and configure the corresponding provider API key in your
environment.

## Use

```python
from src import SmartRouter

router = SmartRouter(routes_file="routes.yaml")
decision = router.route("What is the latest Azure AI Search pricing?")
print(decision.model_dump_json(indent=2))
```

The routes file path is relative to the current working directory. Decisions
are appended to `router_logs.jsonl` in that directory.

## Build and publish

```bash
python -m pip install --upgrade build twine
python -m build
python -m twine check dist/*
python -m twine upload dist/*
```

Create a PyPI API token in your PyPI account before uploading. When prompted by
Twine, use `__token__` as the username and paste the token as the password.
Never put the token in this README, source code, or a committed file. PyPI does
not allow reusing a published version number; increment `version` in
`pyproject.toml` for every new release.
