https://github.com/moodlehq/asero
A very simple semantic router, using max scores and cosine similarity, to provide basic intent detection / classification wherever needed to.
https://github.com/moodlehq/asero
ai embeddings experiment intent research semantic
Last synced: 5 months ago
JSON representation
A very simple semantic router, using max scores and cosine similarity, to provide basic intent detection / classification wherever needed to.
- Host: GitHub
- URL: https://github.com/moodlehq/asero
- Owner: moodlehq
- License: bsd-3-clause
- Created: 2025-09-15T14:36:18.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-10-08T09:13:44.000Z (5 months ago)
- Last Synced: 2025-10-08T11:26:19.106Z (5 months ago)
- Topics: ai, embeddings, experiment, intent, research, semantic
- Language: Python
- Homepage:
- Size: 62.5 KB
- Stars: 1
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Asero - Semantic Router for Intent Classification
A(nother) semantic routing system that classifies user queries into hierarchical categories using OpenAI embeddings and cosine similarity.
## Features
- Hierarchical intent routing with configurable similarity thresholds
- Automatic embedding caching for performance optimization
- YAML-based configuration for routing tree structure
- Transactional updates to routing configuration
- OpenAI embedding model integration
## Requirements
- Python 3.12 and up.
- Access to any Open AI compatible endpoint (Ollama, LiteLLM, ...) with some embeddings model available.
## Quick start
1. Install it with `pip install .`
2. Setup the `.env` file (start with the provided `env_template`one).
3. Optionally, edit the `router_example.yaml` to define your routes.
4. Play with the routes using the `asero` CLI command.
5. That's all!
## Development
1. Install development dependencies: `pip install .[dev]`
2. Enable up pre-commit hooks: `pre-commit install`
3. Setup the `.env` file (start with the provided `env_template`one).
4. Hack, hack, hack (the `asero` CLI command, that runs `main.py`, should be enough)
5. Test, test, test. Try to cover as much as possible always.
(see the [Contributing](#Contributing) section for more details)
## Use as library
Don't forget to configure the `.env` file (see "Quick start" above).
```python
from asero import config as asero_config
from asero.router import SemanticRouter
# Load the configuration from a YAML file (see router_example.yaml)
config = asero_config.get_config("path/to/valid/router.yaml")
# Create a router instance
router = SemanticRouter(config)
# Start making queries (explore options in the SemanticRouter class)
matches = router.top_n_routes(query="Hi!")
# Or, for async contexts:
matches = await router.atop_n_routes(query="Hi!")
# Print the top matches (route, score, depth, leaf)
[print(match) for match in matches]
```
Will output something like:
```
('router_example/greetings/neutral', 0.9999999999999999, 3, True)
('router_example/chitchat', 0.48668323180162615, 2, True)
```
## License
This project is licensed under the BSD 3-Clause License. See the [LICENSE](LICENSE) file for more information.
## Contributing
We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for more details.
## Code of Conduct
Please note that this project adheres to a [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you agree to uphold this code.
----
© 2025 Moodle Research Team