<p align="center">
<img src="media/logo.png" alt="pi_optimal Logo" width="250"/>
</p>
<p align="center">
<a href="https://github.com/pi-optimal/pi-optimal/releases">
<img src="https://img.shields.io/github/v/release/pi-optimal/pi-optimal?color=blue" alt="Latest Release"/>
</a>
<a href="https://github.com/pi-optimal/pi-optimal/blob/main/LICENSE">
<img alt="License" src="https://img.shields.io/github/license/pi-optimal/pi-optimal"/>
</a>
</p>
<p align="center">
<strong>
<a href="https://pi-optimal.com">Website</a>
•
<a href="https://pi-optimal.readthedocs.io/en/stable/">Docs</a>
•
<a href="https://join.slack.com/t/pioptimal/shared_invite/zt-2w4z32qtt-Q7EdDvmSi9vWFCPb22_qVA">Community Slack</a>
</strong>
</p>
---
# 🤖 What is `pi_optimal`?
`pi_optimal` is an open-source Python library that helps you **model, optimize, and control complex systems through Reinforcement Learning (RL)**. Whether your system involves advertising delivery, energy consumption, inventory management, or any scenario where sequential decision-making is paramount, `pi_optimal` provides a flexible and modular interface to train, evaluate, and deploy RL-based policies.
Built for data scientists, RL practitioners, and developers, `pi_optimal`:
- Offers a **time-series aware RL pipeline**, handling lookback windows and forecasting future states.
- Supports **various action spaces** (continuous, discrete, or multi-dimensional), enabling complex control strategies.
- Integrates easily with **custom reward functions**, empowering you to tailor the agent’s objectives to your business goals.
- Facilitates **multi-step planning**, allowing you to look ahead and optimize future outcomes, not just the immediate next step.
If you find `pi_optimal` useful, consider joining our [community Slack](https://join.slack.com/t/pioptimal/shared_invite/zt-2w4z32qtt-Q7EdDvmSi9vWFCPb22_qVA) and give us a ⭐ on GitHub!
---
# 🎯 Why use `pi_optimal`?
In dynamic and complex systems, even experienced operators can struggle to find the best decisions at every step. `pi_optimal` helps you:
- **Automate Decision-Making:** Reduce human overhead by letting RL agents handle routine optimization tasks.
- **Optimize Performance Over Time:** Forecast system states and choose actions that yield smooth, cost-effective, or profit-maximizing trajectories.
- **Incorporate Uncertainty:** Account for uncertainty in future outcomes with built-in approaches to handle uncertain environments.
- **Seamlessly Integrate with Your Workflow:** `pi_optimal` fits easily with your existing code, data pipelines, and infrastructure.
---
# 🌐 Use Cases
- **Advertising Delivery Optimization:** Smooth out ad impressions over time, ensuring efficient, controlled delivery that meets pacing and budget constraints.
- **Energy Management:** Balance supply and demand, optimize resource allocation, and reduce operational costs.
- **Inventory and Supply Chain:** Manage stock levels, forecast demand, and plan orders for just-in-time deliveries.
- **Dynamic Pricing and Bidding:** Adjust bids, prices, and frequency caps in real-time to maximize revenue or reduce costs.
---
# 🚀 Getting Started
## Installation
`pi_optimal` uses [Poetry](https://python-poetry.org/) for dependency management and installation. Follow these steps to get started:
1. **Ensure you are not within a virtual environment** (e.g., deactivate it with `conda deactivate` if using Conda).
2. **Install Poetry** (if you don’t already have it):
```bash
pipx install poetry
```
3. **Clone the repository** and navigate to its directory:
```bash
git clone https://github.com/pi-optimal/pi-optimal.git
cd pi-optimal
```
4. **Install dependencies** using Poetry:
```bash
poetry install
```
Once you've completed the installation, you can open any notebook from the [notebooks](./notebooks) directory. To use the installed environment, select the newly created virtual environment in your Jupyter kernel selection. It should appear with a name similar to `pi-optimal-xyz-py3.10`.
## Example Usage
Below is a simplified excerpt demonstrating how `pi_optimal` can be applied to optimize ad delivery. For a more detailed walkthrough, refer to the [notebooks](./notebooks).
```python
import pandas as pd
import pi_optimal as po
# Load historical room climate control data
df_room_history = pd.read_csv('room_climate_history.csv')
# Prepare dataset: define states (e.g., room conditions), actions (e.g., heater settings), and reward (e.g., comfort level)
climate_dataset = po.datasets.TimeseriesDataset(
df_room_history,
state_columns=['temperature', 'humidity'],
action_columns=['heater_power'],
reward_column='comfort_score',
timestep_column='timestamp',
unit_index='room_id',
lookback_timesteps=8
)
# Train a reinforcement learning agent for climate control
climate_agent = po.Agent(dataset=climate_dataset, type="mpc-continuous", config={"uncertainty_weight": 0.5})
climate_agent.train()
# Load current room data to predict next actions
df_current_conditions = pd.read_csv('current_room_conditions.csv')
current_dataset = po.datasets.TimeseriesDataset(df_current_conditions, dataset_config=climate_dataset.dataset_config, lookback_timesteps=8, train_processors=False)
# Predict optimal heater settings for improved comfort
optimal_actions = climate_agent.predict(current_dataset)
print(optimal_actions)
```
---
# ✨ Features
1. **Time-Series Aware RL**:
Directly handle sequences, lookback windows, and rolling state representations.
2. **Flexible Action Spaces**:
Support for continuous and discrete actions, or complex multidimensional action vectors.
3. **Custom Reward Functions**:
Easily define domain-specific rewards to reflect real-world KPIs.
4. **Multi-Step Planning**:
Implement look-ahead strategies that consider future impacts of current actions.
5. **Data Processing and Visualization**:
Built-in tools for dataset preparation, trajectory visualization, and iterative evaluation.
---
# 📖 Documentation
- **Tutorials & Examples**: Walk through real-world examples to understand how to best apply `pi_optimal`.
- **API Reference**: Detailed documentation for all classes, methods, and functions.
- **Best Practices**: Learn recommended strategies for defining rewards, choosing architectures, and tuning hyperparameters.
[Read the Docs »](https://pi-optimal.readthedocs.io/en/stable/)
---
# 🤝 Contributing and Community
We welcome contributions from the community! If you have feature requests, bug reports, or want to contribute code:
- Open an issue on [GitHub Issues](https://github.com/pi-optimal/pi-optimal/issues).
- Submit a pull request with your proposed changes.
- Join our [Slack community](https://join.slack.com/t/pioptimal/shared_invite/zt-2w4z32qtt-Q7EdDvmSi9vWFCPb22_qVA) to ask questions, share ideas, or get help.
A big thanks to all contributors who make `pi_optimal` better every day!
---
# 🙋 Get Help
If you have questions or need assistance, the fastest way to get answers is via our [community Slack channel](https://join.slack.com/t/pioptimal/shared_invite/zt-2w4z32qtt-Q7EdDvmSi9vWFCPb22_qVA). Drop by and say hello!
---
# 🌱 Roadmap
Check out our [roadmap](https://github.com/pi-optimal/pi-optimal/projects) to see what we’re working on next. Have suggestions or would like to see a new feature prioritized? Let us know in our Slack or open an issue.
---
# 📜 License
`pi_optimal` is distributed under the GNU Affero General Public License (AGPL). See [LICENSE](LICENSE) for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "pi-optimal",
"maintainer": "Jochen Luithardt",
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": "jol@pi-optimal.com",
"keywords": "rl, decision intelligence, reinforcement learning, decision-making, pi, optimal",
"author": "pi-optimal UG (haftungsbeschr\u00e4nkt)",
"author_email": "hello@pi-optimal.com",
"download_url": "https://files.pythonhosted.org/packages/2d/7e/3b54f7f65dbe04a3690f4cc5d5e7b53d19b3c064b9cc7e24fba71399c7d2/pi_optimal-0.1.1.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <img src=\"media/logo.png\" alt=\"pi_optimal Logo\" width=\"250\"/>\n</p>\n\n<p align=\"center\">\n <a href=\"https://github.com/pi-optimal/pi-optimal/releases\">\n <img src=\"https://img.shields.io/github/v/release/pi-optimal/pi-optimal?color=blue\" alt=\"Latest Release\"/>\n </a>\n <a href=\"https://github.com/pi-optimal/pi-optimal/blob/main/LICENSE\">\n <img alt=\"License\" src=\"https://img.shields.io/github/license/pi-optimal/pi-optimal\"/>\n </a>\n</p>\n\n<p align=\"center\">\n <strong>\n <a href=\"https://pi-optimal.com\">Website</a>\n \u2022\n <a href=\"https://pi-optimal.readthedocs.io/en/stable/\">Docs</a>\n \u2022\n <a href=\"https://join.slack.com/t/pioptimal/shared_invite/zt-2w4z32qtt-Q7EdDvmSi9vWFCPb22_qVA\">Community Slack</a>\n </strong>\n</p>\n\n---\n\n# \ud83e\udd16 What is `pi_optimal`?\n\n`pi_optimal` is an open-source Python library that helps you **model, optimize, and control complex systems through Reinforcement Learning (RL)**. Whether your system involves advertising delivery, energy consumption, inventory management, or any scenario where sequential decision-making is paramount, `pi_optimal` provides a flexible and modular interface to train, evaluate, and deploy RL-based policies.\n\nBuilt for data scientists, RL practitioners, and developers, `pi_optimal`:\n\n- Offers a **time-series aware RL pipeline**, handling lookback windows and forecasting future states.\n- Supports **various action spaces** (continuous, discrete, or multi-dimensional), enabling complex control strategies.\n- Integrates easily with **custom reward functions**, empowering you to tailor the agent\u2019s objectives to your business goals.\n- Facilitates **multi-step planning**, allowing you to look ahead and optimize future outcomes, not just the immediate next step.\n\nIf you find `pi_optimal` useful, consider joining our [community Slack](https://join.slack.com/t/pioptimal/shared_invite/zt-2w4z32qtt-Q7EdDvmSi9vWFCPb22_qVA) and give us a \u2b50 on GitHub!\n\n---\n\n# \ud83c\udfaf Why use `pi_optimal`?\n\nIn dynamic and complex systems, even experienced operators can struggle to find the best decisions at every step. `pi_optimal` helps you:\n\n- **Automate Decision-Making:** Reduce human overhead by letting RL agents handle routine optimization tasks.\n- **Optimize Performance Over Time:** Forecast system states and choose actions that yield smooth, cost-effective, or profit-maximizing trajectories.\n- **Incorporate Uncertainty:** Account for uncertainty in future outcomes with built-in approaches to handle uncertain environments.\n- **Seamlessly Integrate with Your Workflow:** `pi_optimal` fits easily with your existing code, data pipelines, and infrastructure.\n\n---\n\n# \ud83c\udf10 Use Cases\n\n- **Advertising Delivery Optimization:** Smooth out ad impressions over time, ensuring efficient, controlled delivery that meets pacing and budget constraints.\n- **Energy Management:** Balance supply and demand, optimize resource allocation, and reduce operational costs.\n- **Inventory and Supply Chain:** Manage stock levels, forecast demand, and plan orders for just-in-time deliveries.\n- **Dynamic Pricing and Bidding:** Adjust bids, prices, and frequency caps in real-time to maximize revenue or reduce costs.\n\n---\n\n# \ud83d\ude80 Getting Started\n\n## Installation\n\n`pi_optimal` uses [Poetry](https://python-poetry.org/) for dependency management and installation. Follow these steps to get started:\n\n1. **Ensure you are not within a virtual environment** (e.g., deactivate it with `conda deactivate` if using Conda). \n2. **Install Poetry** (if you don\u2019t already have it):\n\n ```bash\n pipx install poetry\n ```\n\n3. **Clone the repository** and navigate to its directory:\n\n ```bash\n git clone https://github.com/pi-optimal/pi-optimal.git\n cd pi-optimal\n ```\n\n4. **Install dependencies** using Poetry:\n\n ```bash\n poetry install\n ```\n\nOnce you've completed the installation, you can open any notebook from the [notebooks](./notebooks) directory. To use the installed environment, select the newly created virtual environment in your Jupyter kernel selection. It should appear with a name similar to `pi-optimal-xyz-py3.10`.\n\n\n## Example Usage\n\nBelow is a simplified excerpt demonstrating how `pi_optimal` can be applied to optimize ad delivery. For a more detailed walkthrough, refer to the [notebooks](./notebooks).\n\n```python\nimport pandas as pd\nimport pi_optimal as po\n\n# Load historical room climate control data\ndf_room_history = pd.read_csv('room_climate_history.csv')\n\n# Prepare dataset: define states (e.g., room conditions), actions (e.g., heater settings), and reward (e.g., comfort level)\nclimate_dataset = po.datasets.TimeseriesDataset(\n df_room_history,\n state_columns=['temperature', 'humidity'],\n action_columns=['heater_power'],\n reward_column='comfort_score',\n timestep_column='timestamp',\n unit_index='room_id',\n lookback_timesteps=8\n)\n\n# Train a reinforcement learning agent for climate control\nclimate_agent = po.Agent(dataset=climate_dataset, type=\"mpc-continuous\", config={\"uncertainty_weight\": 0.5})\nclimate_agent.train()\n\n# Load current room data to predict next actions\ndf_current_conditions = pd.read_csv('current_room_conditions.csv')\ncurrent_dataset = po.datasets.TimeseriesDataset(df_current_conditions, dataset_config=climate_dataset.dataset_config, lookback_timesteps=8, train_processors=False)\n\n# Predict optimal heater settings for improved comfort\noptimal_actions = climate_agent.predict(current_dataset)\nprint(optimal_actions)\n```\n\n---\n\n# \u2728 Features\n\n1. **Time-Series Aware RL**: \n Directly handle sequences, lookback windows, and rolling state representations.\n\n2. **Flexible Action Spaces**: \n Support for continuous and discrete actions, or complex multidimensional action vectors.\n\n3. **Custom Reward Functions**: \n Easily define domain-specific rewards to reflect real-world KPIs.\n\n4. **Multi-Step Planning**: \n Implement look-ahead strategies that consider future impacts of current actions.\n\n5. **Data Processing and Visualization**: \n Built-in tools for dataset preparation, trajectory visualization, and iterative evaluation.\n\n---\n\n# \ud83d\udcd6 Documentation\n\n- **Tutorials & Examples**: Walk through real-world examples to understand how to best apply `pi_optimal`.\n- **API Reference**: Detailed documentation for all classes, methods, and functions.\n- **Best Practices**: Learn recommended strategies for defining rewards, choosing architectures, and tuning hyperparameters.\n\n[Read the Docs \u00bb](https://pi-optimal.readthedocs.io/en/stable/)\n\n---\n\n# \ud83e\udd1d Contributing and Community\n\nWe welcome contributions from the community! If you have feature requests, bug reports, or want to contribute code:\n\n- Open an issue on [GitHub Issues](https://github.com/pi-optimal/pi-optimal/issues).\n- Submit a pull request with your proposed changes.\n- Join our [Slack community](https://join.slack.com/t/pioptimal/shared_invite/zt-2w4z32qtt-Q7EdDvmSi9vWFCPb22_qVA) to ask questions, share ideas, or get help.\n\nA big thanks to all contributors who make `pi_optimal` better every day!\n\n---\n\n# \ud83d\ude4b Get Help\n\nIf you have questions or need assistance, the fastest way to get answers is via our [community Slack channel](https://join.slack.com/t/pioptimal/shared_invite/zt-2w4z32qtt-Q7EdDvmSi9vWFCPb22_qVA). Drop by and say hello!\n\n---\n\n# \ud83c\udf31 Roadmap\n\nCheck out our [roadmap](https://github.com/pi-optimal/pi-optimal/projects) to see what we\u2019re working on next. Have suggestions or would like to see a new feature prioritized? Let us know in our Slack or open an issue.\n\n---\n\n# \ud83d\udcdc License\n\n`pi_optimal` is distributed under the GNU Affero General Public License (AGPL). See [LICENSE](LICENSE) for details.\n\n",
"bugtrack_url": null,
"license": "AGPL-3.0-or-later",
"summary": "Python package for easy, data-efficient RL-based decision-making in business applications.",
"version": "0.1.1",
"project_urls": {
"documentation": "https://pi-optimal.com/docs/getting-started",
"homepage": "https://pi-optimal.com/",
"repository": "https://github.com/pi-optimal/pi-optimal"
},
"split_keywords": [
"rl",
" decision intelligence",
" reinforcement learning",
" decision-making",
" pi",
" optimal"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0cdae5b013035a66c79fd95baf5b4da79432cd1039edddd543fba09376457fe4",
"md5": "3587dfdde19f23e02e01b1e54fde6c50",
"sha256": "9c1b9b22b24382241414602b240eb4c7fcdb60886381539dce2973edcf2989fb"
},
"downloads": -1,
"filename": "pi_optimal-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3587dfdde19f23e02e01b1e54fde6c50",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 59345,
"upload_time": "2025-01-31T15:37:59",
"upload_time_iso_8601": "2025-01-31T15:37:59.612693Z",
"url": "https://files.pythonhosted.org/packages/0c/da/e5b013035a66c79fd95baf5b4da79432cd1039edddd543fba09376457fe4/pi_optimal-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2d7e3b54f7f65dbe04a3690f4cc5d5e7b53d19b3c064b9cc7e24fba71399c7d2",
"md5": "33482e6195921b1e1abf31685752ab54",
"sha256": "a08e7a2506f38ef7c936c4a42e481a60dd520d14d312a1eb51a72c549cf83dab"
},
"downloads": -1,
"filename": "pi_optimal-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "33482e6195921b1e1abf31685752ab54",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 51559,
"upload_time": "2025-01-31T15:38:01",
"upload_time_iso_8601": "2025-01-31T15:38:01.568966Z",
"url": "https://files.pythonhosted.org/packages/2d/7e/3b54f7f65dbe04a3690f4cc5d5e7b53d19b3c064b9cc7e24fba71399c7d2/pi_optimal-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-31 15:38:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pi-optimal",
"github_project": "pi-optimal",
"github_not_found": true,
"lcname": "pi-optimal"
}
JSON
