| Name | savanty JSON |
| Version |
0.2.1
JSON |
| download |
| home_page | None |
| Summary | An intelligent optimization problem solver using LLMs and Answer Set Programming |
| upload_time | 2025-08-22 11:30:19 |
| maintainer | None |
| docs_url | None |
| author | Dipankar Sarkar |
| requires_python | <3.14,>=3.10 |
| license | MIT |
| keywords |
optimization
llm
asp
clingo
clorm
ai
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Savanty: Intelligent Optimization Problem Solver
[](https://badge.fury.io/py/savanty)
[](https://opensource.org/licenses/MIT)
Savanty is an intelligent Python library that leverages the power of Large Language Models (LLMs) and DSPy to parse, solve, and visualize optimization problems. It provides both a command-line interface and a web interface for users to input problem descriptions in natural language and automatically generates solutions using Answer Set Programming (ASP).
## 🌟 Features
- **Natural Language Processing**: Utilizes GPT-4 and DSPy for robust optimization problem parsing
- **Code Generation**: Automatically generates Clorm predicates and ASP programs
- **Problem Validation**: Validates if a problem can be solved with ASP before attempting to solve it
- **Interactive Gap Filling**: Asks for additional information when problem descriptions are incomplete
- **Problem Solving**: Implements optimization problem solving using Clingo
- **Dual Interface**: Command-line interface for direct usage and web interface for interactive solving
- **Modern Python Package**: Installable via pip with proper CLI integration
## 🚀 Quick Start
```bash
# Install Savanty
pip install savanty
# Set your OpenAI API key
export OPENAI_API_KEY=your_openai_api_key_here
# Solve a problem directly from the command line
savanty -p "Minimize x+y subject to x>=0, y>=0, x+y<=10"
# Or run the web interface
savanty --web --port 5000
```
## 📋 Prerequisites
- Python 3.8+
- An OpenAI API key
## 📦 Installation
### From PyPI (Recommended)
```bash
pip install savanty
```
### From Source
```bash
git clone https://github.com/terraprompt/savanty.git
cd savanty
pip install .
```
## ⚙️ Configuration
Savanty can be configured using environment variables:
```bash
# Required: Set your OpenAI API key
export OPENAI_API_KEY=your_openai_api_key_here
# Optional: Configure the LLM model (default: gpt-4o)
export SAVANTY_LLM_MODEL=gpt-4-turbo
# Optional: Set a custom Flask secret key
export FLASK_SECRET_KEY=your_flask_secret_key_here
```
## 🖥️ Usage
### Command Line Interface
Solve optimization problems directly from the command line:
```bash
# Solve a problem directly
savanty -p "We have a task scheduling problem. Each task has a name, duration, and priority. We need to schedule tasks within a maximum time of 10 units. Tasks cannot overlap. We want to maximize the total priority of scheduled tasks. Available tasks are: Task1: duration 3, priority 5; Task2: duration 2, priority 3; Task3: duration 4, priority 7; Task4: duration 1, priority 2."
# Run the web interface on a custom port
savanty --web --port 8080
```
### Interactive Problem Solving
When a problem description is incomplete, Savanty will ask for additional information:
```bash
savanty -p "Solve a scheduling problem"
# Savanty will ask: "What are the tasks and their properties?"
# You can then provide: "Task1: duration 3, priority 5; Task2: duration 2, priority 3"
```
### Web Interface
Run the web interface to solve problems interactively:
```bash
# Run on default port 5000
savanty --web
# Run on a custom port
savanty --web --port 8080
```
Then open your browser to `http://localhost:5000` (or your custom port) to access the web interface. The web interface also supports interactive gap filling - if your problem description is incomplete, Savanty will ask for additional information directly in the web interface.
### Python API
Use Savanty directly in your Python code:
```python
from savanty.solver import solve_optimization_problem
problem_description = """
We have a task scheduling problem. Each task has a name, duration, and priority.
We need to schedule tasks within a maximum time of 10 units.
Tasks cannot overlap.
We want to maximize the total priority of scheduled tasks.
Available tasks are:
Task1: duration 3, priority 5
Task2: duration 2, priority 3
Task3: duration 4, priority 7
Task4: duration 1, priority 2
"""
result = solve_optimization_problem(problem_description)
if result.needs_more_info:
print("Please provide more information:")
for question in result.questions:
print(f"- {question}")
elif result.error:
print(f"Error: {result.error}")
else:
print(f"Solution: {result.solution}")
```
## 💡 Example Use Cases
### 1. Task Scheduling Problem
```bash
savanty -p "Schedule tasks to maximize priority. TaskA (duration 3, priority 5), TaskB (duration 2, priority 4), TaskC (duration 4, priority 7). Time limit is 8 units. Tasks cannot overlap."
```
### 2. Resource Allocation
```bash
savanty -p "Allocate 3 projects to 2 teams. Project1 (value 100, requires 2 team members), Project2 (value 150, requires 3 team members), Project3 (value 80, requires 1 team member). Total team members available: 4. Maximize total value."
```
### 3. Knapsack Problem
```bash
savanty -p "Knapsack with capacity 10. Item1 (weight 5, value 10), Item2 (weight 4, value 7), Item3 (weight 6, value 12), Item4 (weight 2, value 3). Maximize value without exceeding capacity."
```
### 4. Graph Coloring
```bash
savanty -p "Color a graph with 4 nodes and edges: (1,2), (2,3), (3,4), (1,4). Use minimum number of colors such that adjacent nodes have different colors."
```
### 5. Sudoku Solver
```bash
savanty -p "Solve a 4x4 Sudoku puzzle. Given: position (1,1) = 1, position (1,3) = 2, position (2,2) = 3, position (3,1) = 4. Find values for all positions respecting Sudoku rules."
```
## 📁 Project Structure
```
savanty/
├── savanty/
│ ├── __init__.py
│ ├── cli.py # Command-line interface
│ ├── solver.py # Core solver logic
│ ├── dspy_modules.py # DSPy modules for LLM processing
│ └── templates/
│ └── index.html # Web interface template
├── tests/
├── pyproject.toml
├── README.md
└── LICENSE
```
## 🤝 Contributing
Contributions to Savanty are welcome! Please follow these steps:
1. Fork the repository
2. Create a new branch: `git checkout -b feature-branch-name`
3. Make your changes and commit them: `git commit -m 'Add some feature'`
4. Push to the original branch: `git push origin feature-branch-name`
5. Create the pull request
Alternatively, see the GitHub documentation on [creating a pull request](https://help.github.com/articles/creating-a-pull-request/).
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 📧 Contact
If you have any questions or feedback, please contact the maintainer:
Dipankar Sarkar - me@dipankar.name
Project Link: [https://github.com/terraprompt/savanty](https://github.com/terraprompt/savanty)
## 🙏 Acknowledgements
- [OpenAI](https://openai.com/) for providing the GPT-4 API
- [DSPy](https://github.com/stanfordnlp/dspy) for LLM prompting and optimization
- [Clingo](https://potassco.org/clingo/) for the ASP solver
- [Clorm](https://github.com/potassco/clorm) for Object-Relational Mapping with Clingo
- [Flask](https://flask.palletsprojects.com/) for the web framework
- [HTMX](https://htmx.org/) for dynamic HTML capabilities
- [Tailwind CSS](https://tailwindcss.com/) for styling
- [Click](https://click.palletsprojects.com/) for CLI creation
Raw data
{
"_id": null,
"home_page": null,
"name": "savanty",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.10",
"maintainer_email": null,
"keywords": "optimization, llm, asp, clingo, clorm, ai",
"author": "Dipankar Sarkar",
"author_email": "me@dipankar.name",
"download_url": "https://files.pythonhosted.org/packages/e2/e2/d05757467a98aa8e6c88d59079438bcf6f507056d1009556e294343acc38/savanty-0.2.1.tar.gz",
"platform": null,
"description": "# Savanty: Intelligent Optimization Problem Solver\n\n[](https://badge.fury.io/py/savanty)\n[](https://opensource.org/licenses/MIT)\n\nSavanty is an intelligent Python library that leverages the power of Large Language Models (LLMs) and DSPy to parse, solve, and visualize optimization problems. It provides both a command-line interface and a web interface for users to input problem descriptions in natural language and automatically generates solutions using Answer Set Programming (ASP).\n\n## \ud83c\udf1f Features\n\n- **Natural Language Processing**: Utilizes GPT-4 and DSPy for robust optimization problem parsing\n- **Code Generation**: Automatically generates Clorm predicates and ASP programs\n- **Problem Validation**: Validates if a problem can be solved with ASP before attempting to solve it\n- **Interactive Gap Filling**: Asks for additional information when problem descriptions are incomplete\n- **Problem Solving**: Implements optimization problem solving using Clingo\n- **Dual Interface**: Command-line interface for direct usage and web interface for interactive solving\n- **Modern Python Package**: Installable via pip with proper CLI integration\n\n## \ud83d\ude80 Quick Start\n\n```bash\n# Install Savanty\npip install savanty\n\n# Set your OpenAI API key\nexport OPENAI_API_KEY=your_openai_api_key_here\n\n# Solve a problem directly from the command line\nsavanty -p \"Minimize x+y subject to x>=0, y>=0, x+y<=10\"\n\n# Or run the web interface\nsavanty --web --port 5000\n```\n\n## \ud83d\udccb Prerequisites\n\n- Python 3.8+\n- An OpenAI API key\n\n## \ud83d\udce6 Installation\n\n### From PyPI (Recommended)\n\n```bash\npip install savanty\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/terraprompt/savanty.git\ncd savanty\npip install .\n```\n\n## \u2699\ufe0f Configuration\n\nSavanty can be configured using environment variables:\n\n```bash\n# Required: Set your OpenAI API key\nexport OPENAI_API_KEY=your_openai_api_key_here\n\n# Optional: Configure the LLM model (default: gpt-4o)\nexport SAVANTY_LLM_MODEL=gpt-4-turbo\n\n# Optional: Set a custom Flask secret key\nexport FLASK_SECRET_KEY=your_flask_secret_key_here\n```\n\n## \ud83d\udda5\ufe0f Usage\n\n### Command Line Interface\n\nSolve optimization problems directly from the command line:\n\n```bash\n# Solve a problem directly\nsavanty -p \"We have a task scheduling problem. Each task has a name, duration, and priority. We need to schedule tasks within a maximum time of 10 units. Tasks cannot overlap. We want to maximize the total priority of scheduled tasks. Available tasks are: Task1: duration 3, priority 5; Task2: duration 2, priority 3; Task3: duration 4, priority 7; Task4: duration 1, priority 2.\"\n\n# Run the web interface on a custom port\nsavanty --web --port 8080\n```\n\n### Interactive Problem Solving\n\nWhen a problem description is incomplete, Savanty will ask for additional information:\n\n```bash\nsavanty -p \"Solve a scheduling problem\"\n# Savanty will ask: \"What are the tasks and their properties?\"\n# You can then provide: \"Task1: duration 3, priority 5; Task2: duration 2, priority 3\"\n```\n\n### Web Interface\n\nRun the web interface to solve problems interactively:\n\n```bash\n# Run on default port 5000\nsavanty --web\n\n# Run on a custom port\nsavanty --web --port 8080\n```\n\nThen open your browser to `http://localhost:5000` (or your custom port) to access the web interface. The web interface also supports interactive gap filling - if your problem description is incomplete, Savanty will ask for additional information directly in the web interface.\n\n### Python API\n\nUse Savanty directly in your Python code:\n\n```python\nfrom savanty.solver import solve_optimization_problem\n\nproblem_description = \"\"\"\nWe have a task scheduling problem. Each task has a name, duration, and priority.\nWe need to schedule tasks within a maximum time of 10 units.\nTasks cannot overlap.\nWe want to maximize the total priority of scheduled tasks.\n\nAvailable tasks are:\nTask1: duration 3, priority 5\nTask2: duration 2, priority 3\nTask3: duration 4, priority 7\nTask4: duration 1, priority 2\n\"\"\"\n\nresult = solve_optimization_problem(problem_description)\n\nif result.needs_more_info:\n print(\"Please provide more information:\")\n for question in result.questions:\n print(f\"- {question}\")\nelif result.error:\n print(f\"Error: {result.error}\")\nelse:\n print(f\"Solution: {result.solution}\")\n```\n\n## \ud83d\udca1 Example Use Cases\n\n### 1. Task Scheduling Problem\n\n```bash\nsavanty -p \"Schedule tasks to maximize priority. TaskA (duration 3, priority 5), TaskB (duration 2, priority 4), TaskC (duration 4, priority 7). Time limit is 8 units. Tasks cannot overlap.\"\n```\n\n### 2. Resource Allocation\n\n```bash\nsavanty -p \"Allocate 3 projects to 2 teams. Project1 (value 100, requires 2 team members), Project2 (value 150, requires 3 team members), Project3 (value 80, requires 1 team member). Total team members available: 4. Maximize total value.\"\n```\n\n### 3. Knapsack Problem\n\n```bash\nsavanty -p \"Knapsack with capacity 10. Item1 (weight 5, value 10), Item2 (weight 4, value 7), Item3 (weight 6, value 12), Item4 (weight 2, value 3). Maximize value without exceeding capacity.\"\n```\n\n### 4. Graph Coloring\n\n```bash\nsavanty -p \"Color a graph with 4 nodes and edges: (1,2), (2,3), (3,4), (1,4). Use minimum number of colors such that adjacent nodes have different colors.\"\n```\n\n### 5. Sudoku Solver\n\n```bash\nsavanty -p \"Solve a 4x4 Sudoku puzzle. Given: position (1,1) = 1, position (1,3) = 2, position (2,2) = 3, position (3,1) = 4. Find values for all positions respecting Sudoku rules.\"\n```\n\n## \ud83d\udcc1 Project Structure\n\n```\nsavanty/\n\u251c\u2500\u2500 savanty/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 cli.py # Command-line interface\n\u2502 \u251c\u2500\u2500 solver.py # Core solver logic\n\u2502 \u251c\u2500\u2500 dspy_modules.py # DSPy modules for LLM processing\n\u2502 \u2514\u2500\u2500 templates/\n\u2502 \u2514\u2500\u2500 index.html # Web interface template\n\u251c\u2500\u2500 tests/\n\u251c\u2500\u2500 pyproject.toml\n\u251c\u2500\u2500 README.md\n\u2514\u2500\u2500 LICENSE\n```\n\n## \ud83e\udd1d Contributing\n\nContributions to Savanty are welcome! Please follow these steps:\n\n1. Fork the repository\n2. Create a new branch: `git checkout -b feature-branch-name`\n3. Make your changes and commit them: `git commit -m 'Add some feature'`\n4. Push to the original branch: `git push origin feature-branch-name`\n5. Create the pull request\n\nAlternatively, see the GitHub documentation on [creating a pull request](https://help.github.com/articles/creating-a-pull-request/).\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\udce7 Contact\n\nIf you have any questions or feedback, please contact the maintainer:\n\nDipankar Sarkar - me@dipankar.name\n\nProject Link: [https://github.com/terraprompt/savanty](https://github.com/terraprompt/savanty)\n\n## \ud83d\ude4f Acknowledgements\n\n- [OpenAI](https://openai.com/) for providing the GPT-4 API\n- [DSPy](https://github.com/stanfordnlp/dspy) for LLM prompting and optimization\n- [Clingo](https://potassco.org/clingo/) for the ASP solver\n- [Clorm](https://github.com/potassco/clorm) for Object-Relational Mapping with Clingo\n- [Flask](https://flask.palletsprojects.com/) for the web framework\n- [HTMX](https://htmx.org/) for dynamic HTML capabilities\n- [Tailwind CSS](https://tailwindcss.com/) for styling\n- [Click](https://click.palletsprojects.com/) for CLI creation\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "An intelligent optimization problem solver using LLMs and Answer Set Programming",
"version": "0.2.1",
"project_urls": {
"Repository": "https://github.com/skelf-research/savanty"
},
"split_keywords": [
"optimization",
" llm",
" asp",
" clingo",
" clorm",
" ai"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5c36a6ffdbcd32c1a60e39cb0dbf0481a81a7ef5ee4af08b8c03616ff94cedf4",
"md5": "ae1afa4d1c5d187e2c1d901d37e90fa1",
"sha256": "971d302e32307b8f868631335402987d28d204168c94185dbbef00c8e3394ad8"
},
"downloads": -1,
"filename": "savanty-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ae1afa4d1c5d187e2c1d901d37e90fa1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.10",
"size": 12191,
"upload_time": "2025-08-22T11:30:18",
"upload_time_iso_8601": "2025-08-22T11:30:18.452102Z",
"url": "https://files.pythonhosted.org/packages/5c/36/a6ffdbcd32c1a60e39cb0dbf0481a81a7ef5ee4af08b8c03616ff94cedf4/savanty-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e2e2d05757467a98aa8e6c88d59079438bcf6f507056d1009556e294343acc38",
"md5": "ae46a416001332779bf0fd9c853a72e6",
"sha256": "2a64fe60d55e7ec9b0ba45ac86d5345b361a35dda163c20883a0ab14a12fbb6a"
},
"downloads": -1,
"filename": "savanty-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "ae46a416001332779bf0fd9c853a72e6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.10",
"size": 12314,
"upload_time": "2025-08-22T11:30:19",
"upload_time_iso_8601": "2025-08-22T11:30:19.819848Z",
"url": "https://files.pythonhosted.org/packages/e2/e2/d05757467a98aa8e6c88d59079438bcf6f507056d1009556e294343acc38/savanty-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-22 11:30:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "skelf-research",
"github_project": "savanty",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "savanty"
}
