# agentevents
Colorful, searchable event logs for your agent.
# Why Use This?
This package simplifies some things you might want to do in your agentic applications.
1. Create a sequential log of events that occur in your agent which can be searched and filtered.
2. Log all events into a file.
3. Track all events by epoch to associate events with particular runs.
# Installation
```bash
pip install agentevents
```
# Quickstart
```python
from event_manager import create_event, get_events, search_events
# Create an event
create_event('My Event Content', type='info', subtype='subtype', creator='John', metadata={'extra':'data'})
# Get all info type events
info_events = get_events(type='info')
# Search events
search_results = search_events('My Event Content')
# events are saved to logs/events.txt by default
```
# Concepts
### Vector Search
This package is backed by a vector search engine. All events are searchable by their "document" data.
### Epochs
If you are running a looping or pipeline application, you can track the epoch of the event. This is useful for associating events with particular runs of your application. For a looping application, you can increment the epoch every time the loop runs. For a pipeline application, you can increment the epoch every time the pipeline runs.
### Event Types and Subtypes
You can assign types to events so you can filter and display them.
### Event Colors
You can assign colors to event types, which will be used in the display, by creating a dictionary of event types and colors and passing it to the `create_event` function.
A set of default colors is provided:
```python
{
"unknown": "white",
"error": "red",
"warning": "yellow",
"info": "blue",
"success": "green",
"debug": "magenta",
"critical": "red",
"start": "green",
"stop": "red",
"pause": "yellow",
"resume": "green",
"epoch": "blue",
}
```
You can override these colors by passing a dictionary of event types and colors to the `create_event` function.
# Documentation
### `create_event(content, type=None, subtype=None, creator=None, metadata={}, type_colors={}, panel=True)`
Create an event with provided metadata and saves it to the event log file.
**Parameters:**
- `content` (str): Content of the event.
- `type` (str, optional): Type of the event. Defaults to None.
- `subtype` (str, optional): Subtype of the event. Defaults to None.
- `creator` (str, optional): Creator of the event. Defaults to None.
- `metadata` (dict, optional): Additional metadata for the event. Defaults to an empty dictionary.
- `type_colors` (dict, optional): Dictionary with event types as keys and colors as values. Defaults to an empty dictionary.
- `panel` (bool, optional): Determines if the output should be within a Panel. Defaults to True.
**Returns:**
None.
### `get_events(type=None, n_results=None, filter_metadata=None)`
Retrieve the last n events.
**Parameters:**
- `type` (str, optional): The type of events to retrieve. Defaults to None.
- `n_results` (int, optional): The number of results to return. Defaults to None.
- `filter_metadata` (dict, optional): Filter by metadata keys. Defaults to None.
**Returns:**
List of event documents.
### `search_events(search_text, n_results=None)`
Ssearch for events that match the search text.
**Parameters:**
- `search_text` (str): The text to search for.
- `n_results` (int, optional): The number of results to return. Defaults to None.
**Returns:**
List of event documents that match the search criteria.
### `write_to_log(content, write_to_debug=False, filename="logs/events.txt")`
This function writes content to the event log file.
**Parameters:**
- `content` (str): String to be written in the log file.
- `write_to_debug` (bool, optional): Whether the content is written to debug file or not. Defaults to False.
- `filename` (str, optional): Name of the file where the content is written. Defaults to "logs/events.txt".
**Returns:**
None.
# Contributions Welcome
If you like this library and want to contribute in any way, please feel free to submit a PR and I will review it. Please note that the goal here is simplicity and accesibility, using common language and few dependencies.
Raw data
{
"_id": null,
"home_page": "https://github.com/AutonomousResearchGroup/agentevents",
"name": "agentevents",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Moon",
"author_email": "shawmakesmagic@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/f0/94/83c338b2917c2d224c39dcf95220524d7a50d5cb7b3c716363533e105de9/agentevents-0.1.3.tar.gz",
"platform": null,
"description": "# agentevents\n\nColorful, searchable event logs for your agent.\n\n\n# Why Use This?\n\nThis package simplifies some things you might want to do in your agentic applications.\n\n1. Create a sequential log of events that occur in your agent which can be searched and filtered.\n2. Log all events into a file.\n3. Track all events by epoch to associate events with particular runs.\n\n# Installation\n\n```bash\npip install agentevents\n```\n\n# Quickstart\n\n```python\nfrom event_manager import create_event, get_events, search_events\n\n# Create an event\ncreate_event('My Event Content', type='info', subtype='subtype', creator='John', metadata={'extra':'data'})\n\n# Get all info type events\ninfo_events = get_events(type='info')\n\n# Search events\nsearch_results = search_events('My Event Content')\n\n# events are saved to logs/events.txt by default\n```\n\n# Concepts\n\n### Vector Search\n\nThis package is backed by a vector search engine. All events are searchable by their \"document\" data.\n\n### Epochs\n\nIf you are running a looping or pipeline application, you can track the epoch of the event. This is useful for associating events with particular runs of your application. For a looping application, you can increment the epoch every time the loop runs. For a pipeline application, you can increment the epoch every time the pipeline runs.\n\n### Event Types and Subtypes\n\nYou can assign types to events so you can filter and display them.\n\n### Event Colors\n\nYou can assign colors to event types, which will be used in the display, by creating a dictionary of event types and colors and passing it to the `create_event` function.\n\nA set of default colors is provided:\n\n```python\n{\n \"unknown\": \"white\",\n \"error\": \"red\",\n \"warning\": \"yellow\",\n \"info\": \"blue\",\n \"success\": \"green\",\n \"debug\": \"magenta\",\n \"critical\": \"red\",\n \"start\": \"green\",\n \"stop\": \"red\",\n \"pause\": \"yellow\",\n \"resume\": \"green\",\n \"epoch\": \"blue\",\n}\n```\n\nYou can override these colors by passing a dictionary of event types and colors to the `create_event` function.\n\n# Documentation\n\n### `create_event(content, type=None, subtype=None, creator=None, metadata={}, type_colors={}, panel=True)`\n\nCreate an event with provided metadata and saves it to the event log file.\n\n**Parameters:**\n\n- `content` (str): Content of the event.\n- `type` (str, optional): Type of the event. Defaults to None.\n- `subtype` (str, optional): Subtype of the event. Defaults to None.\n- `creator` (str, optional): Creator of the event. Defaults to None.\n- `metadata` (dict, optional): Additional metadata for the event. Defaults to an empty dictionary.\n- `type_colors` (dict, optional): Dictionary with event types as keys and colors as values. Defaults to an empty dictionary.\n- `panel` (bool, optional): Determines if the output should be within a Panel. Defaults to True.\n\n**Returns:**\n\nNone.\n\n### `get_events(type=None, n_results=None, filter_metadata=None)`\n\nRetrieve the last n events.\n\n**Parameters:**\n\n- `type` (str, optional): The type of events to retrieve. Defaults to None.\n- `n_results` (int, optional): The number of results to return. Defaults to None.\n- `filter_metadata` (dict, optional): Filter by metadata keys. Defaults to None.\n\n**Returns:**\n\nList of event documents.\n\n### `search_events(search_text, n_results=None)`\n\nSsearch for events that match the search text.\n\n**Parameters:**\n\n- `search_text` (str): The text to search for.\n- `n_results` (int, optional): The number of results to return. Defaults to None.\n\n**Returns:**\n\nList of event documents that match the search criteria.\n\n### `write_to_log(content, write_to_debug=False, filename=\"logs/events.txt\")`\n\nThis function writes content to the event log file.\n\n**Parameters:**\n\n- `content` (str): String to be written in the log file.\n- `write_to_debug` (bool, optional): Whether the content is written to debug file or not. Defaults to False.\n- `filename` (str, optional): Name of the file where the content is written. Defaults to \"logs/events.txt\".\n\n**Returns:**\n\nNone.\n\n# Contributions Welcome\n\nIf you like this library and want to contribute in any way, please feel free to submit a PR and I will review it. Please note that the goal here is simplicity and accesibility, using common language and few dependencies.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Searchable events with colorful log output for agents.",
"version": "0.1.3",
"project_urls": {
"Homepage": "https://github.com/AutonomousResearchGroup/agentevents"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d3c0ee868d3e6396e221821d7ba0e142dffd7845eb90ff55ecdba34c8da744ba",
"md5": "f284a8c63ca135a0844487fa11ce238a",
"sha256": "4f07b0645330b44cae8fc4c9a5773397b5b200c5814c74ded6a799aed4e118d9"
},
"downloads": -1,
"filename": "agentevents-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f284a8c63ca135a0844487fa11ce238a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 5976,
"upload_time": "2023-07-16T08:39:45",
"upload_time_iso_8601": "2023-07-16T08:39:45.655423Z",
"url": "https://files.pythonhosted.org/packages/d3/c0/ee868d3e6396e221821d7ba0e142dffd7845eb90ff55ecdba34c8da744ba/agentevents-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f09483c338b2917c2d224c39dcf95220524d7a50d5cb7b3c716363533e105de9",
"md5": "ce1aca586e364a7593077b7283a220cc",
"sha256": "253c8289a7d1aca25769611a7537743125a068ff9d298dbf6fd247a52d62109d"
},
"downloads": -1,
"filename": "agentevents-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "ce1aca586e364a7593077b7283a220cc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 5388,
"upload_time": "2023-07-16T08:39:47",
"upload_time_iso_8601": "2023-07-16T08:39:47.353401Z",
"url": "https://files.pythonhosted.org/packages/f0/94/83c338b2917c2d224c39dcf95220524d7a50d5cb7b3c716363533e105de9/agentevents-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-16 08:39:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AutonomousResearchGroup",
"github_project": "agentevents",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "agentevents"
}
JSON
