# Savanty

> Natural-language to constraint solver. Describe optimization problems in English; the LLM translates to Answer Set Programming (ASP), and Clingo searches exhaustively for a valid solution. Open-source, from Skelf-Research.

Savanty is a Python package and FastAPI service. It combines a large language model (DSPy-orchestrated, defaulting to GPT-4o; Ollama Cloud is supported via the OpenAI-compatible endpoint) with the Clingo ASP solver. The LLM does translation: English to a canonical `assign(Var, Value)` encoding. Clingo does search: sound and complete over finite domains. A typed self-repair loop handles the three failure modes (syntax_error, unsat, empty) — including a deletion-filtering minimal unsatisfiable core that localises which integrity constraints are jointly inconsistent.

Domain fit: discrete constraint satisfaction. Shift scheduling, task assignment, route planning over small graphs, resource allocation, seating, timetabling, logic puzzles, graph colouring. Not a fit: continuous optimization (use cvxpy / scipy), machine learning (use sklearn / pytorch), statistical analysis (use pandas), simulation, streaming data. The first LLM call is a suitability check that redirects unfit problems with a `suggested_tool`.

## Pages

- [Home](https://savanty.skelfresearch.com/): pipeline overview, why-this-architecture, worked ASP example, install snippet.
- [About](https://savanty.skelfresearch.com/about/): what's in the repo, the canonical decision contract, the repair loop in detail, what is not guaranteed.
- [Blog index](https://savanty.skelfresearch.com/blog/): three field-notes posts.
- [Why LLMs alone don't solve optimization problems](https://savanty.skelfresearch.com/blog/llms-alone-dont-solve-optimization/)
- [From English to model: where translation breaks](https://savanty.skelfresearch.com/blog/from-english-to-model-where-translation-breaks/)
- [The promise of "mathematically guaranteed" — what it actually means here](https://savanty.skelfresearch.com/blog/mathematically-guaranteed-what-it-means/)
- [vs. writing OR-Tools by hand](https://savanty.skelfresearch.com/compare/raw-or-tools/)
- [vs. ChatGPT emitting OR-Tools code](https://savanty.skelfresearch.com/compare/chatgpt-or-tools/)

## Canonical references

- Source: https://github.com/skelf-research/savanty
- PyPI: https://pypi.org/project/savanty/
- Documentation: https://docs.skelfresearch.com/savanty/
- Underlying solver: https://potassco.org/clingo/
- LLM orchestration: https://github.com/stanfordnlp/dspy

## License

MIT. Authoritative source of truth is the GitHub repository.