v0.3.0 (#2)

* build: add dill as req
* git: ignore .DS_Store
* git: ignore .dill & .pkl
* refactor(demo): remove useless print
* refactor(demo): name the agents
* !refactor: separate actions from agent and switch pickl to dill
* refactor(demo): use new custom action system
* doc: update docstrings
* chore: bump version to 0.3.0
* test: add unit tests
* test: remove 3.11-related tests (not needed)
* chore(checkpoint): remove unused code
* fix(action): think action no longer trigger talk action
* fix(interaction): check if agent exist before storing interaction
* fix(checkpoint): check if user tryies to create a new checkpoint manager
* fix(test): resolve failing UTs
* doc: README

---------

Signed-off-by: Valentin De Matos <vltn.dematos@gmail.com>

.github/workflows/tests.yml

@@ -0,0 +1,33 @@
+name: Run Tests
+
+on:
+  pull_request:
+    branches: [ main ]
+  push:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10"]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e ".[test]"
+
+    - name: Run tests with pytest
+      env:
+        OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      run: |
+        pytest

.gitignore

@@ -174,5 +174,9 @@ cython_debug/
 *.pickle
 *.pkl
 
+*.dill
+*.pkl
+
 # VS Code
-*.code-workspace
+*.code-workspace
+.DS_Store

README.md

@@ -32,20 +32,22 @@ from agentarium import Agent
 agent1 = Agent(name="agent1")
 agent2 = Agent(name="agent2")
 
-agent1.talk_to(agent2, "Hello, how are you?")
-agent2.talk_to(agent1, "I'm fine, thank you!")
+# Direct communication between agents
+alice.talk_to(bob, "Hello Bob! I heard you're working on some interesting ML projects.")
 
-agent1.act() # Same as agent.talk_to but it's the agent who decides what to do
+# Agent autonomously decides its next action based on context
+bob.act()
 ```
 
 ## ✨ Features
 
 - **🤖 Advanced Agent Management**: Create and orchestrate multiple AI agents with different roles and capabilities
-- **🔄 Robust Interaction Management**: Coordinate complex interactions between agents
-- **💾 Checkpoint System**: Save and restore agent states and interactions
-- **📊 Data Generation**: Generate synthetic data through agent interactions
+- **🔄 Autonomous Decision Making**: Agents can make decisions and take actions based on their context
+- **💾 Checkpoint System**: Save and restore agent states and interactions for reproducibility
+- **🎭 Customizable Actions**: Define custom actions beyond the default talk/think capabilities
+- **🧠 Memory & Context**: Agents maintain memory of past interactions for contextual responses
+- **⚡ AI Integration**: Seamless integration with various AI providers through aisuite
 - **⚡ Performance Optimized**: Built for efficiency and scalability
-- **🌍 Flexible Environment Configuration**: Define custom environments with YAML configuration files
 - **🛠️ Extensible Architecture**: Easy to extend and customize for your specific needs
 
 ## 📚 Examples
@@ -54,56 +56,101 @@ agent1.act() # Same as agent.talk_to but it's the agent who decides what to do
 Create a simple chat interaction between agents:
 
 ```python
-# examples/basic_chat/demo.py
 from agentarium import Agent
 
-alice = Agent.create_agent()
-bob = Agent.create_agent()
+# Create agents with specific characteristics
+alice = Agent.create_agent(name="Alice", occupation="Software Engineer")
+bob = Agent.create_agent(name="Bob", occupation="Data Scientist")
+
+# Direct communication
+alice.talk_to(bob, "Hello Bob! I heard you're working on some interesting projects.")
 
-alice.talk_to(bob, "Hello Bob! I heard you're working on some interesting data science projects.")
+# Let Bob autonomously decide how to respond
 bob.act()
 ```
 
-### Synthetic Data Generation
-Generate synthetic data through agent interactions:
+### Adding Custom Actions
+Add new capabilities to your agents:
+
+```python
+from agentarium import Agent, Action
+
+# Define a simple greeting action
+def greet(name: str, **kwargs) -> str:
+    return f"Hello, {name}!"
+
+# Create an agent and add the greeting action
+agent = Agent.create_agent(name="Alice")
+agent.add_action(
+    Action(
+        name="GREET",
+        description="Greet someone by name",
+        parameters=["name"],
+        function=greet
+    )
+)
+
+# Use the custom action
+agent.execute_action("GREET", "Bob")
+```
+
+### Using Checkpoints
+Save and restore agent states:
 
 ```python
-# examples/synthetic_data/demo.py
 from agentarium import Agent
 from agentarium.CheckpointManager import CheckpointManager
 
+# Initialize checkpoint manager
 checkpoint = CheckpointManager("demo")
 
-alice = Agent.create_agent()
-bob = Agent.create_agent()
+# Create and interact with agents
+alice = Agent.create_agent(name="Alice")
+bob = Agent.create_agent(name="Bob")
 
 alice.talk_to(bob, "What a beautiful day!")
 checkpoint.update(step="interaction_1")
 
+# Save the current state
 checkpoint.save()
 ```
 
 More examples can be found in the [examples/](examples/) directory.
 
 ## 📖 Documentation
 
-### Environment Configuration
-Configure your environment using YAML files:
+### Agent Creation
+Create agents with custom characteristics:
+
+```python
+agent = Agent.create_agent(
+    name="Alice",
+    age=28,
+    occupation="Software Engineer",
+    location="San Francisco",
+    bio="A passionate developer who loves AI"
+)
+```
+
+### LLM Configuration
+Configure your LLM provider and credentials using a YAML file:
 
 ```yaml
 llm:
-  provider: "openai" # any provider supported by aisuite
-  model: "gpt-4o-mini" # any model supported by the provider
+  provider: "openai"  # The LLM provider to use (any provider supported by aisuite)
+  model: "gpt-4"      # The specific model to use from the provider
 
-aisuite: # optional, credentials for aisuite
-  openai:
-    api_key: "sk-..."
+aisuite:              # (optional) Credentials for aisuite
+  openai:            # Provider-specific configuration
+    api_key: "sk-..."  # Your API key
 ```
 
 ### Key Components
 
-- **Agent**: Base class for creating AI agents
-- **CheckpointManager**: Handles saving and loading of agent states
+- **Agent**: Core class for creating AI agents with personalities and autonomous behavior
+- **CheckpointManager**: Handles saving and loading of agent states and interactions
+- **Action**: Base class for defining custom agent actions
+- **AgentInteractionManager**: Manages and tracks all agent interactions
 
 ## 🤝 Contributing
 
@@ -122,11 +169,5 @@ This project is licensed under the Apache 2.0 License - see the [LICENSE](LICENS
 
 ## 🙏 Acknowledgments
 
-- Thanks to all contributors who have helped shape Agentarium
-- Special thanks to the open-source community
-
----
+Thanks to all contributors who have helped shape Agentarium 🫶
 
-<div align="center">
-Made with ❤️ by <a href="https://github.com/thytu">thytu</a>
-</div>