tiny-agent-os

Name	tiny-agent-os JSON
Version	0.73.3 JSON
	download
home_page	None
Summary	A streamlined framework for building powerful LLM-powered agents that actually work
upload_time	2025-09-09 18:40:23
maintainer	None
docs_url	None
author	alchemiststudios.ai
requires_python	>=3.10
license	Business Source License 1.1
keywords	ai agent llm openai gpt react
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # tinyAgent

![tinyAgent Logo](static/images/tinyAgent_logo_v2.png)

Turn any Python function into an AI‑powered agent in just a few lines:

```python
from tinyagent import tool, ReactAgent

@tool
def multiply(a: float, b: float) -> float:
    """Multiply two numbers together."""
    return a * b

@tool
def divide(a: float, b: float) -> float:
    """Divide the first number by the second number."""
    return a / b

agent = ReactAgent(tools=[multiply, divide])
result = agent.run("What is 12 times 5, then divided by 3?")
# → 20
```

That's it! The agent automatically:
- Understands it needs to perform multiple steps
- Calls `multiply(12, 5)` → gets 60
- Takes that result and calls `divide(60, 3)` → gets 20
- Returns the final answer

## Why tinyAgent?

- **Zero boilerplate** – Just decorate functions with `@tool`
- **Automatic reasoning** – Agent figures out which tools to use and in what order
- **Built-in LLM** – Works out of the box with OpenRouter
- **Type safe** – Full type hints and validation
- **Production ready** – Error handling and retries

## Installation

### Option A: UV (Recommended - 10x Faster)
```bash
uv venv                    # Creates .venv/
source .venv/bin/activate  # Activate environment
uv pip install tiny_agent_os
```

### Option B: Traditional pip
```bash
pip install tiny_agent_os
```

## Quick Setup

Set your API key:
```bash
export OPENAI_API_KEY=your_openrouter_key_here
export OPENAI_BASE_URL=https://openrouter.ai/api/v1
```

