| Name | just-agents JSON |
| Version |
0.4.3
JSON |
| download |
| home_page | None |
| Summary | Just Agents - A lightweight, straightforward library for LLM agents that focuses on simplicity over unnecessary abstractions. |
| upload_time | 2024-12-07 23:39:17 |
| maintainer | Anton Kulaga |
| docs_url | None |
| author | Alex Karmazin |
| requires_python | <4.0,>=3.10 |
| license | MIT |
| keywords |
python
llm
agents
ai
machine-learning
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# just-agents
[](https://github.com/longevity-genie/just-agents/actions/workflows/run_tests.yaml)
[](https://badge.fury.io/py/just-agents-core)
[](https://just-agents.readthedocs.io/en/latest/?badge=latest)
A lightweight, straightforward library for LLM agents - no over-engineering, just simplicity!
## Quick Start
```bash
pip install just-agents-core
```
WARNING: we are reorganizing the package structure right now so the published package is a bit different than the code in this repository.
## ðŊ Motivation
Most of the existing agentic libraries are extremely over-engineered either directly or by using over-engineered libraries under the hood, like langchain and llamaindex.
In reality, interactions with LLMs are mostly about strings, and you can write your own template by just using f-strings and python native string templates.
There is no need in complicated chain-like classes and other abstractions, in fact popular libraries create complexity just to sell you their paid services for LLM calls monitoring because it is extremely hard to understand what exactly is sent to LLMs.
It is way easier to reason about the code if you separate your prompting from python code to a separate easily readable files (like yaml files).
We wrote this libraries while being pissed of by high complexity and wanted something controlled and simple.
Of course, you might comment that we do not have the ecosystem like, for example, tools and loaders. In reality, most of langchain tools are just very simple functions wrapped in their classes, you can always quickly look at them and write a simple function to do the same thing that just-agents will pick up easily.
## âĻ Key Features
- ðŠķ Lightweight and simple implementation
- ð Easy-to-understand agent interactions
- ð§ Customizable prompts using YAML files
- ðĪ Support for various LLM models through litellm
- ð Chain of Thought reasoning with function calls
## ð Documentation & Tutorials
### Interactive Tutorials (Google Colab)
- [Basic Agents Tutorial](https://github.com/longevity-genie/just-agents/blob/main/examples/notebooks/01_just_agents_colab.ipynb)
- [Database Agent Tutorial](https://github.com/longevity-genie/just-agents/blob/main/examples/notebooks/02_sqlite_example.ipynb)
- [Coding Agent Tutorial](https://github.com/longevity-genie/just-agents/blob/main/examples/notebooks/03_coding_agent.ipynb)
### Example Code
Browse our [examples](https://github.com/longevity-genie/just-agents/tree/main/examples) directory for:
- ð° Basic usage examples
- ðŧ Code generation and execution
- ð ïļ Tool integration examples
- ðĨ Multi-agent interactions
## ð Installation
### Quick Install
```bash
pip install just-agents-core
```
### Development Setup
1. Clone the repository:
```bash
git clone git@github.com:longevity-genie/just-agents.git
cd just-agents
```
2. Set up the environment:
We use Poetry for dependency management. First, [install Poetry](https://python-poetry.org/docs/#installation) if you haven't already.
```bash
# Install dependencies using Poetry
poetry install
# Activate the virtual environment
poetry shell
```
3. Configure API keys:
```bash
cp .env.example .env
# Edit .env with your API keys:
# OPENAI_API_KEY=your_key_here
# GROQ_API_KEY=your_key_here
```
## ðïļ Architecture
### Core Components
1. **BaseAgent**: A thin wrapper around litellm for LLM interactions
3. **ChainOfThoughtAgent**: Extended agent with reasoning capabilities
### ChatAgent
The `ChatAgent` class is the core of our library.
It represents an agent with a specific role, goal, and task. Here's a simple example of two agents talking to each other.
```python
from dotenv import load_dotenv
from just_agents.simple.chat_agent import ChatAgent
from just_agents.simple.llm_options import LLAMA3_2_VISION
load_dotenv(override=True)
customer: ChatAgent = ChatAgent(llm_options = LLAMA3_2_VISION, role = "customer at a shop",
goal = "Your goal is to order what you want, while speaking concisely and clearly",
task="Find the best headphones!")
storekeeper: ChatAgent = ChatAgent(llm_options = LLAMA3_2_VISION,
role = "helpful storekeeper",
goal="earn profit by selling what customers need",
task="sell to the customer")
exchanges: int = 3 # how many times the agents will exchange messages
customer.memory.add_on_message(lambda m: logger.info(f"Customer: {m}") if m.role == "user" else logger.info(f"Storekeeper: {m}"))
customer_reply = "Hi."
for _ in range(exchanges):
storekeeper_reply = storekeeper.query(customer_reply)
customer_reply = customer.query(storekeeper_reply)
```
This example demonstrates how two agents (a customer and a storekeeper) can interact with each other, each with their own role,
goal, and task. The agents exchange messages for a specified number of times, simulating a conversation in a shop.
All prompts that we use are stored in yaml files that you can easily overload.
## Chain of Thought Agent with Function Calls
The `ChainOfThoughtAgent` class extends the capabilities of our agents by allowing them to use reasoning steps and call functions.
Here's an example:
```python
from just_agents.patterns.chain_of_throught import ChainOfThoughtAgent
from just_agents import llm_options
def count_letters(character: str, word: str) -> str:
""" Returns the number of character occurrences in the word. """
count = 0
for char in word:
if char == character:
count += 1
print(f"Function: {character} occurs in {word} {count} times.")
return str(count)
# Initialize agent with tools and LLM options
agent = ChainOfThoughtAgent(
tools=[count_letters],
llm_options=llm_options.LLAMA3_3
)
# Optional: Add callback to see all messages
agent.memory.add_on_message(lambda message: print(message))
# Get result and reasoning chain
result, chain = agent.think("Count the number of occurrences of the letter 'L' in the word - 'LOLLAPALOOZA'.")
```
This example shows how a Chain of Thought agent can use a custom function to count letter occurrences in a word. The agent can
reason about the problem and use the provided tool to solve it.
## ðĶ Package Structure
- `just_agents`: Core library
- `just_agents_coding`: Sandbox containers and code execution
- `just_agents_examples`: Usage examples
- `just_agents_tools`: Reusable agent tools
## ð Sandbox Execution
The `just_agents_sandbox` package provides secure containers for code execution:
- ðĶ Sandbox container
- 𧎠Biosandbox container
- ð Websandbox container
Mount `/input` and `/output` directories to easily manage data flow and monitor generated code.
Raw data
{
"_id": null,
"home_page": null,
"name": "just-agents",
"maintainer": "Anton Kulaga",
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": "antonkulaga@gmail.com",
"keywords": "python, llm, agents, AI, machine-learning",
"author": "Alex Karmazin",
"author_email": "karmazinalex@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/2b/3f/24c454bba94bd3e5cd3c2201764187265139082fdf2fcb6ea152a6c17ee8/just_agents-0.4.3.tar.gz",
"platform": null,
"description": "# just-agents\n[](https://github.com/longevity-genie/just-agents/actions/workflows/run_tests.yaml)\n[](https://badge.fury.io/py/just-agents-core)\n[](https://just-agents.readthedocs.io/en/latest/?badge=latest)\n\nA lightweight, straightforward library for LLM agents - no over-engineering, just simplicity!\n\n## Quick Start\n```bash\npip install just-agents-core\n```\n\nWARNING: we are reorganizing the package structure right now so the published package is a bit different than the code in this repository.\n\n## \ud83c\udfaf Motivation\n\nMost of the existing agentic libraries are extremely over-engineered either directly or by using over-engineered libraries under the hood, like langchain and llamaindex.\nIn reality, interactions with LLMs are mostly about strings, and you can write your own template by just using f-strings and python native string templates.\nThere is no need in complicated chain-like classes and other abstractions, in fact popular libraries create complexity just to sell you their paid services for LLM calls monitoring because it is extremely hard to understand what exactly is sent to LLMs.\n\nIt is way easier to reason about the code if you separate your prompting from python code to a separate easily readable files (like yaml files).\n\nWe wrote this libraries while being pissed of by high complexity and wanted something controlled and simple.\nOf course, you might comment that we do not have the ecosystem like, for example, tools and loaders. In reality, most of langchain tools are just very simple functions wrapped in their classes, you can always quickly look at them and write a simple function to do the same thing that just-agents will pick up easily.\n\n## \u2728 Key Features\n- \ud83e\udeb6 Lightweight and simple implementation\n- \ud83d\udcdd Easy-to-understand agent interactions\n- \ud83d\udd27 Customizable prompts using YAML files\n- \ud83e\udd16 Support for various LLM models through litellm\n- \ud83d\udd04 Chain of Thought reasoning with function calls\n\n## \ud83d\udcda Documentation & Tutorials\n\n### Interactive Tutorials (Google Colab)\n- [Basic Agents Tutorial](https://github.com/longevity-genie/just-agents/blob/main/examples/notebooks/01_just_agents_colab.ipynb)\n- [Database Agent Tutorial](https://github.com/longevity-genie/just-agents/blob/main/examples/notebooks/02_sqlite_example.ipynb)\n- [Coding Agent Tutorial](https://github.com/longevity-genie/just-agents/blob/main/examples/notebooks/03_coding_agent.ipynb)\n\n### Example Code\nBrowse our [examples](https://github.com/longevity-genie/just-agents/tree/main/examples) directory for:\n- \ud83d\udd30 Basic usage examples\n- \ud83d\udcbb Code generation and execution\n- \ud83d\udee0\ufe0f Tool integration examples\n- \ud83d\udc65 Multi-agent interactions\n\n\n## \ud83d\ude80 Installation\n\n### Quick Install\n```bash\npip install just-agents-core\n```\n\n### Development Setup\n1. Clone the repository:\n```bash\ngit clone git@github.com:longevity-genie/just-agents.git\ncd just-agents\n```\n\n2. Set up the environment:\nWe use Poetry for dependency management. First, [install Poetry](https://python-poetry.org/docs/#installation) if you haven't already.\n\n```bash\n# Install dependencies using Poetry\npoetry install\n\n# Activate the virtual environment\npoetry shell\n```\n\n3. Configure API keys:\n```bash\ncp .env.example .env\n# Edit .env with your API keys:\n# OPENAI_API_KEY=your_key_here\n# GROQ_API_KEY=your_key_here\n```\n## \ud83c\udfd7\ufe0f Architecture\n\n### Core Components\n1. **BaseAgent**: A thin wrapper around litellm for LLM interactions\n3. **ChainOfThoughtAgent**: Extended agent with reasoning capabilities\n\n\n### ChatAgent\n\nThe `ChatAgent` class is the core of our library. \nIt represents an agent with a specific role, goal, and task. Here's a simple example of two agents talking to each other.\n\n```python\nfrom dotenv import load_dotenv\n\nfrom just_agents.simple.chat_agent import ChatAgent\nfrom just_agents.simple.llm_options import LLAMA3_2_VISION\nload_dotenv(override=True)\n\ncustomer: ChatAgent = ChatAgent(llm_options = LLAMA3_2_VISION, role = \"customer at a shop\",\n goal = \"Your goal is to order what you want, while speaking concisely and clearly\",\n task=\"Find the best headphones!\")\nstorekeeper: ChatAgent = ChatAgent(llm_options = LLAMA3_2_VISION,\n role = \"helpful storekeeper\",\n goal=\"earn profit by selling what customers need\",\n task=\"sell to the customer\")\n\n\nexchanges: int = 3 # how many times the agents will exchange messages\ncustomer.memory.add_on_message(lambda m: logger.info(f\"Customer: {m}\") if m.role == \"user\" else logger.info(f\"Storekeeper: {m}\"))\n\ncustomer_reply = \"Hi.\"\nfor _ in range(exchanges):\n storekeeper_reply = storekeeper.query(customer_reply)\n customer_reply = customer.query(storekeeper_reply)\n```\n\nThis example demonstrates how two agents (a customer and a storekeeper) can interact with each other, each with their own role, \ngoal, and task. The agents exchange messages for a specified number of times, simulating a conversation in a shop.\n\nAll prompts that we use are stored in yaml files that you can easily overload.\n\n## Chain of Thought Agent with Function Calls\n\nThe `ChainOfThoughtAgent` class extends the capabilities of our agents by allowing them to use reasoning steps and call functions. \nHere's an example:\n\n```python\nfrom just_agents.patterns.chain_of_throught import ChainOfThoughtAgent\nfrom just_agents import llm_options\n\ndef count_letters(character: str, word: str) -> str:\n \"\"\" Returns the number of character occurrences in the word. \"\"\"\n count = 0\n for char in word:\n if char == character:\n count += 1\n print(f\"Function: {character} occurs in {word} {count} times.\")\n return str(count)\n\n# Initialize agent with tools and LLM options\nagent = ChainOfThoughtAgent(\n tools=[count_letters],\n llm_options=llm_options.LLAMA3_3\n)\n\n# Optional: Add callback to see all messages\nagent.memory.add_on_message(lambda message: print(message))\n\n# Get result and reasoning chain\nresult, chain = agent.think(\"Count the number of occurrences of the letter 'L' in the word - 'LOLLAPALOOZA'.\")\n```\n\nThis example shows how a Chain of Thought agent can use a custom function to count letter occurrences in a word. The agent can \nreason about the problem and use the provided tool to solve it.\n\n## \ud83d\udce6 Package Structure\n- `just_agents`: Core library\n- `just_agents_coding`: Sandbox containers and code execution\n- `just_agents_examples`: Usage examples\n- `just_agents_tools`: Reusable agent tools\n\n## \ud83d\udd12 Sandbox Execution\n\nThe `just_agents_sandbox` package provides secure containers for code execution:\n- \ud83d\udce6 Sandbox container\n- \ud83e\uddec Biosandbox container\n- \ud83c\udf10 Websandbox container\n\nMount `/input` and `/output` directories to easily manage data flow and monitor generated code.",
"bugtrack_url": null,
"license": "MIT",
"summary": "Just Agents - A lightweight, straightforward library for LLM agents that focuses on simplicity over unnecessary abstractions.",
"version": "0.4.3",
"project_urls": null,
"split_keywords": [
"python",
" llm",
" agents",
" ai",
" machine-learning"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1fe3e33f2a4885df3187796ebaec6ebf23046bb292283b89d1fde9b5b5461408",
"md5": "492b63d111c606857c6e98255b3fd853",
"sha256": "da3a7b560290589fd76424eea7d8d1cac4e9f4b988f72ea9f442396cfae77c2e"
},
"downloads": -1,
"filename": "just_agents-0.4.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "492b63d111c606857c6e98255b3fd853",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 5236,
"upload_time": "2024-12-07T23:39:16",
"upload_time_iso_8601": "2024-12-07T23:39:16.207992Z",
"url": "https://files.pythonhosted.org/packages/1f/e3/e33f2a4885df3187796ebaec6ebf23046bb292283b89d1fde9b5b5461408/just_agents-0.4.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2b3f24c454bba94bd3e5cd3c2201764187265139082fdf2fcb6ea152a6c17ee8",
"md5": "3810f10ce96a2cd12407b78360f1a21d",
"sha256": "3a294fbf223210792d909a8a86751c25c66b255d48f56f8b111e5fc71123e57c"
},
"downloads": -1,
"filename": "just_agents-0.4.3.tar.gz",
"has_sig": false,
"md5_digest": "3810f10ce96a2cd12407b78360f1a21d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 4883,
"upload_time": "2024-12-07T23:39:17",
"upload_time_iso_8601": "2024-12-07T23:39:17.347618Z",
"url": "https://files.pythonhosted.org/packages/2b/3f/24c454bba94bd3e5cd3c2201764187265139082fdf2fcb6ea152a6c17ee8/just_agents-0.4.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-07 23:39:17",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "just-agents"
}
