updated docs a bit

README.md

@@ -105,20 +105,51 @@ This example shows how a Chain of Thought agent can use a custom function to cou
 * just_agents_examples - contains examples of just-agents usage
 * just_agents_tools - contains useful tools that you can use in your agents
 
+# Examples
+
+Examples is one of the easiest ways to get started with just-agents.
+Start with basic examples and then move on to multiagent and coding examples.
+For coding examples you might need to have docker installed to be able to run the containers.
+
+
 # Installation
 
+Note: the instructions below assume that you are running the code on Linuxor under WSL2 on Windows.
+If you use plain Windows you may use user interfaces instead of some of the commands below.
+Also, we recommend using virtual environment and give examples with micromamba (which is same as conda or anaconda in API) however you can use any other environment tool
+
+## Using pip
 If you want to install as pip package use:
 ```
 pip install just-agents
 ```
 
-If you want to contribute to the project you can use micromamba or other anaconda to install the environment
+## Local Development
+
+To contribute or develop locally:
+
+1. Clone the repository (SSH recommended for contributors):
+```bash
+# Using SSH (recommended for contributors)
+git clone git@github.com:longevity-genie/just-agents.git
+
+# Or using HTTPS
+git clone https://github.com/longevity-genie/just-agents.git
 ```
+
+2. Change to the project directory:
+```bash
+cd just-agents
+```
+
+3. Set up the development environment using micromamba or other anaconda:
+```bash
 micromamba create -f environment.yaml
 micromamba activate just-agents
 ```
-then you can edit the library. Optionally you can install it locally with:
-```
+
+4. (Optional) Install the package in editable mode:
+```bash
 pip install -e .
 ```
 
@@ -129,7 +160,7 @@ Create configuration file:
 
 Edit the configuration file:
 
-   This refers to API keys. You'll need to edit these files to customize your setup.
+   This refers to API keys for various LLMs. You'll need to edit these files to customize your setup.
 
 Edit `.env`:
       ```bash
@@ -143,8 +174,10 @@ Edit `.env`:
 
 
 
-# Running the code by agents
+# Running the code by coding agents
+
+You can allow agents to install dependencies and run code by using the sandbox, biosandbox or websandbox containers.
 
-You can allow agents to install dependencies and run code by using the sandbox container.
+We provide a package just_agents_sandbox that contains the sandbox and biosandbox containers as well as micromamba session to run the containers.
 
-We provide a package just_agents_sandbox that contains the sandbox and biosandbox containers as well as micromamba session to run the containers.
+In some of the examples we also provide mounting /input and /output directories to the containers to make it easier to pass data to and from the agents and see which code and bash commands are being generated.

examples/basic/agent_from_yaml.py

@@ -5,6 +5,11 @@
 
 basic_examples_dir = Path(__file__).parent.absolute()
 
+"""
+This example shows how an agent can be built from a yaml file.
+In complex use-cases it can be useful to keep agents in yaml files to be able to iterate on them without changing the code.
+"""
+
 if __name__ == "__main__":
     assistant: IAgent = build_agent(basic_examples_dir / "agent_from_yaml.yaml")
     print(assistant.query("Count the number of occurrences of the letter ’L’ in the word - ’LOLLAPALOOZA’."))

examples/basic/agent_serialization.py

@@ -13,6 +13,7 @@
 
 """
 This example shows how to save and load an agent from a yaml file.
+In complex use-cases it can be useful to keep agents in yaml files to be able to iterate on them without changing the code.
 """
 
 

examples/basic/function_calling.py

@@ -1,4 +1,3 @@
-#from just_agents.chat_agent import ChatAgent
 import asyncio
 import json
 import pprint
@@ -11,6 +10,10 @@
 
 load_dotenv(override=True)
 
+"""
+This example shows how a function can be used to call a function which potentially can have an external API call.
+"""
+
 def get_current_weather(location: str):
     """Gets the current weather in a given location"""
     if "tokyo" in location.lower():
@@ -27,15 +30,14 @@ def get_current_weather(location: str):
 
     llm_options = just_agents.llm_options.LLAMA3_2
 
-    key_getter = rotate_env_keys
     prompt = "What's the weather like in San Francisco, Tokyo, and Paris?"
 
     load_dotenv(override=True)
     session: LLMSession = LLMSession(
         llm_options=just_agents.llm_options.LLAMA3_2,
         tools=[get_current_weather]
     )
-    result = session.query("What's the weather like in San Francisco, Tokyo, and Paris?")
+    result = session.query(prompt)
 
     # I think we need to show all the messages. So should we ignore assistant message?
     # session.memory.add_on_message(lambda m: pprint.pprint(m) if "content" in m is not None else None)

examples/multiagent/glucose_dao_reflection.py

@@ -13,6 +13,12 @@
 output_dir = examples_dir.parent  / "output" / current_dir.name
 output_dir.mkdir(exist_ok=True, parents=True)
 
+"""
+This example shows how a multiagent system can be used to create a plan for a DAO or nonprofit.
+Here we use the simple reflection mechanism to iteratively improve the plan by having a planner and a reviewer.
+In real-world use-cases we can have more sophisticated configurations, when there are also agents that search in the internet, agents that do coding, etc.
+"""
+
 @app.command()
 def planning_example():
     load_dotenv()

examples/multiagent/two_agents_chat.py

@@ -6,6 +6,10 @@
 
 app = typer.Typer(no_args_is_help=True)
 
+"""
+This example shows how two agents can be used to simulate a simple chat.
+"""
+
 @app.command()
 def purchase_example():
     load_dotenv()

just_agents_coding/containers/websandbox/env.yaml

@@ -14,4 +14,6 @@ dependencies:
   - pyarrow
   - pip:
       - fake-useragent
-      - cloudscraper
+      - cloudscraper
+      - html2text  # HTML to markdown converter
+      - undetected-chromedriver  # Anti-bot detection for Selenium