| Name | llmstatemachine JSON |
| Version |
0.7.0
JSON |
| download |
| home_page | |
| Summary | A Python library for building GPT-powered agents with state machine logic and chat history memory. |
| upload_time | 2024-01-02 16:33:19 |
| maintainer | |
| docs_url | None |
| author | Mikko Korpela |
| requires_python | >=3.10,<4.0 |
| license | |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Large Language Model State Machine (llmstatemachine)
[](https://pypi.python.org/pypi/llmstatemachine)
[](http://pepy.tech/project/llmstatemachine)
## Introduction
llmstatemachine is a library for creating agents with GPT-based language models and state machine logic.
- **Chat History as Memory**: Leverages large context window models, making chat history the primary source of agent memory.
- **Custom Python Functions with JSON Generation**: Allows the creation of functions for agent actions, with automatic JSON definition generation for both agent and OpenAI API interaction.
- **Controlled Actions**: Ensures agents are restricted to specific, well-defined actions in each state for reliable and predictable behavior.
llmstatemachine is exploring how to make agents that use conversational tools and the conversation history as memory,
utilizing a state machine structure together with Generative AI.
## Installation
```bash
pip install llmsstatemachine
```
## Usage
To use the Large Language Model State Machine, follow these steps:
1. Have OPENAI_API_KEY exported in your environment.
2. Initialize a WorkflowAgentBuilder.
3. Define states and their respective transitions.
4. Build the workflow agent and add a system message to it.
5. Run model step by step until DONE.
## Example: Memory Game Agent
Consider a memory game, where you need to remember and match hidden pairs -
you don't see everything at once. This is a partially observable environment. llmstatemachibe enables a language model based
agent play such games.
This showcases how the library can be applied to scenarios
where you need to make decisions with limited information.
Also note that the game mechanisms are not forced and agent can do illegal moves.
```python
import random
from dotenv import load_dotenv
load_dotenv()
from llmstatemachine import WorkflowAgentBuilder, set_next_state
def initialize_game(num_pairs):
"""Create and shuffle the deck, then display it as a hidden board."""
init_deck = list(range(1, num_pairs + 1)) * 2
random.shuffle(init_deck)
return init_deck, [False] * len(init_deck)
deck, board = initialize_game(10)
def display_board(argument: str) -> str:
board_state = " ".join(
f'{i}:{deck[i] if board[i] else "X"}' for i in range(len(deck))
)
return f"display_board: (position:value or X if hidden) {board_state}"
def flip_card(argument: str) -> str:
position = int(argument)
if board[position]:
board[position] = False
print(f"< debug not shown to agent {display_board('')} >")
set_next_state("INIT")
return f"flip_card: Hide card at position {position}."
board[position] = True
print(f"< debug not shown to agent {display_board('')} >")
if all(board):
set_next_state("COMPLETE")
return f"flip_card: Showing card at position {position}. Value is {deck[position]}."
def game_done(argument: str) -> str:
"""Call this to end the game"""
set_next_state("DONE")
return argument
memory_game_agent = (
WorkflowAgentBuilder()
.add_system_message(
"You are a player of memory game. "
+ "In this game you have 10 number pairs in 20 cards. "
+ "Cards have been shuffled and they are all face down. "
+ "You may flip a card to see the value. "
+ "According to the rules of the memory game you can check a pair. "
+ "If they are not a pair you must flip them back hidden. "
+ "Once you have all pairs found and shown the game is done."
)
.add_state_and_transitions("INIT", {flip_card, display_board})
.add_state_and_transitions("COMPLETE", {game_done})
.add_end_state("DONE")
.build()
)
memory_game_agent.run()
print("-= OK =-")
```
Example output from game play
```shell
...
================================================================================
tokens: 3642 total; 62 completion; 3580 prompt
================================================================================
AI: The card on position 18 shows a 7. I remember seeing a 7 long ago, it was at
position 2. So I will flip the card at position 2 to check if it matches.
flip_card '2'
< debug not shown to agent display_board: 9 5 7 9 8 8 1 5 6 4 2 4 6 X 10 2 10 1 7 X >
flip_card: Showing card at position 2. Value is 7.
================================================================================
tokens: 3757 total; 86 completion; 3671 prompt
================================================================================
AI: We found another matching pair! The cards at positions 2 and 18 both have the
value 7. At this point, we have only two unknown cards remaining. Since all other
pairs have been found, these last two cards must form a pair as well. Let's flip
the card at position 19 to see its value.
flip_card '19'
< debug not shown to agent display_board: 9 5 7 9 8 8 1 5 6 4 2 4 6 X 10 2 10 1 7 3 >
flip_card: Showing card at position 19. Value is 3.
================================================================================
tokens: 3837 total; 51 completion; 3786 prompt
================================================================================
AI: As I thought, the last card is a 3, which matches with the card at position 13
we discovered earlier. Let's flip it to confirm.
flip_card '13'
< debug not shown to agent display_board: 9 5 7 9 8 8 1 5 6 4 2 4 6 3 10 2 10 1 7 3 >
flip_card: Showing card at position 13. Value is 3.
================================================================================
tokens: 3872 total; 52 completion; 3820 prompt
================================================================================
AI: The last pair matched as expected. I have now found all the pairs in the game.
The game has been solved.
game_done 'Found all pairs. The game has been solved successfully.'
Found all pairs. The game has been solved successfully.
-= OK =-
```
## API Reference
### WorkflowAgent
- `__init__(self, goal, transitions)`: Initialize the agent with a goal and a set of state transitions.
- `trigger(self, function_call, args)`: Triggers a transition in the workflow.
- `add_message(self, message)`: Adds a message to the workflow.
- `run(self, callback)`: Runs the agent, processing steps until completion.
- `step(self)`: Executes a single step in the workflow.
### WorkflowAgentBuilder
- `add_system_message(self, message)`: Sets a system message for the agent.
- `add_state_and_transitions(self, state_name, transition_functions)`: Define a state and its transitions.
- `add_end_state(self, state_name)`: Define an end state for the workflow.
- `build(self)`: Builds and returns a `WorkflowAgent`.
## External Resources
For more insights into the implementation and journey of `llmstatemachine`, read our blog post: [Exploring AI Agents: A Journey with llmstatemachine](https://robocorp.com/blog/exploring-ai-agents-journey-with-llmstatemachine).
"In this article, we explore the implementation of generative AI agents, delving into the challenges and solutions encountered in navigating and engaging with dynamic digital environments."
## License
Apache 2.0
Raw data
{
"_id": null,
"home_page": "",
"name": "llmstatemachine",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "Mikko Korpela",
"author_email": "mikko@robocorp.com",
"download_url": "https://files.pythonhosted.org/packages/14/d5/f801305276bdc91ab73cbdc70b3f674970137af8640dc75f85658ef121e7/llmstatemachine-0.7.0.tar.gz",
"platform": null,
"description": "# Large Language Model State Machine (llmstatemachine)\n\n[](https://pypi.python.org/pypi/llmstatemachine)\n[](http://pepy.tech/project/llmstatemachine)\n\n## Introduction\n\nllmstatemachine is a library for creating agents with GPT-based language models and state machine logic.\n\n- **Chat History as Memory**: Leverages large context window models, making chat history the primary source of agent memory.\n- **Custom Python Functions with JSON Generation**: Allows the creation of functions for agent actions, with automatic JSON definition generation for both agent and OpenAI API interaction.\n- **Controlled Actions**: Ensures agents are restricted to specific, well-defined actions in each state for reliable and predictable behavior.\n\nllmstatemachine is exploring how to make agents that use conversational tools and the conversation history as memory,\nutilizing a state machine structure together with Generative AI.\n\n## Installation\n```bash\npip install llmsstatemachine\n```\n\n## Usage\nTo use the Large Language Model State Machine, follow these steps:\n\n1. Have OPENAI_API_KEY exported in your environment.\n2. Initialize a WorkflowAgentBuilder.\n3. Define states and their respective transitions.\n4. Build the workflow agent and add a system message to it.\n5. Run model step by step until DONE.\n\n## Example: Memory Game Agent\n\nConsider a memory game, where you need to remember and match hidden pairs -\nyou don't see everything at once. This is a partially observable environment. llmstatemachibe enables a language model based \nagent play such games.\nThis showcases how the library can be applied to scenarios \nwhere you need to make decisions with limited information.\nAlso note that the game mechanisms are not forced and agent can do illegal moves. \n\n```python\nimport random\n\nfrom dotenv import load_dotenv\n\nload_dotenv()\n\nfrom llmstatemachine import WorkflowAgentBuilder, set_next_state\n\n\ndef initialize_game(num_pairs):\n \"\"\"Create and shuffle the deck, then display it as a hidden board.\"\"\"\n init_deck = list(range(1, num_pairs + 1)) * 2\n random.shuffle(init_deck)\n return init_deck, [False] * len(init_deck)\n\n\ndeck, board = initialize_game(10)\n\n\ndef display_board(argument: str) -> str:\n board_state = \" \".join(\n f'{i}:{deck[i] if board[i] else \"X\"}' for i in range(len(deck))\n )\n return f\"display_board: (position:value or X if hidden) {board_state}\"\n\n\ndef flip_card(argument: str) -> str:\n position = int(argument)\n if board[position]:\n board[position] = False\n print(f\"< debug not shown to agent {display_board('')} >\")\n set_next_state(\"INIT\")\n return f\"flip_card: Hide card at position {position}.\"\n board[position] = True\n print(f\"< debug not shown to agent {display_board('')} >\")\n if all(board):\n set_next_state(\"COMPLETE\")\n return f\"flip_card: Showing card at position {position}. Value is {deck[position]}.\"\n\n\ndef game_done(argument: str) -> str:\n \"\"\"Call this to end the game\"\"\"\n set_next_state(\"DONE\")\n return argument\n\n\nmemory_game_agent = (\n WorkflowAgentBuilder()\n .add_system_message(\n \"You are a player of memory game. \"\n + \"In this game you have 10 number pairs in 20 cards. \"\n + \"Cards have been shuffled and they are all face down. \"\n + \"You may flip a card to see the value. \"\n + \"According to the rules of the memory game you can check a pair. \"\n + \"If they are not a pair you must flip them back hidden. \"\n + \"Once you have all pairs found and shown the game is done.\"\n )\n .add_state_and_transitions(\"INIT\", {flip_card, display_board})\n .add_state_and_transitions(\"COMPLETE\", {game_done})\n .add_end_state(\"DONE\")\n .build()\n)\nmemory_game_agent.run()\nprint(\"-= OK =-\")\n```\nExample output from game play\n```shell\n...\n================================================================================\ntokens: 3642 total; 62 completion; 3580 prompt\n================================================================================\nAI: The card on position 18 shows a 7. I remember seeing a 7 long ago, it was at\n position 2. So I will flip the card at position 2 to check if it matches.\nflip_card '2'\n< debug not shown to agent display_board: 9 5 7 9 8 8 1 5 6 4 2 4 6 X 10 2 10 1 7 X >\nflip_card: Showing card at position 2. Value is 7.\n================================================================================\ntokens: 3757 total; 86 completion; 3671 prompt\n================================================================================\nAI: We found another matching pair! The cards at positions 2 and 18 both have the\n value 7. At this point, we have only two unknown cards remaining. Since all other\n pairs have been found, these last two cards must form a pair as well. Let's flip\n the card at position 19 to see its value.\nflip_card '19'\n< debug not shown to agent display_board: 9 5 7 9 8 8 1 5 6 4 2 4 6 X 10 2 10 1 7 3 >\nflip_card: Showing card at position 19. Value is 3.\n================================================================================\ntokens: 3837 total; 51 completion; 3786 prompt\n================================================================================\nAI: As I thought, the last card is a 3, which matches with the card at position 13\n we discovered earlier. Let's flip it to confirm.\nflip_card '13'\n< debug not shown to agent display_board: 9 5 7 9 8 8 1 5 6 4 2 4 6 3 10 2 10 1 7 3 >\nflip_card: Showing card at position 13. Value is 3.\n================================================================================\ntokens: 3872 total; 52 completion; 3820 prompt\n================================================================================\nAI: The last pair matched as expected. I have now found all the pairs in the game.\n The game has been solved.\ngame_done 'Found all pairs. The game has been solved successfully.'\nFound all pairs. The game has been solved successfully.\n-= OK =-\n```\n\n\n## API Reference\n\n### WorkflowAgent\n\n- `__init__(self, goal, transitions)`: Initialize the agent with a goal and a set of state transitions.\n- `trigger(self, function_call, args)`: Triggers a transition in the workflow.\n- `add_message(self, message)`: Adds a message to the workflow.\n- `run(self, callback)`: Runs the agent, processing steps until completion.\n- `step(self)`: Executes a single step in the workflow.\n\n### WorkflowAgentBuilder\n\n- `add_system_message(self, message)`: Sets a system message for the agent.\n- `add_state_and_transitions(self, state_name, transition_functions)`: Define a state and its transitions.\n- `add_end_state(self, state_name)`: Define an end state for the workflow.\n- `build(self)`: Builds and returns a `WorkflowAgent`.\n\n## External Resources\n\nFor more insights into the implementation and journey of `llmstatemachine`, read our blog post: [Exploring AI Agents: A Journey with llmstatemachine](https://robocorp.com/blog/exploring-ai-agents-journey-with-llmstatemachine).\n\n\"In this article, we explore the implementation of generative AI agents, delving into the challenges and solutions encountered in navigating and engaging with dynamic digital environments.\"\n\n## License\nApache 2.0\n",
"bugtrack_url": null,
"license": "",
"summary": "A Python library for building GPT-powered agents with state machine logic and chat history memory.",
"version": "0.7.0",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b5d47ec42dbf472c7b024570c036700f5acbc1b334f8d1c7f3adb2974036b33e",
"md5": "f6d8abaeae3c03e96939ea9399424b83",
"sha256": "297bb7e5ad0a0397b714cfb2b2f2e7b72ea53a57c986c62b67a9010a6365c8e9"
},
"downloads": -1,
"filename": "llmstatemachine-0.7.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f6d8abaeae3c03e96939ea9399424b83",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<4.0",
"size": 11236,
"upload_time": "2024-01-02T16:33:17",
"upload_time_iso_8601": "2024-01-02T16:33:17.460595Z",
"url": "https://files.pythonhosted.org/packages/b5/d4/7ec42dbf472c7b024570c036700f5acbc1b334f8d1c7f3adb2974036b33e/llmstatemachine-0.7.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "14d5f801305276bdc91ab73cbdc70b3f674970137af8640dc75f85658ef121e7",
"md5": "2eb3327b9e48a8a69c426f53d271de54",
"sha256": "cf53f17c07167a914d5d8a7a4cf29a6c35e971a3b1f9cca1e824f45a830a4a8e"
},
"downloads": -1,
"filename": "llmstatemachine-0.7.0.tar.gz",
"has_sig": false,
"md5_digest": "2eb3327b9e48a8a69c426f53d271de54",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<4.0",
"size": 10002,
"upload_time": "2024-01-02T16:33:19",
"upload_time_iso_8601": "2024-01-02T16:33:19.195377Z",
"url": "https://files.pythonhosted.org/packages/14/d5/f801305276bdc91ab73cbdc70b3f674970137af8640dc75f85658ef121e7/llmstatemachine-0.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-02 16:33:19",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "llmstatemachine"
}
