# Arshai
A powerful AI application framework for building complex, intelligent systems with conversational agents, workflow orchestration, and advanced memory management.
```mermaid
graph TD
App([Applications]) --> WF[Workflow System]
WF --> AG[Agent System]
AG --> LLM[LLM Providers]
AG --> MEM[Memory Management]
AG --> TL[Tool System]
WF --> DOC[Document Processing]
DOC --> VDB[Vector Databases]
DOC --> EMB[Embedding Models]
subgraph "Framework Layers"
WF
AG
MEM
TL
DOC
LLM
VDB
EMB
end
```
## Overview
Arshai is designed to empower developers to build sophisticated AI applications by providing a flexible, modular framework based on clean architecture principles. At its core, Arshai follows an interface-first design that enables easy extension, customization, and implementation of complex AI systems.
### Key Features
- **Agent Framework**: Create intelligent conversational agents with advanced memory management
- **Workflow Orchestration**: Design complex multi-agent systems with directed graph workflows
- **Memory Management**: Implement sophisticated conversation memory with multiple storage options
- **Tool Integration**: Extend agent capabilities with custom tools and external integrations
- **LLM Integration**: Connect with leading LLM providers (OpenAI, Azure OpenAI) with consistent APIs
- **RAG Capabilities**: Build powerful retrieval-augmented generation systems with document processing
- **Structured Outputs**: Enforce structured responses with schema validation
- **Streaming Support**: Enable real-time streaming responses throughout the stack
## Architecture
Arshai implements a clean, layered architecture with clear separation of concerns:
```mermaid
classDiagram
class Interfaces {
<<package>>
+IAgent
+IWorkflowOrchestrator
+IMemoryManager
+ITool
+ILLM
+IVectorDBClient
}
class Implementation {
<<package>>
+ConversationAgent
+BaseWorkflowOrchestrator
+MemoryManagerService
+WebSearchTool
+OpenAIClient
+AzureClient
}
class Applications {
<<package>>
+RAG Systems
+Conversational Assistants
+Knowledge Bases
+Multi-agent Systems
}
Interfaces <|-- Implementation
Implementation <-- Applications
```
### Core Components
#### Workflow System
The orchestration layer that manages the flow of execution between agents:
- **Workflow Runner**: Interface for executing workflows
- **Workflow Orchestrator**: Manages node execution and state management
- **Nodes**: Wrappers around agents that adapt them for specific business requirements
- **Workflow State**: Carries data and context between nodes
#### Agent System
The intelligent components that process information and make decisions:
- **Conversational Agent**: Primary agent implementation for handling user interactions
- **Memory Integration**: Contextual awareness through working memory
- **Tool Usage**: Tool calling capabilities for extended functionality
- **Response Structuring**: Schema-based response structuring
#### Memory Management
The system that manages conversation context and knowledge:
- **Memory Manager Service**: Orchestrates different memory types
- **Working Memory**: Stores and retrieves conversation context
- **Multiple Providers**: In-memory and Redis implementations
#### Tool System
Extends agent capabilities with specific functionalities:
- **Web Search Tool**: Retrieve information from the web
- **Knowledge Base Tool**: Query vector databases for relevant information
- **Custom Tool Support**: Framework for developing new tools
#### LLM Integration
Connects to large language models through a unified interface:
- **OpenAI Provider**: Integration with OpenAI models
- **Azure Provider**: Integration with Azure OpenAI service
- **Streaming Support**: Real-time response generation
- **Function Calling**: Tool integration through function definitions
## Getting Started
### Installation
```bash
# Install with pip
pip install arshai
# Or with Poetry (recommended)
poetry add arshai
# With optional dependencies
pip install arshai[all] # Includes redis, milvus, flashrank
```
### Quick Start
Create a conversational agent:
```python
from arshai import Settings, IAgentConfig, IAgentInput
# Initialize settings
settings = Settings()
# Create agent configuration
agent_config = IAgentConfig(
task_context="You are a helpful assistant that specializes in Python programming.",
tools=[]
)
# Create conversation agent
agent = settings.create_agent("conversation", agent_config)
# Process a message
response, usage = agent.process_message(
IAgentInput(
message="How do I use list comprehensions in Python?",
conversation_id="conversation_123"
)
)
print(f"Agent response: {response}")
```
### Building a Workflow
Create a simple workflow with multiple agents:
```python
from arshai import (
Settings,
WorkflowRunner,
BaseWorkflowConfig,
IWorkflowState,
IUserContext
)
# Initialize settings
settings = Settings()
# Define workflow configuration
class QAWorkflow(BaseWorkflowConfig):
def _create_nodes(self):
return {
"query_router": self._create_router_node(),
"research_agent": self._create_research_node(),
"synthesizer": self._create_synthesis_node()
}
def _define_edges(self):
return {
"query_router": {
"research": "research_agent"
},
"research_agent": "synthesizer"
}
def _route_input(self, input_data):
return "research"
# Create workflow runner
workflow_config = QAWorkflow(settings)
workflow_runner = WorkflowRunner(workflow_config)
# Initialize state
user_context = IUserContext(user_id="user123")
initial_state = IWorkflowState(user_context=user_context)
# Run workflow
result = workflow_runner.run({
"message": "What are the environmental impacts of electric vehicles?",
"state": initial_state
})
print(result.get("response", ""))
```
### Using Tools
Extend agents with tool capabilities:
```python
from arshai import Settings, IAgentConfig, IAgentInput
from arshai.tools.web_search_tool import WebSearchTool
# Initialize settings
settings = Settings()
# Create tools
web_search = WebSearchTool(settings)
# Create agent with tools
agent_config = IAgentConfig(
task_context="You are a research assistant that can search the web for information.",
tools=[web_search]
)
agent = settings.create_agent("conversation", agent_config)
# Process a message that might trigger tool usage
response, usage = agent.process_message(
IAgentInput(
message="What are the latest breakthroughs in fusion energy?",
conversation_id="research_123"
)
)
print(f"Agent response with web search: {response}")
```
### Using Plugins
Extend Arshai with custom plugins:
```python
from arshai.extensions import load_plugin
# Load a custom plugin
plugin = load_plugin("my_custom_plugin", config={
"api_key": "your_secret_key"
})
# Use plugin's tools with agents
custom_tool = plugin.get_tool("specialized_tool")
agent_config = IAgentConfig(
task_context="Agent with custom capabilities",
tools=[custom_tool]
)
```
## Examples
Explore the `examples/` directory for complete working examples:
- `basic_usage.py`: Demonstrates core agent functionality
- `simple_workflow.py`: Shows basic workflow construction
- `advanced_workflow.py`: Builds complex multi-agent workflows
- `file_indexing_example.py`: Demonstrates document processing and indexing
- `rag_system_usage.py`: Implements retrieval-augmented generation
- `configuration.py`: Shows configuration management techniques
## Component Documentation
Each major component has its own detailed documentation:
- [Agents System](src/agents/README.md)
- [Memory Management](src/memory/README.md)
- [LLM Integration](src/llms/README.md)
- [Tools System](src/tools/README.md)
- [Workflow System](src/workflows/README.md)
## Real-World Applications
Arshai has been used to build several production systems:
1. **Chetor Assistant**: An AI conversational system with integrated knowledge organization
2. **Petro RAG**: A specialized RAG system for the petroleum industry
## Configuration
Arshai uses a flexible configuration system that can be customized through:
- Environment variables
- Configuration files (YAML, JSON)
- Direct settings injection
Example configuration:
```yaml
# config.yaml
llm:
provider: openai
model: gpt-4
temperature: 0.7
memory:
working_memory:
provider: redis
ttl: 86400
workflows:
debug_mode: true
```
## Extension Points
Arshai v0.2.0 introduces a powerful plugin system for extensibility:
### Plugin System
Create and distribute custom plugins:
```python
from arshai.extensions.base import Plugin, PluginMetadata
from arshai.extensions.hooks import hook, HookType
class MyPlugin(Plugin):
def get_metadata(self):
return PluginMetadata(
name="my_plugin",
version="1.0.0",
author="Your Name",
description="Custom plugin for specialized tasks"
)
def initialize(self):
# Set up your plugin
pass
def shutdown(self):
# Clean up resources
pass
# Add hooks to extend behavior
@hook(HookType.BEFORE_AGENT_PROCESS)
def custom_preprocessing(context):
# Modify agent input before processing
pass
```
### Extension Methods
1. **Plugin System**: Create reusable plugins with tools, hooks, and providers
2. **Custom Agents**: Implement the `IAgent` interface for specialized agents
3. **Custom Tools**: Add new capabilities by implementing the `ITool` interface
4. **Hook System**: Extend behavior without modifying core code
5. **Custom Nodes**: Create specialized workflow nodes for business logic
6. **New LLM Providers**: Add support for new LLM providers by implementing the `ILLM` interface
7. **Custom Memory Providers**: Implement new storage backends with the `IMemoryManager` interface
## Migration from v0.1.x
If you're upgrading from an older version of Arshai:
1. **Read the [Migration Guide](MIGRATION_GUIDE.md)** for detailed instructions
2. **Use the migration script** for automatic import updates:
```bash
python scripts/migrate_imports.py --path /path/to/your/project
```
3. **Enable compatibility mode** for gradual migration:
```python
from arshai.compat import enable_compatibility_mode
enable_compatibility_mode()
```
## What's New in v0.2.0
- 🏗️ **Unified package structure** under `arshai` namespace
- 🔌 **Plugin system** for easy extensibility
- 🪝 **Hook system** for behavior customization
- 📦 **PyPI distribution** for easy installation
- 🔄 **Backward compatibility** layer for smooth migration
- 📚 **Enhanced documentation** and examples
- 🧪 **Improved testing** and CI/CD
## Contributing
Contributions are welcome! Please check out our [Contributing Guidelines](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/nimunzn/arshai",
"name": "arshai",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.11",
"maintainer_email": null,
"keywords": "ai, agents, llm, workflow, rag, conversational-ai, multi-agent, vector-db, embeddings",
"author": "Nima Nazarian",
"author_email": "nimunzn@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/e3/08/2a910870f216fc40d69d65f4273230ac119451656f23465c036eca1c5109/arshai-0.3.7.tar.gz",
"platform": null,
"description": "# Arshai\n\nA powerful AI application framework for building complex, intelligent systems with conversational agents, workflow orchestration, and advanced memory management.\n\n```mermaid\ngraph TD\n App([Applications]) --> WF[Workflow System]\n WF --> AG[Agent System]\n AG --> LLM[LLM Providers]\n AG --> MEM[Memory Management]\n AG --> TL[Tool System]\n WF --> DOC[Document Processing]\n DOC --> VDB[Vector Databases]\n DOC --> EMB[Embedding Models]\n\n subgraph \"Framework Layers\"\n WF\n AG\n MEM\n TL\n DOC\n LLM\n VDB \n EMB\n end\n```\n\n## Overview\n\nArshai is designed to empower developers to build sophisticated AI applications by providing a flexible, modular framework based on clean architecture principles. At its core, Arshai follows an interface-first design that enables easy extension, customization, and implementation of complex AI systems.\n\n### Key Features\n\n- **Agent Framework**: Create intelligent conversational agents with advanced memory management\n- **Workflow Orchestration**: Design complex multi-agent systems with directed graph workflows\n- **Memory Management**: Implement sophisticated conversation memory with multiple storage options\n- **Tool Integration**: Extend agent capabilities with custom tools and external integrations\n- **LLM Integration**: Connect with leading LLM providers (OpenAI, Azure OpenAI) with consistent APIs\n- **RAG Capabilities**: Build powerful retrieval-augmented generation systems with document processing\n- **Structured Outputs**: Enforce structured responses with schema validation\n- **Streaming Support**: Enable real-time streaming responses throughout the stack\n\n## Architecture\n\nArshai implements a clean, layered architecture with clear separation of concerns:\n\n```mermaid\nclassDiagram\n class Interfaces {\n <<package>>\n +IAgent\n +IWorkflowOrchestrator\n +IMemoryManager\n +ITool\n +ILLM\n +IVectorDBClient\n }\n \n class Implementation {\n <<package>>\n +ConversationAgent\n +BaseWorkflowOrchestrator\n +MemoryManagerService\n +WebSearchTool\n +OpenAIClient\n +AzureClient\n }\n \n class Applications {\n <<package>>\n +RAG Systems\n +Conversational Assistants\n +Knowledge Bases\n +Multi-agent Systems\n }\n \n Interfaces <|-- Implementation\n Implementation <-- Applications\n```\n\n### Core Components\n\n#### Workflow System\n\nThe orchestration layer that manages the flow of execution between agents:\n- **Workflow Runner**: Interface for executing workflows\n- **Workflow Orchestrator**: Manages node execution and state management\n- **Nodes**: Wrappers around agents that adapt them for specific business requirements\n- **Workflow State**: Carries data and context between nodes\n\n#### Agent System\n\nThe intelligent components that process information and make decisions:\n- **Conversational Agent**: Primary agent implementation for handling user interactions\n- **Memory Integration**: Contextual awareness through working memory\n- **Tool Usage**: Tool calling capabilities for extended functionality\n- **Response Structuring**: Schema-based response structuring\n\n#### Memory Management\n\nThe system that manages conversation context and knowledge:\n- **Memory Manager Service**: Orchestrates different memory types\n- **Working Memory**: Stores and retrieves conversation context\n- **Multiple Providers**: In-memory and Redis implementations\n\n#### Tool System\n\nExtends agent capabilities with specific functionalities:\n- **Web Search Tool**: Retrieve information from the web\n- **Knowledge Base Tool**: Query vector databases for relevant information\n- **Custom Tool Support**: Framework for developing new tools\n\n#### LLM Integration\n\nConnects to large language models through a unified interface:\n- **OpenAI Provider**: Integration with OpenAI models\n- **Azure Provider**: Integration with Azure OpenAI service\n- **Streaming Support**: Real-time response generation\n- **Function Calling**: Tool integration through function definitions\n\n## Getting Started\n\n### Installation\n\n```bash\n# Install with pip\npip install arshai\n\n# Or with Poetry (recommended)\npoetry add arshai\n\n# With optional dependencies\npip install arshai[all] # Includes redis, milvus, flashrank\n```\n\n### Quick Start\n\nCreate a conversational agent:\n\n```python\nfrom arshai import Settings, IAgentConfig, IAgentInput\n\n# Initialize settings\nsettings = Settings()\n\n# Create agent configuration\nagent_config = IAgentConfig(\n task_context=\"You are a helpful assistant that specializes in Python programming.\",\n tools=[]\n)\n\n# Create conversation agent\nagent = settings.create_agent(\"conversation\", agent_config)\n\n# Process a message\nresponse, usage = agent.process_message(\n IAgentInput(\n message=\"How do I use list comprehensions in Python?\",\n conversation_id=\"conversation_123\"\n )\n)\n\nprint(f\"Agent response: {response}\")\n```\n\n### Building a Workflow\n\nCreate a simple workflow with multiple agents:\n\n```python\nfrom arshai import (\n Settings, \n WorkflowRunner, \n BaseWorkflowConfig,\n IWorkflowState, \n IUserContext\n)\n\n# Initialize settings\nsettings = Settings()\n\n# Define workflow configuration\nclass QAWorkflow(BaseWorkflowConfig):\n def _create_nodes(self):\n return {\n \"query_router\": self._create_router_node(),\n \"research_agent\": self._create_research_node(),\n \"synthesizer\": self._create_synthesis_node()\n }\n \n def _define_edges(self):\n return {\n \"query_router\": {\n \"research\": \"research_agent\"\n },\n \"research_agent\": \"synthesizer\"\n }\n \n def _route_input(self, input_data):\n return \"research\"\n\n# Create workflow runner\nworkflow_config = QAWorkflow(settings)\nworkflow_runner = WorkflowRunner(workflow_config)\n\n# Initialize state\nuser_context = IUserContext(user_id=\"user123\")\ninitial_state = IWorkflowState(user_context=user_context)\n\n# Run workflow\nresult = workflow_runner.run({\n \"message\": \"What are the environmental impacts of electric vehicles?\",\n \"state\": initial_state\n})\n\nprint(result.get(\"response\", \"\"))\n```\n\n### Using Tools\n\nExtend agents with tool capabilities:\n\n```python\nfrom arshai import Settings, IAgentConfig, IAgentInput\nfrom arshai.tools.web_search_tool import WebSearchTool\n\n# Initialize settings\nsettings = Settings()\n\n# Create tools\nweb_search = WebSearchTool(settings)\n\n# Create agent with tools\nagent_config = IAgentConfig(\n task_context=\"You are a research assistant that can search the web for information.\",\n tools=[web_search]\n)\n\nagent = settings.create_agent(\"conversation\", agent_config)\n\n# Process a message that might trigger tool usage\nresponse, usage = agent.process_message(\n IAgentInput(\n message=\"What are the latest breakthroughs in fusion energy?\",\n conversation_id=\"research_123\"\n )\n)\n\nprint(f\"Agent response with web search: {response}\")\n```\n\n### Using Plugins\n\nExtend Arshai with custom plugins:\n\n```python\nfrom arshai.extensions import load_plugin\n\n# Load a custom plugin\nplugin = load_plugin(\"my_custom_plugin\", config={\n \"api_key\": \"your_secret_key\"\n})\n\n# Use plugin's tools with agents\ncustom_tool = plugin.get_tool(\"specialized_tool\")\nagent_config = IAgentConfig(\n task_context=\"Agent with custom capabilities\",\n tools=[custom_tool]\n)\n```\n\n## Examples\n\nExplore the `examples/` directory for complete working examples:\n\n- `basic_usage.py`: Demonstrates core agent functionality\n- `simple_workflow.py`: Shows basic workflow construction\n- `advanced_workflow.py`: Builds complex multi-agent workflows\n- `file_indexing_example.py`: Demonstrates document processing and indexing\n- `rag_system_usage.py`: Implements retrieval-augmented generation\n- `configuration.py`: Shows configuration management techniques\n\n## Component Documentation\n\nEach major component has its own detailed documentation:\n\n- [Agents System](src/agents/README.md)\n- [Memory Management](src/memory/README.md)\n- [LLM Integration](src/llms/README.md)\n- [Tools System](src/tools/README.md)\n- [Workflow System](src/workflows/README.md)\n\n## Real-World Applications\n\nArshai has been used to build several production systems:\n\n1. **Chetor Assistant**: An AI conversational system with integrated knowledge organization\n2. **Petro RAG**: A specialized RAG system for the petroleum industry\n\n## Configuration\n\nArshai uses a flexible configuration system that can be customized through:\n\n- Environment variables\n- Configuration files (YAML, JSON)\n- Direct settings injection\n\nExample configuration:\n\n```yaml\n# config.yaml\nllm:\n provider: openai\n model: gpt-4\n temperature: 0.7\n\nmemory:\n working_memory:\n provider: redis\n ttl: 86400\n\nworkflows:\n debug_mode: true\n```\n\n## Extension Points\n\nArshai v0.2.0 introduces a powerful plugin system for extensibility:\n\n### Plugin System\n\nCreate and distribute custom plugins:\n\n```python\nfrom arshai.extensions.base import Plugin, PluginMetadata\nfrom arshai.extensions.hooks import hook, HookType\n\nclass MyPlugin(Plugin):\n def get_metadata(self):\n return PluginMetadata(\n name=\"my_plugin\",\n version=\"1.0.0\",\n author=\"Your Name\",\n description=\"Custom plugin for specialized tasks\"\n )\n \n def initialize(self):\n # Set up your plugin\n pass\n \n def shutdown(self):\n # Clean up resources\n pass\n\n# Add hooks to extend behavior\n@hook(HookType.BEFORE_AGENT_PROCESS)\ndef custom_preprocessing(context):\n # Modify agent input before processing\n pass\n```\n\n### Extension Methods\n\n1. **Plugin System**: Create reusable plugins with tools, hooks, and providers\n2. **Custom Agents**: Implement the `IAgent` interface for specialized agents\n3. **Custom Tools**: Add new capabilities by implementing the `ITool` interface\n4. **Hook System**: Extend behavior without modifying core code\n5. **Custom Nodes**: Create specialized workflow nodes for business logic\n6. **New LLM Providers**: Add support for new LLM providers by implementing the `ILLM` interface\n7. **Custom Memory Providers**: Implement new storage backends with the `IMemoryManager` interface\n\n## Migration from v0.1.x\n\nIf you're upgrading from an older version of Arshai:\n\n1. **Read the [Migration Guide](MIGRATION_GUIDE.md)** for detailed instructions\n2. **Use the migration script** for automatic import updates:\n ```bash\n python scripts/migrate_imports.py --path /path/to/your/project\n ```\n3. **Enable compatibility mode** for gradual migration:\n ```python\n from arshai.compat import enable_compatibility_mode\n enable_compatibility_mode()\n ```\n\n## What's New in v0.2.0\n\n- \ud83c\udfd7\ufe0f **Unified package structure** under `arshai` namespace\n- \ud83d\udd0c **Plugin system** for easy extensibility\n- \ud83e\ude9d **Hook system** for behavior customization\n- \ud83d\udce6 **PyPI distribution** for easy installation\n- \ud83d\udd04 **Backward compatibility** layer for smooth migration\n- \ud83d\udcda **Enhanced documentation** and examples\n- \ud83e\uddea **Improved testing** and CI/CD\n\n## Contributing\n\nContributions are welcome! Please check out our [Contributing Guidelines](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ",
"bugtrack_url": null,
"license": "MIT",
"summary": "A powerful agent framework for building conversational AI systems",
"version": "0.3.7",
"project_urls": {
"Documentation": "https://arshai.readthedocs.io",
"Homepage": "https://github.com/nimunzn/arshai",
"Repository": "https://github.com/nimunzn/arshai"
},
"split_keywords": [
"ai",
" agents",
" llm",
" workflow",
" rag",
" conversational-ai",
" multi-agent",
" vector-db",
" embeddings"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "da53f83aea75cc3b21b2153041baf646d185cf08987cd3614b68c9f0ad9df2ed",
"md5": "4cc37ba6bbe4461febd6baed50717b12",
"sha256": "c8b253fac8cc83886cb808c15ce162555b94af1ce2ef85c3777ea6a8fbe01a95"
},
"downloads": -1,
"filename": "arshai-0.3.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4cc37ba6bbe4461febd6baed50717b12",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.11",
"size": 363933,
"upload_time": "2025-07-08T22:07:04",
"upload_time_iso_8601": "2025-07-08T22:07:04.253340Z",
"url": "https://files.pythonhosted.org/packages/da/53/f83aea75cc3b21b2153041baf646d185cf08987cd3614b68c9f0ad9df2ed/arshai-0.3.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e3082a910870f216fc40d69d65f4273230ac119451656f23465c036eca1c5109",
"md5": "f030882aab4266b0d3f44f3b73e17350",
"sha256": "c5ec2d8c1261c23e5fb350cd715416e59b0b830036ec62dc1b3872d6179446d8"
},
"downloads": -1,
"filename": "arshai-0.3.7.tar.gz",
"has_sig": false,
"md5_digest": "f030882aab4266b0d3f44f3b73e17350",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.11",
"size": 245218,
"upload_time": "2025-07-08T22:07:05",
"upload_time_iso_8601": "2025-07-08T22:07:05.388178Z",
"url": "https://files.pythonhosted.org/packages/e3/08/2a910870f216fc40d69d65f4273230ac119451656f23465c036eca1c5109/arshai-0.3.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-08 22:07:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nimunzn",
"github_project": "arshai",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "arshai"
}
JSON
