# AI Agent State Library
## What is it?
The AI Agent State Library is a library designed to manage the state and decision-making processes of AI agents. At its core, it implements the concept of finite state machines, a computational model used to design systems with a finite number of states and transitions between those states.
Key features of the library include:
1. **State Machine Creation**: It allows developers to define and create intricate state machines that model the behavior of AI agents.
2. **Flexible State Definition**: States can be customized with associated data and metadata, allowing for rich context within each state.
3. **Dynamic Transitions**: The library supports the creation of transitions between states, which can be conditional and trigger specific actions.
4. **State Transition Guards**: Implement conditions that must be met for transitions to occur, providing more control over state changes.
5. **Persistence**: Integration with ChromaDB enables efficient storage and retrieval of state machines, allowing for continuity across sessions or distributed systems.
6. **Visualization**: The library includes tools to visualize state machines, aiding in debugging and understanding complex agent behaviors.
7. **OpenAI Integration**: It leverages the OpenAI API for dynamic decision-making, allowing for more intelligent and adaptive state transitions.
## When is it useful?
The AI Agent State Library proves particularly valuable in scenarios such as:
- **Conversational AI**: Managing the flow and context of conversations, ensuring coherent and contextually appropriate responses.
- **Business Process Automation**: Modeling and executing complex workflows that involve decision points and varied paths based on different conditions.
- **Multi-Agent Systems**: Coordinating the behavior and interactions of multiple AI agents in a complex environment.
The library's flexibility and extensibility make it adaptable to a wide range of AI applications where managing complex state and behavior is crucial. Its integration with modern tools like ChromaDB for persistence and OpenAI for decision-making enhances its utility in creating sophisticated, adaptive AI systems.
By providing a structured way to design, implement, and manage AI agent behavior, the AI Agent State Library helps developers create more reliable, understandable, and maintainable AI systems, reducing the complexity often associated with developing intelligent agents.
## Features
- Create and manage complex state machines for AI agents
- Define custom states with associated data and metadata
- Create transitions between states with optional conditions and actions
- Implement state transition guards for controlled state changes
- Persist and retrieve state machines using ChromaDB
- Visualize state machines for easy understanding and debugging
- Integration with OpenAI's API for dynamic decision-making
## Installation
To install the AI Agent State Library, use pip:
```bash
pip install ai-agent-state
```
Make sure you have the following dependencies installed:
- Python 3.7+
- ChromaDB
- OpenAI
- python-dotenv
- graphviz (optional, for visualization)
## Quick Start
Here's a simple example to get you started with the AI Agent State Library. This example shows how to create a state machine and specify the OpenAI model to be used:
```python
import uuid
from ai_agent_state import State, StateData, StateMachine, Transition
# Define states
states = [
State(
id=str(uuid.uuid4()),
name='initialize',
data=StateData(data={'message': 'Initializing AI agent...'})
),
State(
id=str(uuid.uuid4()),
name='process',
data=StateData(data={'message': 'Processing task...'})
),
State(
id=str(uuid.uuid4()),
name='idle',
data=StateData(data={'message': 'Waiting for next task...'})
),
]
# Create the state machine and specify the model name
state_machine = StateMachine(
name='SimpleAIAgent',
initial_state=states[0],
model_name='gpt-3.5-turbo' # Replace with your desired model
)
# Add states to the state machine
for state in states:
state_machine.add_state(state)
# Add transitions
state_machine.add_transition(Transition(from_state='initialize', to_state='process'))
state_machine.add_transition(Transition(from_state='process', to_state='idle'))
state_machine.add_transition(Transition(from_state='idle', to_state='process'))
# Use the state machine
state_machine.trigger_transition("Start processing")
print(f"Current State: {state_machine.current_state.name}")
state_machine.trigger_transition("Finish processing")
print(f"Current State: {state_machine.current_state.name}")
# Save the state machine (optional)
from ai_agent_state import ChromaStateManager
chroma_manager = ChromaStateManager(persist_directory="chroma_db")
chroma_manager.save_state_machine(state_machine)
```
## Documentation
For detailed documentation on classes and methods, please refer to the [full documentation](link-to-your-documentation).
## Advanced Usage
The AI Agent State Library supports advanced features such as:
- Custom transition conditions and actions
- State transition guards for controlled state changes
- Integration with language models for dynamic decision-making
- Searching for similar states using vector embeddings
- Visualizing complex state machines
For examples of advanced usage, check out the [examples directory](/examples) in the repository.
## Example Use Case
Here's an example of how to use this library to create an AI agent that manages customer support interactions. This example includes passing in the model during the state machine creation:
```python
import os
import uuid
from dotenv import load_dotenv
from ai_agent_state import State, StateData, StateMachine, Transition
# Load API key from environment variables (ensure you have set OPENAI_API_KEY)
load_dotenv()
# Define states
welcome_state = State(
id=str(uuid.uuid4()),
name='Welcome',
data=StateData(data={'message': 'Welcome to E-Shop! How can I assist you today?'})
)
main_menu_state = State(
id=str(uuid.uuid4()),
name='MainMenu',
data=StateData(data={'message': 'Please choose an option: Order Tracking, Returns and Refunds, Product Inquiry, Account Management, or type "exit" to quit.'})
)
order_tracking_state = State(
id=str(uuid.uuid4()),
name='OrderTracking',
data=StateData(data={'task': 'Assisting with order tracking...'})
)
collect_order_number_state = State(
id=str(uuid.uuid4()),
name='CollectOrderNumber',
data=StateData(data={'message': 'Please provide your order number.'})
)
provide_order_status_state = State(
id=str(uuid.uuid4()),
name='ProvideOrderStatus',
data=StateData(data={'task': 'Providing order status...'})
)
returns_refunds_state = State(
id=str(uuid.uuid4()),
name='ReturnsAndRefunds',
data=StateData(data={'task': 'Assisting with returns and refunds...'})
)
product_inquiry_state = State(
id=str(uuid.uuid4()),
name='ProductInquiry',
data=StateData(data={'task': 'Answering product inquiries...'})
)
account_management_state = State(
id=str(uuid.uuid4()),
name='AccountManagement',
data=StateData(data={'task': 'Assisting with account management...'})
)
goodbye_state = State(
id=str(uuid.uuid4()),
name='Goodbye',
data=StateData(data={'message': 'Thank you for visiting E-Shop! Have a great day!'})
)
# Create the state machine with a specified model
state_machine = StateMachine(
name='CustomerSupportAssistant',
initial_state=welcome_state,
model_name='gpt-3.5-turbo' # Replace with your desired model
)
# Add states to the state machine
state_machine.add_state(main_menu_state)
state_machine.add_state(order_tracking_state)
state_machine.add_state(collect_order_number_state)
state_machine.add_state(provide_order_status_state)
state_machine.add_state(returns_refunds_state)
state_machine.add_state(product_inquiry_state)
state_machine.add_state(account_management_state)
state_machine.add_state(goodbye_state)
# Define transitions with conditions
transitions = [
Transition(from_state='Welcome', to_state='MainMenu'),
Transition(from_state='MainMenu', to_state='OrderTracking', condition=is_order_tracking),
Transition(from_state='OrderTracking', to_state='CollectOrderNumber'),
Transition(from_state='CollectOrderNumber', to_state='ProvideOrderStatus', condition=has_order_number),
Transition(from_state='ProvideOrderStatus', to_state='MainMenu'),
Transition(from_state='MainMenu', to_state='ReturnsAndRefunds', condition=is_returns_and_refunds),
Transition(from_state='MainMenu', to_state='ProductInquiry', condition=is_product_inquiry),
Transition(from_state='MainMenu', to_state='AccountManagement', condition=is_account_management),
Transition(from_state='MainMenu', to_state='Goodbye', condition=is_exit_command),
Transition(from_state='ReturnsAndRefunds', to_state='MainMenu'),
Transition(from_state='ProductInquiry', to_state='MainMenu'),
Transition(from_state='AccountManagement', to_state='MainMenu'),
]
# Add transitions to the state machine
for transition in transitions:
state_machine.add_transition(transition)
# Implement action functions
def fetch_order_status(order_number: str) -> str:
# Simulate fetching order status from a database
return f"Order {order_number} is currently in transit and will be delivered in 2 days."
def handle_returns_and_refunds():
return "I've initiated the return process for you. Please check your email for further instructions."
def answer_product_inquiry():
return "The product you're interested in is available in multiple colors and sizes."
def assist_account_management():
return "Your account settings have been updated as per your request."
def main():
print(f"Current State: {state_machine.current_state.name}")
print(state_machine.current_state.data.data['message'])
while True:
user_input = input("You: ")
if not user_input.strip():
continue # Skip empty input
# Before triggering transition, print current state
print(f"\n[Before Transition] Current State: {state_machine.current_state.name}")
# Exit the loop if the user wants to quit
if is_exit_command(user_input, state_machine):
state_machine.current_state = goodbye_state
print(state_machine.current_state.data.data['message'])
break
state_machine.trigger_transition(user_input)
# After triggering transition, print new state
print(f"[After Transition] Current State: {state_machine.current_state.name}")
# Update state history
state_machine.state_history.append(state_machine.current_state.name)
print(f"State History: {' -> '.join(state_machine.state_history)}")
# After the transition, print the assistant's response
if state_machine.conversation_history:
last_turn = state_machine.conversation_history[-1]
assistant_response = last_turn.get('assistant_response', '')
if assistant_response:
print(f"Assistant: {assistant_response}")
# Perform any actions associated with the current state
if state_machine.current_state.name == 'ProvideOrderStatus':
# Assume we stored the order_number in metadata
order_number = "123456" # Replace with actual order number logic
status_message = fetch_order_status(order_number)
print(f"Action: {status_message}")
elif state_machine.current_state.name == 'ReturnsAndRefunds':
result_message = handle_returns_and_refunds()
print(f"Action: {result_message}")
elif state_machine.current_state.name == 'ProductInquiry':
result_message = answer_product_inquiry()
print(f"Action: {result_message}")
elif state_machine.current_state.name == 'AccountManagement':
result_message = assist_account_management()
print(f"Action: {result_message}")
elif state_machine.current_state.name == 'Goodbye':
print(state_machine.current_state.data.data['message'])
break
# Optionally, after exiting, print the final state history
print("\nFinal State History:")
print(" -> ".join(state_machine.state_history))
# Run the main function
if __name__ == '__main__':
main()
```
**Explanation of the Example:**
- **State Definitions:**
- We define several states representing different stages of the customer support interaction, such as `Welcome`, `MainMenu`, `OrderTracking`, `ProvideOrderStatus`, etc.
- **State Machine Initialization:**
- We create a `StateMachine` instance, specifying the initial state and the OpenAI model to use.
- **Adding States and Transitions:**
- All states and transitions are added to the state machine. Transitions define how the state machine moves from one state to another based on the conversation flow.
- **Action Functions:**
- Functions like `fetch_order_status`, `handle_returns_and_refunds`, etc., simulate backend operations that would occur in a real-world scenario.
- **Main Conversation Loop:**
- The `main` function runs an interactive loop where the user can input messages, and the assistant responds accordingly.
- The assistant uses the OpenAI model specified to process messages and determine state transitions.
- **State Management:**
- The state machine keeps track of the current state and moves to the next state based on user input and OpenAI's decision-making.
- Actions associated with each state are performed when the state is active.
**Sample Interaction:**
```plaintext
Current State: Welcome
Welcome to E-Shop! How can I assist you today?
You: I'd like to track my order.
[Before Transition] Current State: Welcome
Assistant Response: Sure, I can help you with order tracking. Please provide your order number.
[After Transition] Current State: CollectOrderNumber
State History: Welcome -> CollectOrderNumber
You: My order number is 123456.
[Before Transition] Current State: CollectOrderNumber
Assistant Response: Thank you! Retrieving the status of your order now.
[After Transition] Current State: ProvideOrderStatus
State History: Welcome -> CollectOrderNumber -> ProvideOrderStatus
Action: Order 123456 is currently in transit and will be delivered in 2 days.
You: Great, thanks!
[Before Transition] Current State: ProvideOrderStatus
Assistant Response: You're welcome! Is there anything else I can assist you with?
[After Transition] Current State: MainMenu
State History: Welcome -> CollectOrderNumber -> ProvideOrderStatus -> MainMenu
You: No, that's all.
[Before Transition] Current State: MainMenu
Assistant Response: Thank you for visiting E-Shop! Have a great day!
[After Transition] Current State: Goodbye
State History: Welcome -> CollectOrderNumber -> ProvideOrderStatus -> MainMenu -> Goodbye
Final State History:
Welcome -> CollectOrderNumber -> ProvideOrderStatus -> MainMenu -> Goodbye
```
**Note:**
- In a real implementation, the assistant's responses and state transitions are determined by the OpenAI model based on your inputs.
- Ensure that you have set the `OPENAI_API_KEY` in your environment variables or appropriately in your code.
- Replace `'gpt-3.5-turbo'` with your desired OpenAI model.
- The action functions simulate backend processes and should be replaced with actual logic in a production environment.
## Contributing
We welcome contributions to the AI Agent State Library! Please read our [contributing guidelines](link-to-contributing-guidelines) for more information on how to get started.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Classes
### StateData
Represents the data and metadata associated with a state.
#### Methods:
- `to_dict()`: Converts the StateData to a dictionary.
- `from_dict(data)`: Creates a StateData object from a dictionary.
- `update_metadata(llm_response, **kwargs)`: Updates the metadata with new information.
### State
Represents a single state in the state machine.
#### Attributes:
- `id`: Unique identifier for the state.
- `name`: Name of the state.
- `data`: StateData object containing the state's data and metadata.
#### Methods:
- `to_dict()`: Converts the State to a dictionary.
- `from_dict(data)`: Creates a State object from a dictionary.
### Transition
Represents a transition between states.
#### Attributes:
- `from_state`: Name of the source state.
- `to_state`: Name of the destination state.
- `condition`: Optional function to determine if the transition should occur.
- `action`: Optional function to execute during the transition.
### StateMachine
Manages the states and transitions of an AI agent.
#### Methods:
- `add_state(state)`: Adds a new state to the machine.
- `add_transition(transition)`: Adds a new transition to the machine.
- `trigger_transition(user_input)`: Processes user input and determines the next state.
- `move_to_previous_state()`: Moves the state machine to the previous state.
- `visualize(filename)`: Generates a visual representation of the state machine.
### ChromaStateManager
Manages the persistence and retrieval of state machines using ChromaDB.
#### Methods:
- `save_state_machine(state_machine)`: Saves a state machine to the database.
- `load_state_machine(state_machine_id)`: Loads a state machine from the database.
- `search_similar_states(query, top_k)`: Searches for similar states based on a query.
**Note:**
- In a real implementation, the assistant's responses and state transitions are determined by the OpenAI model based on your inputs.
- Ensure that you have set the `OPENAI_API_KEY` in your environment variables or appropriately in your code.
- Replace `'gpt-3.5-turbo'` with your desired OpenAI model.
- The action functions simulate backend processes and should be replaced with actual logic in a production environment.
Raw data
{
"_id": null,
"home_page": "https://github.com/AlgorithmicResearchGroup/Agent-States",
"name": "ai-agent-state",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": null,
"author": "Algorithmic Research Group",
"author_email": "matt@algorithmicresearchgroup.com",
"download_url": "https://files.pythonhosted.org/packages/98/f0/366e8643f75aaf1df54abe189b0ba498f1a24be2ed643091c23e20cc0d9e/ai_agent_state-0.1.15.tar.gz",
"platform": null,
"description": "# AI Agent State Library\n\n\n## What is it?\n\nThe AI Agent State Library is a library designed to manage the state and decision-making processes of AI agents. At its core, it implements the concept of finite state machines, a computational model used to design systems with a finite number of states and transitions between those states.\n\nKey features of the library include:\n\n1. **State Machine Creation**: It allows developers to define and create intricate state machines that model the behavior of AI agents.\n\n2. **Flexible State Definition**: States can be customized with associated data and metadata, allowing for rich context within each state.\n\n3. **Dynamic Transitions**: The library supports the creation of transitions between states, which can be conditional and trigger specific actions.\n\n4. **State Transition Guards**: Implement conditions that must be met for transitions to occur, providing more control over state changes.\n\n5. **Persistence**: Integration with ChromaDB enables efficient storage and retrieval of state machines, allowing for continuity across sessions or distributed systems.\n\n6. **Visualization**: The library includes tools to visualize state machines, aiding in debugging and understanding complex agent behaviors.\n\n7. **OpenAI Integration**: It leverages the OpenAI API for dynamic decision-making, allowing for more intelligent and adaptive state transitions.\n\n## When is it useful?\n\nThe AI Agent State Library proves particularly valuable in scenarios such as:\n\n- **Conversational AI**: Managing the flow and context of conversations, ensuring coherent and contextually appropriate responses.\n\n- **Business Process Automation**: Modeling and executing complex workflows that involve decision points and varied paths based on different conditions.\n\n- **Multi-Agent Systems**: Coordinating the behavior and interactions of multiple AI agents in a complex environment.\n\nThe library's flexibility and extensibility make it adaptable to a wide range of AI applications where managing complex state and behavior is crucial. Its integration with modern tools like ChromaDB for persistence and OpenAI for decision-making enhances its utility in creating sophisticated, adaptive AI systems.\n\nBy providing a structured way to design, implement, and manage AI agent behavior, the AI Agent State Library helps developers create more reliable, understandable, and maintainable AI systems, reducing the complexity often associated with developing intelligent agents.\n\n## Features\n\n- Create and manage complex state machines for AI agents\n- Define custom states with associated data and metadata\n- Create transitions between states with optional conditions and actions\n- Implement state transition guards for controlled state changes\n- Persist and retrieve state machines using ChromaDB\n- Visualize state machines for easy understanding and debugging\n- Integration with OpenAI's API for dynamic decision-making\n\n## Installation\n\nTo install the AI Agent State Library, use pip:\n\n```bash\npip install ai-agent-state\n```\n\nMake sure you have the following dependencies installed:\n\n- Python 3.7+\n- ChromaDB\n- OpenAI\n- python-dotenv\n- graphviz (optional, for visualization)\n\n## Quick Start\n\nHere's a simple example to get you started with the AI Agent State Library. This example shows how to create a state machine and specify the OpenAI model to be used:\n\n```python\nimport uuid\nfrom ai_agent_state import State, StateData, StateMachine, Transition\n\n# Define states\nstates = [\n State(\n id=str(uuid.uuid4()),\n name='initialize',\n data=StateData(data={'message': 'Initializing AI agent...'})\n ),\n State(\n id=str(uuid.uuid4()),\n name='process',\n data=StateData(data={'message': 'Processing task...'})\n ),\n State(\n id=str(uuid.uuid4()),\n name='idle',\n data=StateData(data={'message': 'Waiting for next task...'})\n ),\n]\n\n# Create the state machine and specify the model name\nstate_machine = StateMachine(\n name='SimpleAIAgent',\n initial_state=states[0],\n model_name='gpt-3.5-turbo' # Replace with your desired model\n)\n\n# Add states to the state machine\nfor state in states:\n state_machine.add_state(state)\n\n# Add transitions\nstate_machine.add_transition(Transition(from_state='initialize', to_state='process'))\nstate_machine.add_transition(Transition(from_state='process', to_state='idle'))\nstate_machine.add_transition(Transition(from_state='idle', to_state='process'))\n\n# Use the state machine\nstate_machine.trigger_transition(\"Start processing\")\nprint(f\"Current State: {state_machine.current_state.name}\")\nstate_machine.trigger_transition(\"Finish processing\")\nprint(f\"Current State: {state_machine.current_state.name}\")\n\n# Save the state machine (optional)\nfrom ai_agent_state import ChromaStateManager\nchroma_manager = ChromaStateManager(persist_directory=\"chroma_db\")\nchroma_manager.save_state_machine(state_machine)\n```\n\n## Documentation\n\nFor detailed documentation on classes and methods, please refer to the [full documentation](link-to-your-documentation).\n\n## Advanced Usage\n\nThe AI Agent State Library supports advanced features such as:\n\n- Custom transition conditions and actions\n- State transition guards for controlled state changes\n- Integration with language models for dynamic decision-making\n- Searching for similar states using vector embeddings\n- Visualizing complex state machines\n\nFor examples of advanced usage, check out the [examples directory](/examples) in the repository.\n\n## Example Use Case\n\nHere's an example of how to use this library to create an AI agent that manages customer support interactions. This example includes passing in the model during the state machine creation:\n\n```python\nimport os\nimport uuid\nfrom dotenv import load_dotenv\nfrom ai_agent_state import State, StateData, StateMachine, Transition\n\n# Load API key from environment variables (ensure you have set OPENAI_API_KEY)\nload_dotenv()\n\n# Define states\nwelcome_state = State(\n id=str(uuid.uuid4()),\n name='Welcome',\n data=StateData(data={'message': 'Welcome to E-Shop! How can I assist you today?'})\n)\n\nmain_menu_state = State(\n id=str(uuid.uuid4()),\n name='MainMenu',\n data=StateData(data={'message': 'Please choose an option: Order Tracking, Returns and Refunds, Product Inquiry, Account Management, or type \"exit\" to quit.'})\n)\n\norder_tracking_state = State(\n id=str(uuid.uuid4()),\n name='OrderTracking',\n data=StateData(data={'task': 'Assisting with order tracking...'})\n)\n\ncollect_order_number_state = State(\n id=str(uuid.uuid4()),\n name='CollectOrderNumber',\n data=StateData(data={'message': 'Please provide your order number.'})\n)\n\nprovide_order_status_state = State(\n id=str(uuid.uuid4()),\n name='ProvideOrderStatus',\n data=StateData(data={'task': 'Providing order status...'})\n)\n\nreturns_refunds_state = State(\n id=str(uuid.uuid4()),\n name='ReturnsAndRefunds',\n data=StateData(data={'task': 'Assisting with returns and refunds...'})\n)\n\nproduct_inquiry_state = State(\n id=str(uuid.uuid4()),\n name='ProductInquiry',\n data=StateData(data={'task': 'Answering product inquiries...'})\n)\n\naccount_management_state = State(\n id=str(uuid.uuid4()),\n name='AccountManagement',\n data=StateData(data={'task': 'Assisting with account management...'})\n)\n\ngoodbye_state = State(\n id=str(uuid.uuid4()),\n name='Goodbye',\n data=StateData(data={'message': 'Thank you for visiting E-Shop! Have a great day!'})\n)\n\n# Create the state machine with a specified model\nstate_machine = StateMachine(\n name='CustomerSupportAssistant',\n initial_state=welcome_state,\n model_name='gpt-3.5-turbo' # Replace with your desired model\n)\n\n# Add states to the state machine\nstate_machine.add_state(main_menu_state)\nstate_machine.add_state(order_tracking_state)\nstate_machine.add_state(collect_order_number_state)\nstate_machine.add_state(provide_order_status_state)\nstate_machine.add_state(returns_refunds_state)\nstate_machine.add_state(product_inquiry_state)\nstate_machine.add_state(account_management_state)\nstate_machine.add_state(goodbye_state)\n\n# Define transitions with conditions\ntransitions = [\n Transition(from_state='Welcome', to_state='MainMenu'),\n Transition(from_state='MainMenu', to_state='OrderTracking', condition=is_order_tracking),\n Transition(from_state='OrderTracking', to_state='CollectOrderNumber'),\n Transition(from_state='CollectOrderNumber', to_state='ProvideOrderStatus', condition=has_order_number),\n Transition(from_state='ProvideOrderStatus', to_state='MainMenu'),\n Transition(from_state='MainMenu', to_state='ReturnsAndRefunds', condition=is_returns_and_refunds),\n Transition(from_state='MainMenu', to_state='ProductInquiry', condition=is_product_inquiry),\n Transition(from_state='MainMenu', to_state='AccountManagement', condition=is_account_management),\n Transition(from_state='MainMenu', to_state='Goodbye', condition=is_exit_command),\n Transition(from_state='ReturnsAndRefunds', to_state='MainMenu'),\n Transition(from_state='ProductInquiry', to_state='MainMenu'),\n Transition(from_state='AccountManagement', to_state='MainMenu'),\n]\n\n# Add transitions to the state machine\nfor transition in transitions:\n state_machine.add_transition(transition)\n\n# Implement action functions\ndef fetch_order_status(order_number: str) -> str:\n # Simulate fetching order status from a database\n return f\"Order {order_number} is currently in transit and will be delivered in 2 days.\"\n\ndef handle_returns_and_refunds():\n return \"I've initiated the return process for you. Please check your email for further instructions.\"\n\ndef answer_product_inquiry():\n return \"The product you're interested in is available in multiple colors and sizes.\"\n\ndef assist_account_management():\n return \"Your account settings have been updated as per your request.\"\n\ndef main():\n print(f\"Current State: {state_machine.current_state.name}\")\n print(state_machine.current_state.data.data['message'])\n\n while True:\n user_input = input(\"You: \")\n\n if not user_input.strip():\n continue # Skip empty input\n\n # Before triggering transition, print current state\n print(f\"\\n[Before Transition] Current State: {state_machine.current_state.name}\")\n\n # Exit the loop if the user wants to quit\n if is_exit_command(user_input, state_machine):\n state_machine.current_state = goodbye_state\n print(state_machine.current_state.data.data['message'])\n break\n\n state_machine.trigger_transition(user_input)\n\n # After triggering transition, print new state\n print(f\"[After Transition] Current State: {state_machine.current_state.name}\")\n\n # Update state history\n state_machine.state_history.append(state_machine.current_state.name)\n print(f\"State History: {' -> '.join(state_machine.state_history)}\")\n\n # After the transition, print the assistant's response\n if state_machine.conversation_history:\n last_turn = state_machine.conversation_history[-1]\n assistant_response = last_turn.get('assistant_response', '')\n if assistant_response:\n print(f\"Assistant: {assistant_response}\")\n\n # Perform any actions associated with the current state\n if state_machine.current_state.name == 'ProvideOrderStatus':\n # Assume we stored the order_number in metadata\n order_number = \"123456\" # Replace with actual order number logic\n status_message = fetch_order_status(order_number)\n print(f\"Action: {status_message}\")\n elif state_machine.current_state.name == 'ReturnsAndRefunds':\n result_message = handle_returns_and_refunds()\n print(f\"Action: {result_message}\")\n elif state_machine.current_state.name == 'ProductInquiry':\n result_message = answer_product_inquiry()\n print(f\"Action: {result_message}\")\n elif state_machine.current_state.name == 'AccountManagement':\n result_message = assist_account_management()\n print(f\"Action: {result_message}\")\n elif state_machine.current_state.name == 'Goodbye':\n print(state_machine.current_state.data.data['message'])\n break\n\n # Optionally, after exiting, print the final state history\n print(\"\\nFinal State History:\")\n print(\" -> \".join(state_machine.state_history))\n\n# Run the main function\nif __name__ == '__main__':\n main()\n```\n\n**Explanation of the Example:**\n\n- **State Definitions:**\n - We define several states representing different stages of the customer support interaction, such as `Welcome`, `MainMenu`, `OrderTracking`, `ProvideOrderStatus`, etc.\n\n- **State Machine Initialization:**\n - We create a `StateMachine` instance, specifying the initial state and the OpenAI model to use.\n\n- **Adding States and Transitions:**\n - All states and transitions are added to the state machine. Transitions define how the state machine moves from one state to another based on the conversation flow.\n\n- **Action Functions:**\n - Functions like `fetch_order_status`, `handle_returns_and_refunds`, etc., simulate backend operations that would occur in a real-world scenario.\n\n- **Main Conversation Loop:**\n - The `main` function runs an interactive loop where the user can input messages, and the assistant responds accordingly.\n - The assistant uses the OpenAI model specified to process messages and determine state transitions.\n\n- **State Management:**\n - The state machine keeps track of the current state and moves to the next state based on user input and OpenAI's decision-making.\n - Actions associated with each state are performed when the state is active.\n\n**Sample Interaction:**\n\n```plaintext\nCurrent State: Welcome\nWelcome to E-Shop! How can I assist you today?\nYou: I'd like to track my order.\n\n[Before Transition] Current State: Welcome\nAssistant Response: Sure, I can help you with order tracking. Please provide your order number.\n[After Transition] Current State: CollectOrderNumber\nState History: Welcome -> CollectOrderNumber\nYou: My order number is 123456.\n\n[Before Transition] Current State: CollectOrderNumber\nAssistant Response: Thank you! Retrieving the status of your order now.\n[After Transition] Current State: ProvideOrderStatus\nState History: Welcome -> CollectOrderNumber -> ProvideOrderStatus\nAction: Order 123456 is currently in transit and will be delivered in 2 days.\nYou: Great, thanks!\n\n[Before Transition] Current State: ProvideOrderStatus\nAssistant Response: You're welcome! Is there anything else I can assist you with?\n[After Transition] Current State: MainMenu\nState History: Welcome -> CollectOrderNumber -> ProvideOrderStatus -> MainMenu\nYou: No, that's all.\n\n[Before Transition] Current State: MainMenu\nAssistant Response: Thank you for visiting E-Shop! Have a great day!\n[After Transition] Current State: Goodbye\nState History: Welcome -> CollectOrderNumber -> ProvideOrderStatus -> MainMenu -> Goodbye\n\nFinal State History:\nWelcome -> CollectOrderNumber -> ProvideOrderStatus -> MainMenu -> Goodbye\n```\n\n**Note:**\n\n- In a real implementation, the assistant's responses and state transitions are determined by the OpenAI model based on your inputs.\n- Ensure that you have set the `OPENAI_API_KEY` in your environment variables or appropriately in your code.\n- Replace `'gpt-3.5-turbo'` with your desired OpenAI model.\n- The action functions simulate backend processes and should be replaced with actual logic in a production environment.\n\n## Contributing\n\nWe welcome contributions to the AI Agent State Library! Please read our [contributing guidelines](link-to-contributing-guidelines) for more information on how to get started.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n\n\n## Classes\n\n### StateData\nRepresents the data and metadata associated with a state.\n\n#### Methods:\n- `to_dict()`: Converts the StateData to a dictionary.\n- `from_dict(data)`: Creates a StateData object from a dictionary.\n- `update_metadata(llm_response, **kwargs)`: Updates the metadata with new information.\n\n### State\nRepresents a single state in the state machine.\n\n#### Attributes:\n- `id`: Unique identifier for the state.\n- `name`: Name of the state.\n- `data`: StateData object containing the state's data and metadata.\n\n#### Methods:\n- `to_dict()`: Converts the State to a dictionary.\n- `from_dict(data)`: Creates a State object from a dictionary.\n\n### Transition\nRepresents a transition between states.\n\n#### Attributes:\n- `from_state`: Name of the source state.\n- `to_state`: Name of the destination state.\n- `condition`: Optional function to determine if the transition should occur.\n- `action`: Optional function to execute during the transition.\n\n### StateMachine\nManages the states and transitions of an AI agent.\n\n#### Methods:\n- `add_state(state)`: Adds a new state to the machine.\n- `add_transition(transition)`: Adds a new transition to the machine.\n- `trigger_transition(user_input)`: Processes user input and determines the next state.\n- `move_to_previous_state()`: Moves the state machine to the previous state.\n- `visualize(filename)`: Generates a visual representation of the state machine.\n\n### ChromaStateManager\nManages the persistence and retrieval of state machines using ChromaDB.\n\n#### Methods:\n- `save_state_machine(state_machine)`: Saves a state machine to the database.\n- `load_state_machine(state_machine_id)`: Loads a state machine from the database.\n- `search_similar_states(query, top_k)`: Searches for similar states based on a query.\n\n\n**Note:**\n\n- In a real implementation, the assistant's responses and state transitions are determined by the OpenAI model based on your inputs.\n- Ensure that you have set the `OPENAI_API_KEY` in your environment variables or appropriately in your code.\n- Replace `'gpt-3.5-turbo'` with your desired OpenAI model.\n- The action functions simulate backend processes and should be replaced with actual logic in a production environment.\n",
"bugtrack_url": null,
"license": null,
"summary": "A library for managing state machines in AI agents",
"version": "0.1.15",
"project_urls": {
"Homepage": "https://github.com/AlgorithmicResearchGroup/Agent-States"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "efc73208608e38d8f8f0e32eb1c05f8ba7484487412146dae3c82b9a4760434e",
"md5": "334118708c9c17217beab066f70e7cdb",
"sha256": "3f9cd77abdf021edb26ba622dce51b24c5c2318d186861c8f2abb0d96202637a"
},
"downloads": -1,
"filename": "ai_agent_state-0.1.15-py3-none-any.whl",
"has_sig": false,
"md5_digest": "334118708c9c17217beab066f70e7cdb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 13225,
"upload_time": "2024-11-23T00:27:17",
"upload_time_iso_8601": "2024-11-23T00:27:17.995198Z",
"url": "https://files.pythonhosted.org/packages/ef/c7/3208608e38d8f8f0e32eb1c05f8ba7484487412146dae3c82b9a4760434e/ai_agent_state-0.1.15-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "98f0366e8643f75aaf1df54abe189b0ba498f1a24be2ed643091c23e20cc0d9e",
"md5": "287bc4957caa3b97c6a1592ccf86c9a4",
"sha256": "d75f1b7a94657cec3f13f4e08188ae3a3112e7e2445f38191cfdb36d3a511af9"
},
"downloads": -1,
"filename": "ai_agent_state-0.1.15.tar.gz",
"has_sig": false,
"md5_digest": "287bc4957caa3b97c6a1592ccf86c9a4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 18124,
"upload_time": "2024-11-23T00:27:19",
"upload_time_iso_8601": "2024-11-23T00:27:19.534893Z",
"url": "https://files.pythonhosted.org/packages/98/f0/366e8643f75aaf1df54abe189b0ba498f1a24be2ed643091c23e20cc0d9e/ai_agent_state-0.1.15.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-23 00:27:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AlgorithmicResearchGroup",
"github_project": "Agent-States",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "ai-agent-state"
}
JSON
