Metadata-Version: 2.1
Name: freeact
Version: 0.2.0
Summary: A general-purpose CodeAct Agent
Home-page: https://github.com/gradion-ai/freeact
License: Apache-2.0
Author: Martin Krasser
Author-email: martin@gradion.ai
Requires-Python: >=3.11,<3.14
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: aioconsole (>=0.8.1,<0.9.0)
Requires-Dist: aiofiles (>=24.1,<25.0)
Requires-Dist: anthropic (>=0.39.0,<0.40.0)
Requires-Dist: google-genai (>=0.3.0,<0.4.0)
Requires-Dist: httpx (>=0.27.2,<0.28.0)
Requires-Dist: ipybox (>=0.3.0,<0.4.0)
Requires-Dist: python-dotenv (>=1.0,<2.0)
Requires-Dist: rich (>=13.9,<14.0)
Requires-Dist: typer (>=0.12.5,<0.13.0)
Description-Content-Type: text/markdown

# freeact

`freeact` is a lightweight Python implementation of AI agents that use *code actions* to dynamically interact with and adapt to their environment.

<p align="center">
  <img src="docs/img/strawberry.resized.png" alt="logo" width="400">
</p>

`freeact` agents:

- Write their actions in code, rather than just being agents for writing code. No JSON tool configs required
- Have a broad action space since they can install and use any Python library in their code actions
- Autonomously improve their code actions through reflection on environmental observations, execution feedback, and human input
- Store code actions as custom skills in long-term memory for efficient reuse, enabling the composition of higher-level capabilities
- Perform software-engineering tasks during the interactive development and optimization of custom agent skills
- Execute code actions in [`ipybox`](https://gradion-ai.github.io/ipybox/), a secure code execution environment built with IPython and Docker.

`freeact` agents can function as general-purpose agents right out of the box—no extra tool configuration needed—or be specialized for specific environments using custom skills and system extensions:

- Custom skills provide optimized interfaces for the agent to interact with specific environments
- System extensions provide natural language configurations for custom domain knowledge and agent behavior

## Documentation

The `freeact` documentation is available [here](https://gradion-ai.github.io/freeact/).

## Quickstart

### Installation

Install `freeact` using pip:

```bash
pip install freeact
```

### Configuration

Create a `.env` file with API keys:

```env title=".env"
# Required for Claude 3.5 Sonnet
# https://docs.anthropic.com/en/docs/api/api-keys
ANTHROPIC_API_KEY=...

# Required for generative Google Search via Gemini 2
# https://aistudio.google.com/app/apikey
GOOGLE_API_KEY=...
```

### Launch the Agent

Start a `freeact` agent with generative Google Search skill using the CLI:

```bash
python -m freeact.cli \
  --model-name=claude-3-5-sonnet-20241022 \
  --ipybox-tag=ghcr.io/gradion-ai/ipybox:basic \
  --executor-key=example \
  --skill-modules=freeact_skills.search.google.stream.api
```

Once launched, you can start interacting with the agent:

[![output](docs/tutorials/output/quickstart.svg)](docs/tutorials/output/quickstart.html)

