{ "info": { "author": "Andrew Gree", "author_email": "andrew@criticalhop.com", "bugtrack_url": null, "classifiers": [ "Development Status :: 3 - Alpha", "Intended Audience :: Developers", "License :: OSI Approved :: BSD License", "Operating System :: POSIX :: Linux", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.7", "Topic :: Scientific/Engineering :: Artificial Intelligence", "Topic :: Software Development :: Libraries :: Python Modules" ], "description": "# Poodle - AI Planning in Python\n\n [](https://opensource.org/licenses/BSD-3-Clause) [](https://badge.fury.io/py/poodle) [](https://travis-ci.org/criticalhop/poodle)\n\nPoodle is the Python-to-PDDL compiler and automated programming framework in an early stage of development.\n\n# Rationale\n\n[PDDL](https://en.wikipedia.org/wiki/Planning_Domain_Definition_Language) is a widely-used language to describe [AI planning](https://en.wikipedia.org/wiki/Automated_planning_and_scheduling) [domains](http://www.cs.toronto.edu/~sheila/2542/w09/A1/introtopddl2.pdf). The applications include various [robotic planning problems](https://kcl-planning.github.io/ROSPlan/), scheduling, [logistics](https://github.com/pellierd/pddl4j/wiki/Logistics:-a-simple-running-example) and [manufacturing](https://ocharles.org.uk/posts/2018-12-25-fast-downward.html) optimization, writing intelligent agents in [computer games](https://www.researchgate.net/publication/228724581_Real-Time_Planning_for_Video-Games_A_Purpose_for_PDDL), real-time decision making, and even automated unix administration [[1]](https://www.youtube.com/watch?v=2veFbpiQv4k) [[2]](http://www.aiai.ed.ac.uk/project/oplan/oplan/applications.html). AI planning, and specifically model-based planning, can be explained as a problem-solving method where the software developer describes (models) a problem, rather than codes the algorithm to solve the problem - which is radically different from how the conventional software development is practically-always done today. Not having to invent and code the algorithm has obvious benefits: developer productivity goes to extremes, you can write software with humanly-impossible complexity of algorithms, any tasks that require combining actions into meaningful chains can now be automated.\n\nBut despite these extreme gains, AI planning-based software is virtually nonexistent. And there are reasons why imperative programming is so popular and logic programming is not. Imperative programming has a much lower barrier of entry. Realistically, the majority of problems are much easier to code in a \"usual\" imperative way rather than modeling the full domain. The tooling, ecosystem, coding paradigms, and the language itself are much more polished and well-designed. Finally, many software libraries and components were written, and are readily available, in imperative programming languages. \n\nPoodle aims to change that. The goal is to create a \"native merge\" of Python and model-based planning. This means that the developer will have an option to either write the algorithm or describe the problem and let the AI figure out the algorithm - with the result as usable in both options. The goal is to develop all the necessary tooling to enable full-scale production use of AI planning in real-world computing tasks - building on the top of a strong foundation created by the Python community.\n\nTranslating full Python programs into planning domain enables the use of efficient search methods to compose pre-built Python libraries into new algorithms. And a developer always gets an alternative to use the code imperatively - whenever she desires to switch. \n\n# Quickstart\n\n```shell\n$ pip install poodle # needs Python 3.7+\n```\n\nLet's say you have:\n\n```python\nfrom poodle import Object, xschedule\n\nclass World(Object): \n prepared: int\n said: bool \n\ndef hello(world: World):\n assert world.said == False\n world.prepared += 1\n\ndef world(world: World):\n assert world.prepared > 0\n world.said = True\n return \"Hello, world!\"\n\nw = World()\nw.prepared = 0\nw.said = False\n```\n\nNow you have two options:\n\n1. (obvious) execute natively, if you know the algorithm\n\n```python\nhello(w)\nprint(world(w)) \n# -> \"Hello, World!\"\n```\n\n2. if you don't know the parameters and/or sequence of execution - ask AI to figure out\n\n```python\nprint(xschedule(methods=[world, hello], space=[w], goal=lambda:w.said==True))\n# -> \"Hello, World!\"\n```\n\nThis will run the code on a hosted solver. To run a local solver, please scroll down to *Installation* section.\n\n# Overview\n\n## Introduction\n\nPoodle is a Python module that enables construction of complex planning and constraint satisfaction problems using familiar Pythonic paradigms in production environments. It is still in the early stage of development, but is already powering [*kubectl‑val*, our tool to prevent Kubernetes configuration errors](https://github.com/criticalhop/kubectl-val).\n\nPoodle introduces a pair of Python functions called `xschedule` and `schedule` that implement an automated planning mechanism, and a new base object `Object`:\n\n```python\nxschedule(\n methods=[...], # methods\n space=[...], # objects\n goal=lambda: ... # condition for final object state\n)\n```\n\nwhere `methods` is the list of methods that the planner should use to try to reach the goal state; `space` contains the list of `Object` objects that the planner will try to use as parameters for the methods, and `goal` is a simple end-state condition expressed as Python logical expression, usually a `lambda` function.\n\n`Object` is a special object type that knows how to translate itself to PDDL.\n\nTo understand how to construct a problem, let's start with a classic \"Hello, World\" function:\n\n```python\nfrom poodle import Object, xschedule\n\nclass World(Object): # a class that defines object that will hold final state\n said: bool # declaration of a bollean variable (Python 3 type hints)\n\ndef hello(world: World): # annotated function that mutates the state of `world`\n assert world.said == False # hint for the planner when this call is valid\n print(\"Hello, World!\")\n world.said = True # mutate the state of the parameter object\n\nw = World() # create first object instance\nw.said = False # define the value for `said` attribute\n\n# now execute this in an unfamiliar way ... \nxschedule(methods=[hello], space=[w], goal=lambda:w.said==True)\n```\n\nThis program will immediately print \"Hello, World!\" to the console, which looks obvious at first. What actually happened is that Poodle compiled your Python method into PDDL domain + problem and used AI planner to find that the final state is achievable by simply executing the only method, and all `assert`s are satisfied with our hero object `w`.\n\nIt is important to note that the more precisely you describe your task, the easier it is for the AI planner to figure out the algorithm. That is why Poodle enforces fully statically typed interface for all objects and methods in search space as a minimum selectivity requirement. This also saves you from a lot of bugs in bigger projects.\n\nLet's now jump to a more sophisticated example:\n\n## Monkey and Banana problem\n\n