Get your key at [openrouter.ai](https://openrouter.ai)

> **Note**: This is a clean rewrite focused on keeping tinyAgent truly tiny. For the legacy codebase (v0.72.x), install with `pip install tiny-agent-os==0.72.18` or see the [`0.72` branch](https://github.com/alchemiststudiosDOTai/tinyAgent/tree/0.72).

## Package Structure

As of v0.73, tinyAgent's internal structure has been reorganized for better maintainability:

- `tinyagent/agent.py` → `tinyagent/agents/agent.py` (ReactAgent)
- `tinyagent/code_agent.py` → `tinyagent/agents/code_agent.py` (TinyCodeAgent)

The public API remains unchanged - you can still import directly from `tinyagent`:
```python
from tinyagent import ReactAgent, TinyCodeAgent, tool
```

## Setting the Model

Pass any OpenRouter model when creating the agent:

```python
from tinyagent import ReactAgent, tool

# Default model
agent = ReactAgent(tools=[...])

# Specify a model
agent = ReactAgent(tools=[...], model="gpt-4o-mini")
agent = ReactAgent(tools=[...], model="anthropic/claude-3.5-sonnet")
agent = ReactAgent(tools=[...], model="meta-llama/llama-3.1-70b-instruct")

# TinyCodeAgent works the same way
agent = TinyCodeAgent(tools=[...], model="gpt-4o-mini")
```

## More Examples

### Multi-step reasoning
```python
from tinyagent import tool, ReactAgent

@tool
def calculate_percentage(value: float, percentage: float) -> float:
    """Calculate what percentage of a value is."""
    return value * (percentage / 100)

@tool
def subtract(a: float, b: float) -> float:
    """Subtract b from a."""
    return a - b

agent = ReactAgent(tools=[calculate_percentage, subtract])
result = agent.run("If I have 15 apples and give away 40%, how many are left?")
print(result)  # → "You have 9 apples left."
```

Behind the scenes:
1. Agent calculates 40% of 15 → 6
2. Subtracts 6 from 15 → 9
3. Returns a natural language answer

### Web Search Tool
Built-in web search capabilities with Brave Search API:

```python
from tinyagent import ReactAgent
from tinyagent.base_tools import web_search

# Simple web search with formatted results
agent = ReactAgent(tools=[web_search])
result = agent.run("What are the latest Python web frameworks?")

# Works great for research and comparisons
agent = ReactAgent(tools=[web_search])
result = agent.run("Compare FastAPI vs Django performance")
```

Set your Brave API key:
```bash
export BRAVE_SEARCH_API_KEY=your_brave_api_key
```

## Key Features

### ReactAgent
- **Multi-step reasoning** - Breaks down complex problems automatically
- **Clean API** - Simple, ergonomic interface
- **Error handling** - Built-in retry logic and graceful failures

### Tools Philosophy
Every function can be a tool. Keep them:
- **Atomic** - Do one thing well
- **Typed** - Use type hints for parameters
- **Documented** - Docstrings help the LLM understand usage

For a comprehensive guide on creating tools with patterns and best practices, see the [tool creation documentation](documentation/modules/tools.md).

## Status

**BETA** - Actively developed and used in production. Breaking changes possible until v1.0.

Found a bug? Have a feature request? [Open an issue](https://github.com/alchemiststudiosDOTai/tinyAgent/issues)!

## License

**Business Source License 1.1**
- Free for individuals and small businesses (< $1M revenue)
- Enterprise license required for larger companies

Contact: [info@alchemiststudios.ai](mailto:info@alchemiststudios.ai)

---

Made by [@tunahorse21](https://x.com/tunahorse21) | [alchemiststudios.ai](https://alchemiststudios.ai) focusing on keeping it "tiny"

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "tiny-agent-os",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.10",
    "maintainer_email": null,
    "keywords": "ai, agent, llm, openai, gpt, react",
    "author": "alchemiststudios.ai",
    "author_email": null,
    "download_url": "https://files.pythonhosted.org/packages/c4/e2/0537b3901c40c7bd7b4ee3ca9d24d85bd00270dc9e3a4780f7a18bed839b/tiny_agent_os-0.73.3.tar.gz",
    "platform": null,
    "description": "# tinyAgent\n\n![tinyAgent Logo](static/images/tinyAgent_logo_v2.png)\n\nTurn any Python function into an AI\u2011powered agent in just a few lines:\n\n```python\nfrom tinyagent import tool, ReactAgent\n\n@tool\ndef multiply(a: float, b: float) -> float:\n    \"\"\"Multiply two numbers together.\"\"\"\n    return a * b\n\n@tool\ndef divide(a: float, b: float) -> float:\n    \"\"\"Divide the first number by the second number.\"\"\"\n    return a / b\n\nagent = ReactAgent(tools=[multiply, divide])\nresult = agent.run(\"What is 12 times 5, then divided by 3?\")\n# \u2192 20\n```\n\nThat's it! The agent automatically:\n- Understands it needs to perform multiple steps\n- Calls `multiply(12, 5)` \u2192 gets 60\n- Takes that result and calls `divide(60, 3)` \u2192 gets 20\n- Returns the final answer\n\n## Why tinyAgent?\n\n- **Zero boilerplate** \u2013 Just decorate functions with `@tool`\n- **Automatic reasoning** \u2013 Agent figures out which tools to use and in what order\n- **Built-in LLM** \u2013 Works out of the box with OpenRouter\n- **Type safe** \u2013 Full type hints and validation\n- **Production ready** \u2013 Error handling and retries\n\n## Installation\n\n### Option A: UV (Recommended - 10x Faster)\n```bash\nuv venv                    # Creates .venv/\nsource .venv/bin/activate  # Activate environment\nuv pip install tiny_agent_os\n```\n\n### Option B: Traditional pip\n```bash\npip install tiny_agent_os\n```\n\n## Quick Setup\n\nSet your API key:\n```bash\nexport OPENAI_API_KEY=your_openrouter_key_here\nexport OPENAI_BASE_URL=https://openrouter.ai/api/v1\n```\n\nGet your key at [openrouter.ai](https://openrouter.ai)\n\n> **Note**: This is a clean rewrite focused on keeping tinyAgent truly tiny. For the legacy codebase (v0.72.x), install with `pip install tiny-agent-os==0.72.18` or see the [`0.72` branch](https://github.com/alchemiststudiosDOTai/tinyAgent/tree/0.72).\n\n## Package Structure\n\nAs of v0.73, tinyAgent's internal structure has been reorganized for better maintainability:\n\n- `tinyagent/agent.py` \u2192 `tinyagent/agents/agent.py` (ReactAgent)\n- `tinyagent/code_agent.py` \u2192 `tinyagent/agents/code_agent.py` (TinyCodeAgent)\n\nThe public API remains unchanged - you can still import directly from `tinyagent`:\n```python\nfrom tinyagent import ReactAgent, TinyCodeAgent, tool\n```\n\n## Setting the Model\n\nPass any OpenRouter model when creating the agent:\n\n```python\nfrom tinyagent import ReactAgent, tool\n\n# Default model\nagent = ReactAgent(tools=[...])\n\n# Specify a model\nagent = ReactAgent(tools=[...], model=\"gpt-4o-mini\")\nagent = ReactAgent(tools=[...], model=\"anthropic/claude-3.5-sonnet\")\nagent = ReactAgent(tools=[...], model=\"meta-llama/llama-3.1-70b-instruct\")\n\n# TinyCodeAgent works the same way\nagent = TinyCodeAgent(tools=[...], model=\"gpt-4o-mini\")\n```\n\n## More Examples\n\n### Multi-step reasoning\n```python\nfrom tinyagent import tool, ReactAgent\n\n@tool\ndef calculate_percentage(value: float, percentage: float) -> float:\n    \"\"\"Calculate what percentage of a value is.\"\"\"\n    return value * (percentage / 100)\n\n@tool\ndef subtract(a: float, b: float) -> float:\n    \"\"\"Subtract b from a.\"\"\"\n    return a - b\n\nagent = ReactAgent(tools=[calculate_percentage, subtract])\nresult = agent.run(\"If I have 15 apples and give away 40%, how many are left?\")\nprint(result)  # \u2192 \"You have 9 apples left.\"\n```\n\nBehind the scenes:\n1. Agent calculates 40% of 15 \u2192 6\n2. Subtracts 6 from 15 \u2192 9\n3. Returns a natural language answer\n\n### Web Search Tool\nBuilt-in web search capabilities with Brave Search API:\n\n```python\nfrom tinyagent import ReactAgent\nfrom tinyagent.base_tools import web_search\n\n# Simple web search with formatted results\nagent = ReactAgent(tools=[web_search])\nresult = agent.run(\"What are the latest Python web frameworks?\")\n\n# Works great for research and comparisons\nagent = ReactAgent(tools=[web_search])\nresult = agent.run(\"Compare FastAPI vs Django performance\")\n```\n\nSet your Brave API key:\n```bash\nexport BRAVE_SEARCH_API_KEY=your_brave_api_key\n```\n\n## Key Features\n\n### ReactAgent\n- **Multi-step reasoning** - Breaks down complex problems automatically\n- **Clean API** - Simple, ergonomic interface\n- **Error handling** - Built-in retry logic and graceful failures\n\n### Tools Philosophy\nEvery function can be a tool. Keep them:\n- **Atomic** - Do one thing well\n- **Typed** - Use type hints for parameters\n- **Documented** - Docstrings help the LLM understand usage\n\nFor a comprehensive guide on creating tools with patterns and best practices, see the [tool creation documentation](documentation/modules/tools.md).\n\n## Status\n\n**BETA** - Actively developed and used in production. Breaking changes possible until v1.0.\n\nFound a bug? Have a feature request? [Open an issue](https://github.com/alchemiststudiosDOTai/tinyAgent/issues)!\n\n## License\n\n**Business Source License 1.1**\n- Free for individuals and small businesses (< $1M revenue)\n- Enterprise license required for larger companies\n\nContact: [info@alchemiststudios.ai](mailto:info@alchemiststudios.ai)\n\n---\n\nMade by [@tunahorse21](https://x.com/tunahorse21) | [alchemiststudios.ai](https://alchemiststudios.ai) focusing on keeping it \"tiny\"\n",
    "bugtrack_url": null,
    "license": "Business Source License 1.1",
    "summary": "A streamlined framework for building powerful LLM-powered agents that actually work",
    "version": "0.73.3",
    "project_urls": {
        "Homepage": "https://tinyagent.xyz",
        "Issues": "https://github.com/alchemiststudiosDOTai/tinyAgent/issues",
        "Repository": "https://github.com/alchemiststudiosDOTai/tinyAgent"
    },
    "split_keywords": [
        "ai",
        " agent",
        " llm",
        " openai",
        " gpt",
        " react"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "8cd0b794b0718162a099ae8112f00e495ae394c27a384057406bdb4e4828736a",
                "md5": "5df86472935d82b791d3eff884dfe0d2",
                "sha256": "7ba0eb1ed1809a2765a8d92e94aa0ec4fd2b2945aecf1540a096601b7754a4aa"
            },
            "downloads": -1,
            "filename": "tiny_agent_os-0.73.3-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "5df86472935d82b791d3eff884dfe0d2",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.10",
            "size": 15234,
            "upload_time": "2025-09-09T18:40:21",
            "upload_time_iso_8601": "2025-09-09T18:40:21.937198Z",
            "url": "https://files.pythonhosted.org/packages/8c/d0/b794b0718162a099ae8112f00e495ae394c27a384057406bdb4e4828736a/tiny_agent_os-0.73.3-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "c4e20537b3901c40c7bd7b4ee3ca9d24d85bd00270dc9e3a4780f7a18bed839b",
                "md5": "7dd6e99d92ccb64b0d8ef0896ec8e46a",
                "sha256": "e71ed2e45df974e7cc06f97210699b26d8e3db2838da3afea3b4556fe893fc85"
            },
            "downloads": -1,
            "filename": "tiny_agent_os-0.73.3.tar.gz",
            "has_sig": false,
            "md5_digest": "7dd6e99d92ccb64b0d8ef0896ec8e46a",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.10",
            "size": 2320799,
            "upload_time": "2025-09-09T18:40:23",
            "upload_time_iso_8601": "2025-09-09T18:40:23.641647Z",
            "url": "https://files.pythonhosted.org/packages/c4/e2/0537b3901c40c7bd7b4ee3ca9d24d85bd00270dc9e3a4780f7a18bed839b/tiny_agent_os-0.73.3.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-09-09 18:40:23",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "alchemiststudiosDOTai",
    "github_project": "tinyAgent",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "tiny-agent-os"
}