# VenusAI - Advanced Agent Framework 🚀
VenusAI is a **secure and extensible Agent framework** built for modern AI applications.
It offers **dynamic tool management**, **powerful decorators**, **advanced caching**, **robust error handling**, a built-in **CLI**, and seamless **Claude MCP integration**.
---
## Installation
Install library via pip or uv.
> Note: The venusai is alias of venai, you can use both but venai is the main package.
```bash
pip install venai
pip install venusai
```
**or**
```bash
uv add venai
uv add venusai
```
Install latest NodeJS with npx for Claude Desktop HTTP support.
> Note: mcp-remote package used for support.
---
## 🔑 Key Capabilities
* 🛡️ **Security-first design** with permission-based tool filtering & E2B sandbox integration
* 🔧 **Dynamic tool ecosystem** with decorators for safety, autofix & error recovery
* ⚡ **High-performance caching** with multiple backends (`aiocache`, `lrucache`, `async-lru`, `cachetools`)
* 🌐 **HTTP API generation** → automatically expose tools as REST endpoints
* 🤖 **MCP Protocol native support** → seamless Claude Desktop integration
* 🎯 **Type-safe dependency injection** with advanced context management
* 🔄 **Self-healing tools** → automatic error recovery & retry mechanisms
* 📊 **Comprehensive error tracking** with detailed frame info & custom handlers
> Whether you're building simple chatbots or complex multi-agent systems, VenusAI provides the foundation for **scalable, maintainable, and secure AI applications**.
---
## ✨ Features
### 🔹 Core Bases
* **Venus**
* Base class for all Agents
* No default toolset (bare Agent)
* **VenusCode**
* Subclass of Venus with coding capabilities
* Built-in filesystem toolset
* **Permission-based tool filtering** (supports custom permitters)
* Code execution **disabled by default**
* **E2B sandbox integration** for safe execution
---
### 🔹 Tools
* **Dynamic tool integration** from modules
* **Dynamic Dependency Injection**
* **Decorators**
* `@agent.safe` → error-safe wrapper for non-context tools
* `@agent.safe_plain` → error-safe wrapper for context tools
* `@agent.autofix` → self-healing tools (functions can fix themselves)
* `@agent.on_error` → custom error handler
* **Register tools as HTTP endpoints** *(beta)*
* Convert registered tools to HTTP API (via FastAPI)
* Just call `agent.tools_http_api()` and `agent.serve()`
* **Sync/Async caching** for tools with `@cached`
* Backends: `aiocache`, `lrucache`, `async-lru`, `cachetools`
* **Autofix mechanism**
* Implicitly handles errors via `@safe`
* Customizable fix-prompt & fix-model
* Falls back to a default model if none provided
* **Error Handlers**
* Errors yield an **ErrorDict** with frame & error details
* Fully customizable responses/actions
---
### 🔹 Example
```python
from venus import Venus
from venus.errors import ErrorDict
from venus.types import Deps, DepsT, ModelRetry, RunContext
import hashlib
agent = Venus("grok:grok-3", deps_type=int)
class Bank(Deps[DepsT]):
reserve: int
"""Current bank reserves."""
@agent.on_error
async def retry_on_failure(err: ErrorDict):
print(f"Error occurred: {err.exception} at {err.location}. Retrying...")
raise ModelRetry(err.exception)
@agent.on_error
async def notify(err: ErrorDict):
# e.g: await send_mail(body=err.message)
pass
def get_reserves():
return 1_881_938
def get_details():
return {'code': 'tr', 'swift': 1283, 'id': 1710}
@agent.safe(retries=3, deps=Deps(reserve=get_reserves, details=get_details))
async def add_money(ctx: RunContext[Bank[int]], fund: int):
if fund <= 5:
raise ValueError("Enter a number greater than 5.")
ctx.deps.reserve += fund
bank_details = ctx.deps.get(dict)
bank_id = bank_details['id']
tx_hash = hashlib.md5(str(bank_id + ctx.deps.reserve).encode()).hexdigest()
print(f"Connected bank with ID {bank_details['code'].upper()}{bank_details['swift']}")
print(f"Added ${fund} to current (${ctx.deps.reserve - fund}) reserves.")
print(f"Hash for transaction: {tx_hash}")
return ctx.deps.reserve
```
**Run:**
```python
result = agent.run_sync("Add random money to the bank, pick 4 to 6.", output_type=int)
print(result.output)
```
**or**
```python
a2a = agent.to_a2a()
```
```bash
venus serve agent:agent a2a --env dev
```
> ✅ This example is complete and runnable as-is.
---
### 🔹 MCP (Model Context Protocol)
* **Tool integration** from modules via `@tool` / `@mcp_tool`
* **Dynamic Claude configuration** with `MCP.configure(configure_claude=True)`
* **Dependency Injection** support for MCP tools
* **mcp-remote integration** with HTTP/SSE for Claude Desktop
---
### 🔹 CLI
Venus provides a **command-line interface (CLI)** to manage and run agents.
You can start chats, serve APIs, or launch MCP servers directly from the terminal.
#### Available Commands
* **Chat with an agent**
```bash
venus chat module:app
```
* **Run MCP Server**
```bash
venus mcp --path my_tools.py --name "Venus MCP" --host 127.0.0.1 --port 8000 --transport <sse|http|stdio> --configure
```
```bash
venus mcp --path my_tools.py --name "Venus MCP" --host 127.0.0.1 --port 8000 --transport <sse|http|stdio> --configure --all
```
* **Serve an Agent as API**
```bash
venus serve mymodule:agent --auto --env dev
```
#### CLI Options
* `chat` → Start interactive CLI chat with an agent
* `mcp` → Run an MCP server with tools from modules
* `serve` → Expose your agent via HTTP (FastAPI/Uvicorn)
* Supports plugins such as **A2A** (`a2a`)
---
## ⚡ Usage Examples
### Basic Agent
```python
from agent import Venus
agent = Venus(name="venus")
response = agent.run_sync("Hello there!")
print(result.output)
```
### Code-Capable Agent
```python
from venus import VenusCode
from venus.permissions import Permissions
from venus.helpers.io import io_toolset
def my_permitter(permission: int):
if not permission & Permissions.EXECUTE and permission & Permissions.READ:
return ["read_file_content"]
return list(io_toolset.tools.keys())
code_agent = VenusCode(
name="coder",
permission=Permissions.READ_EXECUTE,
permitter=my_permitter, # do not set a permitter to use default permitter
)
```
### Dependency Injection
```python
from venus import Venus
from venus.types import Deps, DepsT, RunContext
import uuid
import time
agent = Venus(deps_type=int)
uuidgen = lambda: uuid.uuid4().hex
datagen = lambda: {'foo': [Deps(bar='baz')]}
class Auth(Deps[DepsT]):
id: str
@agent.safe(deps=Deps(id=uuidgen, data=datagen))
def get_tx(ctx: RunContext[Auth[int]]): # AgentDepsT is int here
# attribute-style access to deps entity `id`
txhash = f'%d$%s' % (time.time(), ctx.deps.id)
# type-based access to deps entity `foo`
data = ctx.deps.get(dict) # None
data = ctx.deps.get(list) # [Deps(bar='baz')]
# access main dependency for agent
agentdeps = ctx.deps.main # int
# type-based access to deps entity `foo`
# use exact annotation to access it:
data = ctx.deps.get(list[Deps]) # [Deps(bar='baz')]
return txhash + data.bar
```
### Module Tools with Decorators
```python
# agent.py
from venus import Venus
agent = Venus(tool_modules='agent_tools')
```
```python
# agent_tools.py
from venus.types import Deps
from venus.caching import cached
from venus.decorators import tool, mcp_tool, safe_call, autofix
@tool
@cached(ttl=240)
def get_id():
return 1
@mcp_tool(deps=Deps(id=get_id))
def get_username(deps: Deps):
return f'@user{deps.id}'
@safe_call
async def create_user(username: str):
return True
@autofix
async def risky_function():
raise Exception('An error occured')
```
### Agent Tools with Decorators
```python
# agent.py
from venus import Venus
from venus.types import RunContext
agent = Venus()
@agent.safe_plain
def add(x: int, y: int) -> int:
return x + y
@agent.safe(retries=3)
def sub(ctx: RunContext, x: int, y: int) -> int:
return x - y
@agent.autofix(retries=2, deps=Deps(result=lambda: 20))
def risky_function(data: str):
raise Exception('An error occured')
```
---
## 🛠 Tech Stack
* **Python 3.10+** → async-first with modern type hints
* **Based on PydanticAI** → robust validation & AI agent foundation
* **ASGI-compatible** → works with FastAPI, Uvicorn, etc.
* **MCP Protocol** → native Model Context Protocol integration
* **Secure execution** with E2B Sandbox
* **CLI powered by Click** → ergonomic, extensible command line
* **Advanced Caching** → multiple backend support
* **Dependency Injection** → type-safe, dynamic DI system
* **Error Handling** → custom recovery & retry strategies
* **Decorator System** → tool safety, autofix & error control
* **HTTP API Generation** → auto REST endpoint conversion
---
## 🤝 Contributing
Contributions are welcome! 🎉
Please open an **issue** before submitting a PR to discuss your idea.
---
## 📜 License
Licensed under the **MIT License** – see the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "venai",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Mert Sirakaya <contact@tomris.dev>",
"keywords": "agent, agentic ai, ai, ai agent, llm, pydantic, pydantic-ai, safety, sandbox, self-healing",
"author": null,
"author_email": "Mert Sirakaya <contact@tomris.dev>",
"download_url": "https://files.pythonhosted.org/packages/43/0c/fbbec2a8b254e4b4d2eca917042a5250ecb1d524cc27dd361261154685ae/venai-1.28.7.tar.gz",
"platform": null,
"description": "# VenusAI - Advanced Agent Framework \ud83d\ude80\n\nVenusAI is a **secure and extensible Agent framework** built for modern AI applications.\nIt offers **dynamic tool management**, **powerful decorators**, **advanced caching**, **robust error handling**, a built-in **CLI**, and seamless **Claude MCP integration**.\n\n---\n## Installation\n\nInstall library via pip or uv.\n\n> Note: The venusai is alias of venai, you can use both but venai is the main package.\n\n```bash\npip install venai\npip install venusai\n```\n\n**or**\n\n```bash\nuv add venai\nuv add venusai\n```\n\nInstall latest NodeJS with npx for Claude Desktop HTTP support.\n> Note: mcp-remote package used for support.\n---\n\n## \ud83d\udd11 Key Capabilities\n\n* \ud83d\udee1\ufe0f **Security-first design** with permission-based tool filtering & E2B sandbox integration\n* \ud83d\udd27 **Dynamic tool ecosystem** with decorators for safety, autofix & error recovery\n* \u26a1 **High-performance caching** with multiple backends (`aiocache`, `lrucache`, `async-lru`, `cachetools`)\n* \ud83c\udf10 **HTTP API generation** \u2192 automatically expose tools as REST endpoints\n* \ud83e\udd16 **MCP Protocol native support** \u2192 seamless Claude Desktop integration\n* \ud83c\udfaf **Type-safe dependency injection** with advanced context management\n* \ud83d\udd04 **Self-healing tools** \u2192 automatic error recovery & retry mechanisms\n* \ud83d\udcca **Comprehensive error tracking** with detailed frame info & custom handlers\n\n> Whether you're building simple chatbots or complex multi-agent systems, VenusAI provides the foundation for **scalable, maintainable, and secure AI applications**.\n\n---\n\n## \u2728 Features\n\n### \ud83d\udd39 Core Bases\n\n* **Venus**\n\n * Base class for all Agents\n * No default toolset (bare Agent)\n\n* **VenusCode**\n\n * Subclass of Venus with coding capabilities\n * Built-in filesystem toolset\n * **Permission-based tool filtering** (supports custom permitters)\n * Code execution **disabled by default**\n * **E2B sandbox integration** for safe execution\n\n---\n\n### \ud83d\udd39 Tools\n\n* **Dynamic tool integration** from modules\n\n* **Dynamic Dependency Injection**\n\n* **Decorators**\n\n * `@agent.safe` \u2192 error-safe wrapper for non-context tools\n * `@agent.safe_plain` \u2192 error-safe wrapper for context tools\n * `@agent.autofix` \u2192 self-healing tools (functions can fix themselves)\n * `@agent.on_error` \u2192 custom error handler\n\n* **Register tools as HTTP endpoints** *(beta)*\n\n * Convert registered tools to HTTP API (via FastAPI)\n * Just call `agent.tools_http_api()` and `agent.serve()`\n\n* **Sync/Async caching** for tools with `@cached`\n\n * Backends: `aiocache`, `lrucache`, `async-lru`, `cachetools`\n\n* **Autofix mechanism**\n\n * Implicitly handles errors via `@safe`\n * Customizable fix-prompt & fix-model\n * Falls back to a default model if none provided\n\n* **Error Handlers**\n\n * Errors yield an **ErrorDict** with frame & error details\n * Fully customizable responses/actions\n\n---\n\n### \ud83d\udd39 Example\n\n```python\nfrom venus import Venus\nfrom venus.errors import ErrorDict\nfrom venus.types import Deps, DepsT, ModelRetry, RunContext\nimport hashlib\n\nagent = Venus(\"grok:grok-3\", deps_type=int)\n\nclass Bank(Deps[DepsT]):\n reserve: int\n \"\"\"Current bank reserves.\"\"\"\n\n@agent.on_error\nasync def retry_on_failure(err: ErrorDict):\n print(f\"Error occurred: {err.exception} at {err.location}. Retrying...\")\n raise ModelRetry(err.exception)\n\n@agent.on_error\nasync def notify(err: ErrorDict):\n # e.g: await send_mail(body=err.message)\n pass\n\ndef get_reserves():\n return 1_881_938\n\ndef get_details():\n return {'code': 'tr', 'swift': 1283, 'id': 1710}\n\n@agent.safe(retries=3, deps=Deps(reserve=get_reserves, details=get_details))\nasync def add_money(ctx: RunContext[Bank[int]], fund: int):\n if fund <= 5:\n raise ValueError(\"Enter a number greater than 5.\")\n \n ctx.deps.reserve += fund\n bank_details = ctx.deps.get(dict)\n bank_id = bank_details['id']\n tx_hash = hashlib.md5(str(bank_id + ctx.deps.reserve).encode()).hexdigest()\n \n print(f\"Connected bank with ID {bank_details['code'].upper()}{bank_details['swift']}\")\n print(f\"Added ${fund} to current (${ctx.deps.reserve - fund}) reserves.\")\n print(f\"Hash for transaction: {tx_hash}\")\n \n return ctx.deps.reserve\n```\n\n**Run:**\n\n```python\nresult = agent.run_sync(\"Add random money to the bank, pick 4 to 6.\", output_type=int)\nprint(result.output)\n```\n\n**or**\n\n```python\na2a = agent.to_a2a()\n```\n\n```bash\nvenus serve agent:agent a2a --env dev\n```\n\n> \u2705 This example is complete and runnable as-is.\n\n---\n\n### \ud83d\udd39 MCP (Model Context Protocol)\n\n* **Tool integration** from modules via `@tool` / `@mcp_tool`\n* **Dynamic Claude configuration** with `MCP.configure(configure_claude=True)`\n* **Dependency Injection** support for MCP tools\n* **mcp-remote integration** with HTTP/SSE for Claude Desktop\n\n---\n\n### \ud83d\udd39 CLI\n\nVenus provides a **command-line interface (CLI)** to manage and run agents.\nYou can start chats, serve APIs, or launch MCP servers directly from the terminal.\n\n#### Available Commands\n\n* **Chat with an agent**\n\n```bash\nvenus chat module:app\n```\n\n* **Run MCP Server**\n\n```bash\nvenus mcp --path my_tools.py --name \"Venus MCP\" --host 127.0.0.1 --port 8000 --transport <sse|http|stdio> --configure\n```\n\n```bash\nvenus mcp --path my_tools.py --name \"Venus MCP\" --host 127.0.0.1 --port 8000 --transport <sse|http|stdio> --configure --all\n```\n\n* **Serve an Agent as API**\n\n```bash\nvenus serve mymodule:agent --auto --env dev\n```\n\n#### CLI Options\n\n* `chat` \u2192 Start interactive CLI chat with an agent\n* `mcp` \u2192 Run an MCP server with tools from modules\n* `serve` \u2192 Expose your agent via HTTP (FastAPI/Uvicorn)\n* Supports plugins such as **A2A** (`a2a`)\n\n---\n\n## \u26a1 Usage Examples\n\n### Basic Agent\n\n```python\nfrom agent import Venus\n\nagent = Venus(name=\"venus\")\nresponse = agent.run_sync(\"Hello there!\")\nprint(result.output)\n```\n\n### Code-Capable Agent\n\n```python\nfrom venus import VenusCode\nfrom venus.permissions import Permissions\nfrom venus.helpers.io import io_toolset\n\ndef my_permitter(permission: int):\n if not permission & Permissions.EXECUTE and permission & Permissions.READ:\n return [\"read_file_content\"]\n return list(io_toolset.tools.keys())\n\ncode_agent = VenusCode(\n name=\"coder\",\n permission=Permissions.READ_EXECUTE,\n permitter=my_permitter, # do not set a permitter to use default permitter\n)\n```\n\n### Dependency Injection\n```python\n\nfrom venus import Venus\nfrom venus.types import Deps, DepsT, RunContext\n\nimport uuid\nimport time\n\nagent = Venus(deps_type=int)\n\nuuidgen = lambda: uuid.uuid4().hex\ndatagen = lambda: {'foo': [Deps(bar='baz')]}\n\nclass Auth(Deps[DepsT]):\n id: str\n\n@agent.safe(deps=Deps(id=uuidgen, data=datagen))\ndef get_tx(ctx: RunContext[Auth[int]]): # AgentDepsT is int here\n # attribute-style access to deps entity `id`\n txhash = f'%d$%s' % (time.time(), ctx.deps.id)\n # type-based access to deps entity `foo`\n data = ctx.deps.get(dict) # None\n data = ctx.deps.get(list) # [Deps(bar='baz')]\n\n # access main dependency for agent\n agentdeps = ctx.deps.main # int\n \n # type-based access to deps entity `foo`\n # use exact annotation to access it:\n data = ctx.deps.get(list[Deps]) # [Deps(bar='baz')]\n return txhash + data.bar\n```\n\n### Module Tools with Decorators\n\n```python\n# agent.py\nfrom venus import Venus\nagent = Venus(tool_modules='agent_tools')\n```\n\n```python\n# agent_tools.py\nfrom venus.types import Deps\nfrom venus.caching import cached\nfrom venus.decorators import tool, mcp_tool, safe_call, autofix\n\n@tool\n@cached(ttl=240)\ndef get_id():\n return 1\n\n@mcp_tool(deps=Deps(id=get_id))\ndef get_username(deps: Deps):\n return f'@user{deps.id}'\n\n@safe_call\nasync def create_user(username: str):\n return True\n\n@autofix\nasync def risky_function():\n raise Exception('An error occured')\n```\n\n### Agent Tools with Decorators\n\n```python\n# agent.py\nfrom venus import Venus\nfrom venus.types import RunContext\n\nagent = Venus()\n\n@agent.safe_plain\ndef add(x: int, y: int) -> int:\n return x + y\n\n@agent.safe(retries=3)\ndef sub(ctx: RunContext, x: int, y: int) -> int:\n return x - y\n\n@agent.autofix(retries=2, deps=Deps(result=lambda: 20))\ndef risky_function(data: str):\n raise Exception('An error occured')\n```\n\n---\n\n## \ud83d\udee0 Tech Stack\n\n* **Python 3.10+** \u2192 async-first with modern type hints\n* **Based on PydanticAI** \u2192 robust validation & AI agent foundation\n* **ASGI-compatible** \u2192 works with FastAPI, Uvicorn, etc.\n* **MCP Protocol** \u2192 native Model Context Protocol integration\n* **Secure execution** with E2B Sandbox\n* **CLI powered by Click** \u2192 ergonomic, extensible command line\n* **Advanced Caching** \u2192 multiple backend support\n* **Dependency Injection** \u2192 type-safe, dynamic DI system\n* **Error Handling** \u2192 custom recovery & retry strategies\n* **Decorator System** \u2192 tool safety, autofix & error control\n* **HTTP API Generation** \u2192 auto REST endpoint conversion\n\n---\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! \ud83c\udf89\nPlease open an **issue** before submitting a PR to discuss your idea.\n\n---\n\n## \ud83d\udcdc License\n\nLicensed under the **MIT License** \u2013 see the [LICENSE](LICENSE) file for details.",
"bugtrack_url": null,
"license": "MIT",
"summary": "VenusAI is a secure and extensible Agent framework built for modern AI applications.",
"version": "1.28.7",
"project_urls": {
"Documentation": "https://venai.tech/docs",
"Source": "https://github.com/VenusAgent/VenusAI",
"Tracker": "https://github.com/VenusAgent/VenusAI/issues"
},
"split_keywords": [
"agent",
" agentic ai",
" ai",
" ai agent",
" llm",
" pydantic",
" pydantic-ai",
" safety",
" sandbox",
" self-healing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7a49d86c51b482092d2080ed41b6c304289779ed4015fc89d663a37092f175d6",
"md5": "8c56d58fde358abd85a5c95c43c70c24",
"sha256": "66008077e6ab4baa5142d776a08752efe99dc3a27c22e32f6de06ce3260857f9"
},
"downloads": -1,
"filename": "venai-1.28.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8c56d58fde358abd85a5c95c43c70c24",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 46858,
"upload_time": "2025-09-02T21:31:15",
"upload_time_iso_8601": "2025-09-02T21:31:15.375957Z",
"url": "https://files.pythonhosted.org/packages/7a/49/d86c51b482092d2080ed41b6c304289779ed4015fc89d663a37092f175d6/venai-1.28.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "430cfbbec2a8b254e4b4d2eca917042a5250ecb1d524cc27dd361261154685ae",
"md5": "eabb29e352adb440c20db256dab3c9b2",
"sha256": "4059ce399c009e6aa7d5859e4590c1b7057b520a03abee11e66e7854478dfd91"
},
"downloads": -1,
"filename": "venai-1.28.7.tar.gz",
"has_sig": false,
"md5_digest": "eabb29e352adb440c20db256dab3c9b2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 39175,
"upload_time": "2025-09-02T21:31:16",
"upload_time_iso_8601": "2025-09-02T21:31:16.485856Z",
"url": "https://files.pythonhosted.org/packages/43/0c/fbbec2a8b254e4b4d2eca917042a5250ecb1d524cc27dd361261154685ae/venai-1.28.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-02 21:31:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "VenusAgent",
"github_project": "VenusAI",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "mcp",
"specs": []
},
{
"name": "rich",
"specs": []
},
{
"name": "click",
"specs": []
},
{
"name": "tinydb",
"specs": []
},
{
"name": "fasta2a",
"specs": []
},
{
"name": "attrobj",
"specs": []
},
{
"name": "fastapi",
"specs": []
},
{
"name": "logfire",
"specs": []
},
{
"name": "uvicorn",
"specs": []
},
{
"name": "pydantic",
"specs": []
},
{
"name": "aiocache",
"specs": []
},
{
"name": "aiofiles",
"specs": []
},
{
"name": "async-lru",
"specs": []
},
{
"name": "cachetools",
"specs": []
},
{
"name": "pydantic-ai",
"specs": []
},
{
"name": "python-dotenv",
"specs": []
},
{
"name": "mcp-run-python",
"specs": []
},
{
"name": "typing-extensions",
"specs": []
},
{
"name": "e2b-code-interpreter",
"specs": []
}
],
"lcname": "venai"
}
JSON
