# š§ SuluvAI
**Production-ready Deep Agents** with streaming and local storage - built on stable LangGraph.
A powerful, feature-rich LangChain agent framework similar to DeepAgents with enhanced capabilities for real-world applications.
## āØ Features
### Core Features
ā
**Sub-agents** - Delegate tasks to specialized agents
ā
**ReAct Pattern** - Reasoning + Acting with tool use
ā
**TODO Lists** - Plan complex multi-step tasks
ā
**Multi-turn Conversations** - State persists across turns
ā
**Production Ready** - Built on stable LangGraph 0.6.10
### š New in v2.0
š„ **Token Streaming** - Real-time token-by-token output
š„ **Event Streaming** - Stream tool calls, actions, and agent events
š„ **Local File Storage** - Persistent disk-based storage
š„ **Multi-level Folders** - Unlimited nested directory support
š„ **File Search** - Advanced search with glob patterns
š„ **File Operations** - Copy, move, organize files easily
## š¦ Installation
```bash
# Install from PyPI
pip install suluvai
# With OpenAI support
pip install suluvai[openai]
# With Anthropic support
pip install suluvai[anthropic]
# Full installation with all features
pip install suluvai[openai,anthropic,tracing]
```
## š Quick Start
### Basic Agent
```python
from suluvai import create_enhanced_agent, EnhancedAgentConfig
from langchain_openai import ChatOpenAI
# Initialize LLM
llm = ChatOpenAI(model="gpt-4")
# Configure with local storage
config = EnhancedAgentConfig(
storage_mode="local",
storage_path="./my_workspace"
)
# Create agent
agent, storage = create_enhanced_agent(
model=llm,
tools=[],
instructions="You are a helpful assistant.",
config=config
)
# Use it
result = agent.invoke({
"messages": [("user", "Create a report")]
})
print(result["messages"][-1].content)
```
### Streaming Example
```python
import asyncio
from suluvai import stream_agent_events, StreamEventType
async def main():
# Stream tokens in real-time
async for event in stream_agent_events(
agent,
{"messages": [("user", "Tell me a story")]}
):
if event.event_type == StreamEventType.TOKEN:
print(event.data, end="", flush=True)
elif event.event_type == StreamEventType.TOOL_START:
print(f"\nš§ Using: {event.data['tool_name']}")
asyncio.run(main())
```
### Multi-level Folder Example
```python
# Agent automatically organizes files in nested folders
result = agent.invoke({
"messages": [("user", """
Create these files:
- data/sales/2024/q1/january.csv
- data/sales/2024/q2/april.csv
- reports/monthly/summary.md
""")]
})
# List all files
files = storage.list_files()
print(files)
# ['data/sales/2024/q1/january.csv', 'data/sales/2024/q2/april.csv', ...]
# Search for specific files
csv_files = storage.search_files("*.csv")
print(csv_files)
# Get directory tree
tree = storage.get_tree()
print(tree)
```
## š ļø Built-in Tools
### Filesystem Tools (Enhanced in v2.0)
- `write_file(filepath, content)` - Write to files (supports nested paths)
- `read_file(filepath)` - Read file contents
- `list_files(directory, recursive)` - List files in directories
- `delete_file(filepath)` - Delete a file
- `create_directory(dirpath)` - Create nested directories
- `list_directories(directory, recursive)` - List all directories
- `search_files(pattern, directory)` - Search with glob patterns
- `get_file_tree(directory, max_depth)` - Visual directory tree
- `copy_file(src, dst)` - Copy files
- `move_file(src, dst)` - Move/rename files
### TODO Tools
- `write_todos(tasks)` - Create/update TODO list
- `get_todos()` - Get current TODO list
- `mark_todo_done(task_number)` - Mark task as complete
## Advanced Usage
### Multi-turn Conversations with File Persistence
```python
# Turn 1: Fetch data
state = agent.invoke({
"messages": [("user", "Fetch Q1 sales data")],
"files": {},
"todos": [],
"metadata": {}
})
# Files are now in state["files"]["q1_sales.csv"]
# Turn 2: Analyze (agent can access existing files!)
state = agent.invoke({
"messages": state["messages"] + [("user", "Analyze it")],
"files": state["files"], # Pass existing files!
"todos": state["todos"],
"metadata": state["metadata"]
})
```
### Multiple Subagents
```python
# Define specialized subagents
data_fetcher = SubAgent(
name="data_fetcher",
description="Fetches data from databases",
tools=[get_schema, execute_query],
instructions="You fetch data..."
)
analyzer = SubAgent(
name="analyzer",
description="Analyzes data and finds insights",
tools=[analyze, correlate],
instructions="You analyze data..."
)
responder = SubAgent(
name="responder",
description="Formats responses beautifully",
tools=[format_markdown],
instructions="You format responses..."
)
# Create agent with all subagents
agent = create_zita_agent(
model=llm,
tools=[],
subagents=[data_fetcher, analyzer, responder],
instructions="""You coordinate subagents:
1. Use data_fetcher to get data
2. Use analyzer to find insights
3. Use responder to format final answer"""
)
```
## Comparison with DeepAgents
| Feature | DeepAgents | SuluvAI |
|---------|------------|-------------|
| Stability | ā ļø Alpha | ā
Production Ready |
| Token Streaming | ā No | ā
Yes |
| Local Storage | ā No | ā
Yes |
| Multi-level Folders | ā No | ā
Yes |
| Subagents | ā
Yes | ā
Yes |
| Filesystem | ā
Virtual Only | ā
Virtual + Local |
| TODO Lists | ā
Yes | ā
Yes |
| File Search | ā No | ā
Yes |
## API Reference
### `create_enhanced_agent()`
```python
def create_enhanced_agent(
model: Any,
tools: Sequence[BaseTool],
subagents: Optional[List[SubAgent]] = None,
instructions: str = "You are a helpful assistant.",
config: Optional[EnhancedAgentConfig] = None,
state_schema: type = SuluvAIAgentState
) -> Tuple[CompiledGraph, LocalFileStorage]
```
**Parameters:**
- `model`: LLM model (e.g., ChatOpenAI, ChatAnthropic)
- `tools`: List of tools the main agent can use
- `subagents`: List of SubAgent configurations
- `instructions`: System prompt for the main agent
- `config`: EnhancedAgentConfig for storage and streaming settings
- `state_schema`: Custom state schema (default: SuluvAIAgentState)
**Returns:** Tuple of (compiled agent, storage instance)
### `SubAgent`
```python
@dataclass
class SubAgent:
name: str # Unique identifier
description: str # What this subagent does
tools: List[Any] # Tools this subagent can use
instructions: str # System prompt for this subagent
model: Optional[Any] = None # Optional specific model
```
## License
MIT License - Copyright (c) 2025 Zitatech
## Support
Built and maintained by Zitatech for production SAP applications.
Raw data
{
"_id": null,
"home_page": "https://github.com/suluvai/suluvai",
"name": "suluvai",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "langchain, langgraph, agents, ai, llm, streaming, deep-agents, suluvai",
"author": "SuluvAI Team",
"author_email": "SuluvAI Team <contact@suluvai.com>",
"download_url": "https://files.pythonhosted.org/packages/cf/d2/57453cd1ee954bdbec688923807eddbee4cca33e7c33b214d5799fb7eeef/suluvai-2.0.0.tar.gz",
"platform": null,
"description": "# \ud83e\udde0 SuluvAI\r\n\r\n**Production-ready Deep Agents** with streaming and local storage - built on stable LangGraph.\r\n\r\nA powerful, feature-rich LangChain agent framework similar to DeepAgents with enhanced capabilities for real-world applications.\r\n\r\n## \u2728 Features\r\n\r\n### Core Features\r\n\u2705 **Sub-agents** - Delegate tasks to specialized agents \r\n\u2705 **ReAct Pattern** - Reasoning + Acting with tool use \r\n\u2705 **TODO Lists** - Plan complex multi-step tasks \r\n\u2705 **Multi-turn Conversations** - State persists across turns \r\n\u2705 **Production Ready** - Built on stable LangGraph 0.6.10\r\n\r\n### \ud83c\udd95 New in v2.0\r\n\ud83d\udd25 **Token Streaming** - Real-time token-by-token output \r\n\ud83d\udd25 **Event Streaming** - Stream tool calls, actions, and agent events \r\n\ud83d\udd25 **Local File Storage** - Persistent disk-based storage \r\n\ud83d\udd25 **Multi-level Folders** - Unlimited nested directory support \r\n\ud83d\udd25 **File Search** - Advanced search with glob patterns \r\n\ud83d\udd25 **File Operations** - Copy, move, organize files easily \r\n\r\n## \ud83d\udce6 Installation\r\n\r\n```bash\r\n# Install from PyPI\r\npip install suluvai\r\n\r\n# With OpenAI support\r\npip install suluvai[openai]\r\n\r\n# With Anthropic support\r\npip install suluvai[anthropic]\r\n\r\n# Full installation with all features\r\npip install suluvai[openai,anthropic,tracing]\r\n```\r\n\r\n## \ud83d\ude80 Quick Start\r\n\r\n### Basic Agent\r\n\r\n```python\r\nfrom suluvai import create_enhanced_agent, EnhancedAgentConfig\r\nfrom langchain_openai import ChatOpenAI\r\n\r\n# Initialize LLM\r\nllm = ChatOpenAI(model=\"gpt-4\")\r\n\r\n# Configure with local storage\r\nconfig = EnhancedAgentConfig(\r\n storage_mode=\"local\",\r\n storage_path=\"./my_workspace\"\r\n)\r\n\r\n# Create agent\r\nagent, storage = create_enhanced_agent(\r\n model=llm,\r\n tools=[],\r\n instructions=\"You are a helpful assistant.\",\r\n config=config\r\n)\r\n\r\n# Use it\r\nresult = agent.invoke({\r\n \"messages\": [(\"user\", \"Create a report\")]\r\n})\r\n\r\nprint(result[\"messages\"][-1].content)\r\n```\r\n\r\n### Streaming Example\r\n\r\n```python\r\nimport asyncio\r\nfrom suluvai import stream_agent_events, StreamEventType\r\n\r\nasync def main():\r\n # Stream tokens in real-time\r\n async for event in stream_agent_events(\r\n agent,\r\n {\"messages\": [(\"user\", \"Tell me a story\")]}\r\n ):\r\n if event.event_type == StreamEventType.TOKEN:\r\n print(event.data, end=\"\", flush=True)\r\n elif event.event_type == StreamEventType.TOOL_START:\r\n print(f\"\\n\ud83d\udd27 Using: {event.data['tool_name']}\")\r\n\r\nasyncio.run(main())\r\n```\r\n\r\n### Multi-level Folder Example\r\n\r\n```python\r\n# Agent automatically organizes files in nested folders\r\nresult = agent.invoke({\r\n \"messages\": [(\"user\", \"\"\"\r\n Create these files:\r\n - data/sales/2024/q1/january.csv\r\n - data/sales/2024/q2/april.csv\r\n - reports/monthly/summary.md\r\n \"\"\")]\r\n})\r\n\r\n# List all files\r\nfiles = storage.list_files()\r\nprint(files)\r\n# ['data/sales/2024/q1/january.csv', 'data/sales/2024/q2/april.csv', ...]\r\n\r\n# Search for specific files\r\ncsv_files = storage.search_files(\"*.csv\")\r\nprint(csv_files)\r\n\r\n# Get directory tree\r\ntree = storage.get_tree()\r\nprint(tree)\r\n```\r\n\r\n## \ud83d\udee0\ufe0f Built-in Tools\r\n\r\n### Filesystem Tools (Enhanced in v2.0)\r\n- `write_file(filepath, content)` - Write to files (supports nested paths)\r\n- `read_file(filepath)` - Read file contents\r\n- `list_files(directory, recursive)` - List files in directories\r\n- `delete_file(filepath)` - Delete a file\r\n- `create_directory(dirpath)` - Create nested directories\r\n- `list_directories(directory, recursive)` - List all directories\r\n- `search_files(pattern, directory)` - Search with glob patterns\r\n- `get_file_tree(directory, max_depth)` - Visual directory tree\r\n- `copy_file(src, dst)` - Copy files\r\n- `move_file(src, dst)` - Move/rename files\r\n\r\n### TODO Tools\r\n- `write_todos(tasks)` - Create/update TODO list\r\n- `get_todos()` - Get current TODO list\r\n- `mark_todo_done(task_number)` - Mark task as complete\r\n\r\n## Advanced Usage\r\n\r\n### Multi-turn Conversations with File Persistence\r\n\r\n```python\r\n# Turn 1: Fetch data\r\nstate = agent.invoke({\r\n \"messages\": [(\"user\", \"Fetch Q1 sales data\")],\r\n \"files\": {},\r\n \"todos\": [],\r\n \"metadata\": {}\r\n})\r\n\r\n# Files are now in state[\"files\"][\"q1_sales.csv\"]\r\n\r\n# Turn 2: Analyze (agent can access existing files!)\r\nstate = agent.invoke({\r\n \"messages\": state[\"messages\"] + [(\"user\", \"Analyze it\")],\r\n \"files\": state[\"files\"], # Pass existing files!\r\n \"todos\": state[\"todos\"],\r\n \"metadata\": state[\"metadata\"]\r\n})\r\n```\r\n\r\n### Multiple Subagents\r\n\r\n```python\r\n# Define specialized subagents\r\ndata_fetcher = SubAgent(\r\n name=\"data_fetcher\",\r\n description=\"Fetches data from databases\",\r\n tools=[get_schema, execute_query],\r\n instructions=\"You fetch data...\"\r\n)\r\n\r\nanalyzer = SubAgent(\r\n name=\"analyzer\",\r\n description=\"Analyzes data and finds insights\",\r\n tools=[analyze, correlate],\r\n instructions=\"You analyze data...\"\r\n)\r\n\r\nresponder = SubAgent(\r\n name=\"responder\",\r\n description=\"Formats responses beautifully\",\r\n tools=[format_markdown],\r\n instructions=\"You format responses...\"\r\n)\r\n\r\n# Create agent with all subagents\r\nagent = create_zita_agent(\r\n model=llm,\r\n tools=[],\r\n subagents=[data_fetcher, analyzer, responder],\r\n instructions=\"\"\"You coordinate subagents:\r\n 1. Use data_fetcher to get data\r\n 2. Use analyzer to find insights\r\n 3. Use responder to format final answer\"\"\"\r\n)\r\n```\r\n\r\n## Comparison with DeepAgents\r\n\r\n| Feature | DeepAgents | SuluvAI |\r\n|---------|------------|-------------|\r\n| Stability | \u26a0\ufe0f Alpha | \u2705 Production Ready |\r\n| Token Streaming | \u274c No | \u2705 Yes |\r\n| Local Storage | \u274c No | \u2705 Yes |\r\n| Multi-level Folders | \u274c No | \u2705 Yes |\r\n| Subagents | \u2705 Yes | \u2705 Yes |\r\n| Filesystem | \u2705 Virtual Only | \u2705 Virtual + Local |\r\n| TODO Lists | \u2705 Yes | \u2705 Yes |\r\n| File Search | \u274c No | \u2705 Yes |\r\n\r\n## API Reference\r\n\r\n### `create_enhanced_agent()`\r\n\r\n```python\r\ndef create_enhanced_agent(\r\n model: Any,\r\n tools: Sequence[BaseTool],\r\n subagents: Optional[List[SubAgent]] = None,\r\n instructions: str = \"You are a helpful assistant.\",\r\n config: Optional[EnhancedAgentConfig] = None,\r\n state_schema: type = SuluvAIAgentState\r\n) -> Tuple[CompiledGraph, LocalFileStorage]\r\n```\r\n\r\n**Parameters:**\r\n- `model`: LLM model (e.g., ChatOpenAI, ChatAnthropic)\r\n- `tools`: List of tools the main agent can use\r\n- `subagents`: List of SubAgent configurations\r\n- `instructions`: System prompt for the main agent\r\n- `config`: EnhancedAgentConfig for storage and streaming settings\r\n- `state_schema`: Custom state schema (default: SuluvAIAgentState)\r\n\r\n**Returns:** Tuple of (compiled agent, storage instance)\r\n\r\n### `SubAgent`\r\n\r\n```python\r\n@dataclass\r\nclass SubAgent:\r\n name: str # Unique identifier\r\n description: str # What this subagent does\r\n tools: List[Any] # Tools this subagent can use\r\n instructions: str # System prompt for this subagent\r\n model: Optional[Any] = None # Optional specific model\r\n```\r\n\r\n## License\r\n\r\nMIT License - Copyright (c) 2025 Zitatech\r\n\r\n## Support\r\n\r\nBuilt and maintained by Zitatech for production SAP applications.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Production-ready Deep Agents with streaming and local storage support",
"version": "2.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/suluvai/suluvai/issues",
"Documentation": "https://github.com/suluvai/suluvai#readme",
"Homepage": "https://github.com/suluvai/suluvai",
"Repository": "https://github.com/suluvai/suluvai"
},
"split_keywords": [
"langchain",
" langgraph",
" agents",
" ai",
" llm",
" streaming",
" deep-agents",
" suluvai"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "297f1e40ce8c18fa093298c7a76488621fe87efb9c1cd9710a375860c63f69d1",
"md5": "c80f0ff7264e9ec09b19c3a8b526de26",
"sha256": "4c5a348a6cb7d445a66f3aab455d96773e88e727b376712da5b4dc15ebf6f286"
},
"downloads": -1,
"filename": "suluvai-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c80f0ff7264e9ec09b19c3a8b526de26",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 22877,
"upload_time": "2025-10-12T17:56:37",
"upload_time_iso_8601": "2025-10-12T17:56:37.559320Z",
"url": "https://files.pythonhosted.org/packages/29/7f/1e40ce8c18fa093298c7a76488621fe87efb9c1cd9710a375860c63f69d1/suluvai-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cfd257453cd1ee954bdbec688923807eddbee4cca33e7c33b214d5799fb7eeef",
"md5": "b75ce4091f7ec456f6cdd420bebf4f89",
"sha256": "d965036eff22ef30bec292e8cb744777ea2941d7229e15a996fa51fecf49432b"
},
"downloads": -1,
"filename": "suluvai-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "b75ce4091f7ec456f6cdd420bebf4f89",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 33164,
"upload_time": "2025-10-12T17:56:39",
"upload_time_iso_8601": "2025-10-12T17:56:39.124890Z",
"url": "https://files.pythonhosted.org/packages/cf/d2/57453cd1ee954bdbec688923807eddbee4cca33e7c33b214d5799fb7eeef/suluvai-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-12 17:56:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "suluvai",
"github_project": "suluvai",
"github_not_found": true,
"lcname": "suluvai"
}
JSON
