ambivo-agents 1.3.3__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- ambivo_agents/__init__.py +89 -0
- ambivo_agents/agents/__init__.py +19 -0
- ambivo_agents/agents/assistant.py +79 -0
- ambivo_agents/agents/code_executor.py +133 -0
- ambivo_agents/agents/knowledge_base.py +595 -0
- ambivo_agents/agents/media_editor.py +777 -0
- ambivo_agents/agents/simple_web_search.py +404 -0
- ambivo_agents/agents/web_scraper.py +682 -0
- ambivo_agents/agents/web_search.py +660 -0
- ambivo_agents/agents/youtube_download.py +553 -0
- ambivo_agents/cli.py +1871 -0
- ambivo_agents/config/__init__.py +4 -0
- ambivo_agents/config/loader.py +301 -0
- ambivo_agents/core/__init__.py +33 -0
- ambivo_agents/core/base.py +880 -0
- ambivo_agents/core/llm.py +333 -0
- ambivo_agents/core/memory.py +640 -0
- ambivo_agents/executors/__init__.py +8 -0
- ambivo_agents/executors/docker_executor.py +108 -0
- ambivo_agents/executors/media_executor.py +237 -0
- ambivo_agents/executors/youtube_executor.py +404 -0
- ambivo_agents/services/__init__.py +6 -0
- ambivo_agents/services/agent_service.py +590 -0
- ambivo_agents/services/factory.py +366 -0
- ambivo_agents-1.3.3.dist-info/METADATA +773 -0
- ambivo_agents-1.3.3.dist-info/RECORD +30 -0
- ambivo_agents-1.3.3.dist-info/WHEEL +5 -0
- ambivo_agents-1.3.3.dist-info/entry_points.txt +3 -0
- ambivo_agents-1.3.3.dist-info/licenses/LICENSE +21 -0
- ambivo_agents-1.3.3.dist-info/top_level.txt +1 -0
@@ -0,0 +1,773 @@
|
|
1
|
+
Metadata-Version: 2.4
|
2
|
+
Name: ambivo-agents
|
3
|
+
Version: 1.3.3
|
4
|
+
Summary: Multi-Agent AI System for automation
|
5
|
+
Home-page: https://github.com/ambivo-corp/ambivo-agents
|
6
|
+
Author: Hemant Gosain 'Sunny'
|
7
|
+
Author-email: Hemant Gosain 'Sunny' <sgosain@ambivo.com>
|
8
|
+
License: MIT
|
9
|
+
Project-URL: Homepage, https://github.com/ambivo-corp/ambivo-agents
|
10
|
+
Project-URL: Repository, https://github.com/ambivo-corp/ambivo-agents
|
11
|
+
Project-URL: Issues, https://github.com/ambivo-corp/ambivo-agents/issues
|
12
|
+
Project-URL: Documentation, https://github.com/ambivo-corp/ambivo-agents/blob/main/README.md
|
13
|
+
Project-URL: Company, https://www.ambivo.com
|
14
|
+
Classifier: Development Status :: 4 - Beta
|
15
|
+
Classifier: Intended Audience :: Developers
|
16
|
+
Classifier: License :: OSI Approved :: MIT License
|
17
|
+
Classifier: Operating System :: OS Independent
|
18
|
+
Classifier: Programming Language :: Python :: 3
|
19
|
+
Classifier: Programming Language :: Python :: 3.11
|
20
|
+
Classifier: Programming Language :: Python :: 3.12
|
21
|
+
Classifier: Programming Language :: Python :: 3.13
|
22
|
+
Requires-Python: >=3.11
|
23
|
+
Description-Content-Type: text/markdown
|
24
|
+
License-File: LICENSE
|
25
|
+
Requires-Dist: redis>=6.2.0
|
26
|
+
Requires-Dist: redis[asyncio]
|
27
|
+
Requires-Dist: docker>=6.0.0
|
28
|
+
Requires-Dist: asyncio-mqtt>=0.11.0
|
29
|
+
Requires-Dist: cachetools
|
30
|
+
Requires-Dist: lz4
|
31
|
+
Requires-Dist: requests>=2.32.4
|
32
|
+
Requires-Dist: click>=8.2.1
|
33
|
+
Requires-Dist: openai>=1.84.0
|
34
|
+
Requires-Dist: langchain>=0.3.25
|
35
|
+
Requires-Dist: langchain-community>=0.3.24
|
36
|
+
Requires-Dist: langchain-core>=0.3.63
|
37
|
+
Requires-Dist: langchain-openai>=0.3.19
|
38
|
+
Requires-Dist: langchainhub>=0.1.21
|
39
|
+
Requires-Dist: langchain-text-splitters>=0.3.8
|
40
|
+
Requires-Dist: langchain-anthropic>=0.3.15
|
41
|
+
Requires-Dist: langchain-aws
|
42
|
+
Requires-Dist: langchain-voyageai
|
43
|
+
Requires-Dist: huggingface-hub
|
44
|
+
Requires-Dist: llama-index-core
|
45
|
+
Requires-Dist: llama-index-embeddings-langchain
|
46
|
+
Requires-Dist: llama-index-llms-langchain
|
47
|
+
Requires-Dist: llama-index-llms-openai
|
48
|
+
Requires-Dist: llama-index-vector-stores-qdrant
|
49
|
+
Requires-Dist: llama-index-readers-smart-pdf-loader
|
50
|
+
Requires-Dist: pydantic>=2.11.7
|
51
|
+
Requires-Dist: boto3>=1.38.42
|
52
|
+
Requires-Dist: python-dotenv>=1.1.1
|
53
|
+
Requires-Dist: pyyaml>=6.0.2
|
54
|
+
Requires-Dist: psutil>=7.0.0
|
55
|
+
Requires-Dist: qdrant-client
|
56
|
+
Requires-Dist: numexpr
|
57
|
+
Requires-Dist: pytest>=8.4.1
|
58
|
+
Requires-Dist: pytest-asyncio>=1.0.0
|
59
|
+
Requires-Dist: black>=25.1.0
|
60
|
+
Requires-Dist: isort>=6.0.1
|
61
|
+
Requires-Dist: unstructured
|
62
|
+
Requires-Dist: langchain-unstructured
|
63
|
+
Provides-Extra: test
|
64
|
+
Requires-Dist: pytest>=8.4.1; extra == "test"
|
65
|
+
Requires-Dist: pytest-asyncio>=1.0.0; extra == "test"
|
66
|
+
Requires-Dist: pytest-timeout>=2.1.0; extra == "test"
|
67
|
+
Provides-Extra: dev
|
68
|
+
Requires-Dist: pytest>=8.4.1; extra == "dev"
|
69
|
+
Requires-Dist: pytest-asyncio>=1.0.0; extra == "dev"
|
70
|
+
Requires-Dist: black>=25.1.0; extra == "dev"
|
71
|
+
Requires-Dist: isort>=6.0.1; extra == "dev"
|
72
|
+
Requires-Dist: pytest-timeout>=2.1.0; extra == "dev"
|
73
|
+
Provides-Extra: all
|
74
|
+
Requires-Dist: pytest>=8.4.1; extra == "all"
|
75
|
+
Requires-Dist: pytest-asyncio>=1.0.0; extra == "all"
|
76
|
+
Requires-Dist: black>=25.1.0; extra == "all"
|
77
|
+
Requires-Dist: isort>=6.0.1; extra == "all"
|
78
|
+
Requires-Dist: pytest-timeout>=2.1.0; extra == "all"
|
79
|
+
Requires-Dist: beautifulsoup4>=4.13.4; extra == "all"
|
80
|
+
Requires-Dist: playwright>=1.40.0; extra == "all"
|
81
|
+
Requires-Dist: pytubefix>=6.0.0; extra == "all"
|
82
|
+
Requires-Dist: anthropic>=0.55.0; extra == "all"
|
83
|
+
Dynamic: author
|
84
|
+
Dynamic: home-page
|
85
|
+
Dynamic: license-file
|
86
|
+
Dynamic: requires-python
|
87
|
+
|
88
|
+
# Ambivo Agents - Multi-Agent AI System
|
89
|
+
|
90
|
+
A minimalistic toolkit for AI-powered automation including media processing, knowledge base operations, web scraping, YouTube downloads, and more.
|
91
|
+
|
92
|
+
## ⚠️ Alpha Release Disclaimer
|
93
|
+
|
94
|
+
**This library is currently in alpha stage.** While functional, it may contain bugs, undergo breaking changes, and lack complete documentation. **Developers should thoroughly evaluate and test the library before considering it for production use.** Use in production environments is at your own risk.
|
95
|
+
|
96
|
+
For production scenarios, we recommend:
|
97
|
+
- Extensive testing in your specific environment
|
98
|
+
- Implementing proper error handling and monitoring
|
99
|
+
- Having rollback plans in place
|
100
|
+
- Staying updated with releases for critical fixes
|
101
|
+
|
102
|
+
**Development Roadmap**: We are actively working toward a stable 1.0 release. Breaking changes may occur during the alpha phase as we refine the API and improve stability.
|
103
|
+
|
104
|
+
## Table of Contents
|
105
|
+
|
106
|
+
- [Quick Start](#quick-start)
|
107
|
+
- [Agent Creation](#agent-creation)
|
108
|
+
- [Features](#features)
|
109
|
+
- [Available Agents](#available-agents)
|
110
|
+
- [Prerequisites](#prerequisites)
|
111
|
+
- [Installation](#installation)
|
112
|
+
- [Configuration](#configuration)
|
113
|
+
- [Usage Examples](#usage-examples)
|
114
|
+
- [Command Line Interface](#command-line-interface)
|
115
|
+
- [Architecture](#architecture)
|
116
|
+
- [Docker Setup](#docker-setup)
|
117
|
+
- [Troubleshooting](#troubleshooting)
|
118
|
+
- [Security Considerations](#security-considerations)
|
119
|
+
- [Contributing](#contributing)
|
120
|
+
- [License](#license)
|
121
|
+
- [Author](#author)
|
122
|
+
- [Support](#support)
|
123
|
+
|
124
|
+
## Quick Start
|
125
|
+
|
126
|
+
### Python Library Usage (Recommended)
|
127
|
+
|
128
|
+
```python
|
129
|
+
from ambivo_agents import YouTubeDownloadAgent
|
130
|
+
import asyncio
|
131
|
+
|
132
|
+
async def main():
|
133
|
+
# Agent creation with explicit context
|
134
|
+
agent, context = YouTubeDownloadAgent.create(user_id="john")
|
135
|
+
|
136
|
+
print(f"✅ Agent: {agent.agent_id}")
|
137
|
+
print(f"📋 Session: {context.session_id}")
|
138
|
+
print(f"👤 User: {context.user_id}")
|
139
|
+
|
140
|
+
# Download audio from YouTube
|
141
|
+
result = await agent._download_youtube_audio(
|
142
|
+
"https://youtube.com/watch?v=dQw4w9WgXcQ"
|
143
|
+
)
|
144
|
+
|
145
|
+
if result['success']:
|
146
|
+
print(f"✅ Downloaded: {result['filename']}")
|
147
|
+
|
148
|
+
# Cleanup when done
|
149
|
+
await agent.cleanup_session()
|
150
|
+
|
151
|
+
# Run
|
152
|
+
asyncio.run(main())
|
153
|
+
```
|
154
|
+
|
155
|
+
## Agent Creation
|
156
|
+
|
157
|
+
### Direct Agent Creation (Recommended)
|
158
|
+
|
159
|
+
Use the `.create()` method for direct control over specific agent types:
|
160
|
+
|
161
|
+
```python
|
162
|
+
from ambivo_agents import YouTubeDownloadAgent
|
163
|
+
|
164
|
+
# Create agent with explicit context
|
165
|
+
agent, context = YouTubeDownloadAgent.create(user_id="john")
|
166
|
+
print(f"Session: {context.session_id}")
|
167
|
+
print(f"User: {context.user_id}")
|
168
|
+
|
169
|
+
# Use agent directly
|
170
|
+
result = await agent._download_youtube_audio("https://youtube.com/watch?v=example")
|
171
|
+
|
172
|
+
# Cleanup when done
|
173
|
+
await agent.cleanup_session()
|
174
|
+
```
|
175
|
+
|
176
|
+
**When to use `.create()`:**
|
177
|
+
- Direct control over specific agent types
|
178
|
+
- Single-agent applications
|
179
|
+
- Explicit context management
|
180
|
+
- Prototyping and development
|
181
|
+
|
182
|
+
### Service-Based Creation
|
183
|
+
|
184
|
+
Use the service method for multi-agent systems with intelligent routing:
|
185
|
+
|
186
|
+
```python
|
187
|
+
from ambivo_agents.services import create_agent_service
|
188
|
+
|
189
|
+
service = create_agent_service()
|
190
|
+
session_id = service.create_session()
|
191
|
+
|
192
|
+
# Service automatically routes to the appropriate agent
|
193
|
+
result = await service.process_message(
|
194
|
+
message="download audio from youtube.com/watch?v=example", # → YouTubeAgent
|
195
|
+
session_id=session_id,
|
196
|
+
user_id="user123"
|
197
|
+
)
|
198
|
+
```
|
199
|
+
|
200
|
+
**When to use Service:**
|
201
|
+
- Multi-agent applications
|
202
|
+
- Intelligent message routing
|
203
|
+
- Production chatbots/assistants
|
204
|
+
- Unified session management
|
205
|
+
|
206
|
+
**Benefits of this approach:**
|
207
|
+
- ✅ **Explicit Context**: Session IDs, user IDs, and metadata are always visible
|
208
|
+
- ✅ **Better Control**: Full lifecycle management of agents and sessions
|
209
|
+
- ✅ **Built-in Memory**: Conversation history built into every agent
|
210
|
+
|
211
|
+
## Features
|
212
|
+
|
213
|
+
### Core Capabilities
|
214
|
+
- **Multi-Agent Architecture**: Specialized agents for different tasks with intelligent routing
|
215
|
+
- **Docker-Based Execution**: Secure, isolated execution environment for code and media processing
|
216
|
+
- **Redis Memory Management**: Persistent conversation memory with compression and caching
|
217
|
+
- **Multi-Provider LLM Support**: Automatic failover between OpenAI, Anthropic, and AWS Bedrock
|
218
|
+
- **Configuration-Driven**: All features controlled via `agent_config.yaml`
|
219
|
+
|
220
|
+
## Available Agents
|
221
|
+
|
222
|
+
### 🤖 Assistant Agent
|
223
|
+
- General purpose conversational AI
|
224
|
+
- Context-aware responses
|
225
|
+
- Multi-turn conversations
|
226
|
+
|
227
|
+
### 💻 Code Executor Agent
|
228
|
+
- Secure Python and Bash execution in Docker
|
229
|
+
- Isolated environment with resource limits
|
230
|
+
- Real-time output streaming
|
231
|
+
|
232
|
+
### 🔍 Web Search Agent
|
233
|
+
- Multi-provider search (Brave, AVES APIs)
|
234
|
+
- Academic search capabilities
|
235
|
+
- Automatic provider failover
|
236
|
+
|
237
|
+
### 🕷️ Web Scraper Agent
|
238
|
+
- Proxy-enabled scraping (ScraperAPI compatible)
|
239
|
+
- Playwright and requests-based scraping
|
240
|
+
- Batch URL processing with rate limiting
|
241
|
+
|
242
|
+
### 📚 Knowledge Base Agent
|
243
|
+
- Document ingestion (PDF, DOCX, TXT, web URLs)
|
244
|
+
- Vector similarity search with Qdrant
|
245
|
+
- Semantic question answering
|
246
|
+
|
247
|
+
### 🎥 Media Editor Agent
|
248
|
+
- Audio/video processing with FFmpeg
|
249
|
+
- Format conversion, resizing, trimming
|
250
|
+
- Audio extraction and volume adjustment
|
251
|
+
|
252
|
+
### 🎬 YouTube Download Agent
|
253
|
+
- Download videos and audio from YouTube
|
254
|
+
- Docker-based execution with pytubefix
|
255
|
+
- Automatic title sanitization and metadata extraction
|
256
|
+
|
257
|
+
## Prerequisites
|
258
|
+
|
259
|
+
### Required
|
260
|
+
- **Python 3.11+**
|
261
|
+
- **Docker** (for code execution, media processing, YouTube downloads)
|
262
|
+
- **Redis** (Cloud Redis recommended: Redis Cloud)
|
263
|
+
|
264
|
+
### Recommended Cloud Services
|
265
|
+
- **Redis Cloud**
|
266
|
+
- **Qdrant Cloud** for knowledge base operations
|
267
|
+
- **AWS Bedrock**, **OpenAI**, or **Anthropic** for LLM services
|
268
|
+
|
269
|
+
### API Keys (Optional - based on enabled features)
|
270
|
+
- **OpenAI API Key** (for GPT models)
|
271
|
+
- **Anthropic API Key** (for Claude models)
|
272
|
+
- **AWS Credentials** (for Bedrock models)
|
273
|
+
- **Brave Search API Key** (for web search)
|
274
|
+
- **AVES API Key** (for web search)
|
275
|
+
- **ScraperAPI/Proxy credentials** (for web scraping)
|
276
|
+
- **Qdrant Cloud API Key** (for Knowledge Base operations)
|
277
|
+
- **Redis Cloud credentials** (for memory management)
|
278
|
+
|
279
|
+
|
280
|
+
|
281
|
+
## Installation
|
282
|
+
|
283
|
+
### 1. Install Dependencies
|
284
|
+
```bash
|
285
|
+
# Core dependencies
|
286
|
+
pip install redis python-dotenv pyyaml click
|
287
|
+
|
288
|
+
# LLM providers (choose based on your needs)
|
289
|
+
pip install openai anthropic boto3 langchain-openai langchain-anthropic langchain-aws
|
290
|
+
|
291
|
+
# Knowledge base (if using)
|
292
|
+
pip install qdrant-client llama-index langchain-unstructured
|
293
|
+
|
294
|
+
# Web capabilities (if using)
|
295
|
+
pip install requests beautifulsoup4 playwright
|
296
|
+
|
297
|
+
# Media processing (if using)
|
298
|
+
pip install docker
|
299
|
+
|
300
|
+
# YouTube downloads (if using)
|
301
|
+
pip install pytubefix pydantic
|
302
|
+
|
303
|
+
# Optional: Install all at once
|
304
|
+
pip install -r requirements.txt
|
305
|
+
```
|
306
|
+
|
307
|
+
### 2. Setup Docker Images
|
308
|
+
```bash
|
309
|
+
# Pull the multi-purpose container image
|
310
|
+
docker pull sgosain/amb-ubuntu-python-public-pod
|
311
|
+
```
|
312
|
+
|
313
|
+
### 3. Setup Redis
|
314
|
+
|
315
|
+
**Recommended: Cloud Redis **
|
316
|
+
```yaml
|
317
|
+
# In agent_config.yaml
|
318
|
+
redis:
|
319
|
+
host: "your-redis-cloud-endpoint.redis.cloud"
|
320
|
+
port: 6379
|
321
|
+
password: "your-redis-password"
|
322
|
+
```
|
323
|
+
|
324
|
+
**Alternative: Local Redis**
|
325
|
+
```bash
|
326
|
+
# Using Docker (for development)
|
327
|
+
docker run -d --name redis -p 6379:6379 redis:latest
|
328
|
+
|
329
|
+
# Or install locally
|
330
|
+
# sudo apt-get install redis-server # Ubuntu/Debian
|
331
|
+
# brew install redis # macOS
|
332
|
+
```
|
333
|
+
|
334
|
+
## Configuration
|
335
|
+
|
336
|
+
Create `agent_config.yaml` in your project root:
|
337
|
+
|
338
|
+
```yaml
|
339
|
+
# Redis Configuration (Required)
|
340
|
+
redis:
|
341
|
+
host: "your-redis-cloud-endpoint.redis.cloud" # Recommended: Cloud Redis
|
342
|
+
port: 6379
|
343
|
+
db: 0
|
344
|
+
password: "your-redis-password" # Required for cloud
|
345
|
+
# Alternative local: host: "localhost", password: null
|
346
|
+
|
347
|
+
# LLM Configuration (Required - at least one provider)
|
348
|
+
llm:
|
349
|
+
preferred_provider: "openai" # openai, anthropic, or bedrock
|
350
|
+
temperature: 0.7
|
351
|
+
|
352
|
+
# Provider API Keys
|
353
|
+
openai_api_key: "your-openai-key"
|
354
|
+
anthropic_api_key: "your-anthropic-key"
|
355
|
+
|
356
|
+
# AWS Bedrock (optional)
|
357
|
+
aws_access_key_id: "your-aws-key"
|
358
|
+
aws_secret_access_key: "your-aws-secret"
|
359
|
+
aws_region: "us-east-1"
|
360
|
+
|
361
|
+
# Agent Capabilities (Enable/disable features)
|
362
|
+
agent_capabilities:
|
363
|
+
enable_knowledge_base: true
|
364
|
+
enable_web_search: true
|
365
|
+
enable_code_execution: true
|
366
|
+
enable_file_processing: true
|
367
|
+
enable_web_ingestion: true
|
368
|
+
enable_api_calls: true
|
369
|
+
enable_web_scraping: true
|
370
|
+
enable_proxy_mode: true
|
371
|
+
enable_media_editor: true
|
372
|
+
enable_youtube_download: true
|
373
|
+
|
374
|
+
# Web Search Configuration (if enabled)
|
375
|
+
web_search:
|
376
|
+
brave_api_key: "your-brave-api-key"
|
377
|
+
avesapi_api_key: "your-aves-api-key"
|
378
|
+
|
379
|
+
# Web Scraping Configuration (if enabled)
|
380
|
+
web_scraping:
|
381
|
+
proxy_enabled: true
|
382
|
+
proxy_config:
|
383
|
+
http_proxy: "http://scraperapi:your-key@proxy-server.scraperapi.com:8001"
|
384
|
+
default_headers:
|
385
|
+
User-Agent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
|
386
|
+
timeout: 60
|
387
|
+
max_links_per_page: 100
|
388
|
+
|
389
|
+
# Knowledge Base Configuration (if enabled)
|
390
|
+
knowledge_base:
|
391
|
+
qdrant_url: "https://your-cluster.qdrant.tech" # Recommended: Qdrant Cloud
|
392
|
+
qdrant_api_key: "your-qdrant-api-key" # Required for cloud
|
393
|
+
# Alternative local: "http://localhost:6333"
|
394
|
+
chunk_size: 1024
|
395
|
+
chunk_overlap: 20
|
396
|
+
similarity_top_k: 5
|
397
|
+
|
398
|
+
# Media Editor Configuration (if enabled)
|
399
|
+
media_editor:
|
400
|
+
docker_image: "sgosain/amb-ubuntu-python-public-pod"
|
401
|
+
input_dir: "./media_input"
|
402
|
+
output_dir: "./media_output"
|
403
|
+
timeout: 300
|
404
|
+
memory_limit: "2g"
|
405
|
+
|
406
|
+
# YouTube Download Configuration (if enabled)
|
407
|
+
youtube_download:
|
408
|
+
docker_image: "sgosain/amb-ubuntu-python-public-pod"
|
409
|
+
download_dir: "./youtube_downloads"
|
410
|
+
timeout: 600
|
411
|
+
memory_limit: "1g"
|
412
|
+
default_audio_only: true
|
413
|
+
|
414
|
+
# Docker Configuration
|
415
|
+
docker:
|
416
|
+
timeout: 60
|
417
|
+
memory_limit: "512m"
|
418
|
+
images: ["sgosain/amb-ubuntu-python-public-pod"]
|
419
|
+
|
420
|
+
# Service Configuration
|
421
|
+
service:
|
422
|
+
max_sessions: 100
|
423
|
+
session_timeout: 3600
|
424
|
+
log_level: "INFO"
|
425
|
+
log_to_file: false
|
426
|
+
|
427
|
+
# Memory Management
|
428
|
+
memory_management:
|
429
|
+
compression:
|
430
|
+
enabled: true
|
431
|
+
algorithm: "lz4"
|
432
|
+
cache:
|
433
|
+
enabled: true
|
434
|
+
max_size: 1000
|
435
|
+
ttl_seconds: 300
|
436
|
+
```
|
437
|
+
|
438
|
+
## Project Structure
|
439
|
+
|
440
|
+
```
|
441
|
+
ambivo_agents/
|
442
|
+
├── agents/ # Agent implementations
|
443
|
+
│ ├── assistant.py
|
444
|
+
│ ├── code_executor.py
|
445
|
+
│ ├── knowledge_base.py
|
446
|
+
│ ├── media_editor.py
|
447
|
+
│ ├── simple_web_search.py
|
448
|
+
│ ├── web_scraper.py
|
449
|
+
│ ├── web_search.py
|
450
|
+
│ └── youtube_download.py
|
451
|
+
├── config/ # Configuration management
|
452
|
+
├── core/ # Core functionality
|
453
|
+
│ ├── base.py
|
454
|
+
│ ├── llm.py
|
455
|
+
│ └── memory.py
|
456
|
+
├── executors/ # Execution environments
|
457
|
+
├── services/ # Service layer
|
458
|
+
├── __init__.py # Package initialization
|
459
|
+
└── cli.py # Command line interface
|
460
|
+
```
|
461
|
+
|
462
|
+
## Usage Examples
|
463
|
+
|
464
|
+
### 🎬 YouTube Downloads
|
465
|
+
```python
|
466
|
+
from ambivo_agents import YouTubeDownloadAgent
|
467
|
+
|
468
|
+
async def download_youtube():
|
469
|
+
agent, context = YouTubeDownloadAgent.create(user_id="media_user")
|
470
|
+
|
471
|
+
# Download audio
|
472
|
+
result = await agent._download_youtube_audio(
|
473
|
+
"https://youtube.com/watch?v=example"
|
474
|
+
)
|
475
|
+
|
476
|
+
if result['success']:
|
477
|
+
print(f"✅ Audio downloaded: {result['filename']}")
|
478
|
+
print(f"📍 Path: {result['file_path']}")
|
479
|
+
print(f"📊 Size: {result['file_size_bytes']:,} bytes")
|
480
|
+
|
481
|
+
# Get video info
|
482
|
+
info = await agent._get_youtube_info(
|
483
|
+
"https://youtube.com/watch?v=example"
|
484
|
+
)
|
485
|
+
|
486
|
+
if info['success']:
|
487
|
+
video_info = info['video_info']
|
488
|
+
print(f"📹 Title: {video_info['title']}")
|
489
|
+
print(f"⏱️ Duration: {video_info['duration']} seconds")
|
490
|
+
|
491
|
+
await agent.cleanup_session()
|
492
|
+
```
|
493
|
+
|
494
|
+
### 📚 Knowledge Base Operations
|
495
|
+
```python
|
496
|
+
from ambivo_agents import KnowledgeBaseAgent
|
497
|
+
|
498
|
+
async def knowledge_base_demo():
|
499
|
+
agent, context = KnowledgeBaseAgent.create(
|
500
|
+
user_id="kb_user",
|
501
|
+
session_metadata={"project": "company_docs"}
|
502
|
+
)
|
503
|
+
|
504
|
+
print(f"Session: {context.session_id}")
|
505
|
+
|
506
|
+
# Ingest document
|
507
|
+
result = await agent._ingest_document(
|
508
|
+
kb_name="company_kb",
|
509
|
+
doc_path="/path/to/document.pdf",
|
510
|
+
custom_meta={"department": "HR", "type": "policy"}
|
511
|
+
)
|
512
|
+
|
513
|
+
if result['success']:
|
514
|
+
print("✅ Document ingested")
|
515
|
+
|
516
|
+
# Query the knowledge base
|
517
|
+
answer = await agent._query_knowledge_base(
|
518
|
+
kb_name="company_kb",
|
519
|
+
query="What is the remote work policy?"
|
520
|
+
)
|
521
|
+
|
522
|
+
if answer['success']:
|
523
|
+
print(f"📝 Answer: {answer['answer']}")
|
524
|
+
|
525
|
+
# View conversation history
|
526
|
+
history = await agent.get_conversation_history(limit=5)
|
527
|
+
print(f"💬 Messages in session: {len(history)}")
|
528
|
+
|
529
|
+
await agent.cleanup_session()
|
530
|
+
```
|
531
|
+
|
532
|
+
### 🔍 Web Search
|
533
|
+
```python
|
534
|
+
from ambivo_agents import WebSearchAgent
|
535
|
+
|
536
|
+
async def search_demo():
|
537
|
+
agent, context = WebSearchAgent.create(user_id="search_user")
|
538
|
+
|
539
|
+
# Search the web
|
540
|
+
results = await agent._search_web(
|
541
|
+
"artificial intelligence trends 2024",
|
542
|
+
max_results=5
|
543
|
+
)
|
544
|
+
|
545
|
+
if results['success']:
|
546
|
+
print(f"🔍 Found {len(results['results'])} results")
|
547
|
+
|
548
|
+
for i, result in enumerate(results['results'], 1):
|
549
|
+
print(f"{i}. {result['title']}")
|
550
|
+
print(f" {result['url']}")
|
551
|
+
print(f" {result['snippet'][:100]}...")
|
552
|
+
|
553
|
+
await agent.cleanup_session()
|
554
|
+
```
|
555
|
+
|
556
|
+
### 🎵 Media Processing
|
557
|
+
```python
|
558
|
+
from ambivo_agents import MediaEditorAgent
|
559
|
+
|
560
|
+
async def media_demo():
|
561
|
+
agent, context = MediaEditorAgent.create(user_id="media_user")
|
562
|
+
|
563
|
+
# Extract audio from video
|
564
|
+
result = await agent._extract_audio_from_video(
|
565
|
+
input_video="/path/to/video.mp4",
|
566
|
+
output_format="mp3",
|
567
|
+
audio_quality="high"
|
568
|
+
)
|
569
|
+
|
570
|
+
if result['success']:
|
571
|
+
print(f"✅ Audio extracted: {result['output_file']}")
|
572
|
+
|
573
|
+
await agent.cleanup_session()
|
574
|
+
```
|
575
|
+
|
576
|
+
### Context Manager Pattern (Auto-Cleanup)
|
577
|
+
|
578
|
+
```python
|
579
|
+
from ambivo_agents import KnowledgeBaseAgent, AgentSession
|
580
|
+
import asyncio
|
581
|
+
|
582
|
+
async def main():
|
583
|
+
# Auto-cleanup with context manager
|
584
|
+
async with AgentSession(KnowledgeBaseAgent, user_id="sarah") as agent:
|
585
|
+
print(f"Session: {agent.context.session_id}")
|
586
|
+
|
587
|
+
# Use agent - cleanup happens automatically
|
588
|
+
result = await agent._query_knowledge_base(
|
589
|
+
kb_name="company_docs",
|
590
|
+
query="What is our return policy?"
|
591
|
+
)
|
592
|
+
|
593
|
+
print(result['answer'])
|
594
|
+
# Agent automatically cleaned up here
|
595
|
+
|
596
|
+
asyncio.run(main())
|
597
|
+
```
|
598
|
+
|
599
|
+
## Command Line Interface
|
600
|
+
|
601
|
+
```bash
|
602
|
+
# Install the CLI
|
603
|
+
pip install ambivo-agents
|
604
|
+
|
605
|
+
# Health check
|
606
|
+
ambivo-agents health
|
607
|
+
|
608
|
+
# Chat mode with smart routing
|
609
|
+
ambivo-agents
|
610
|
+
|
611
|
+
# Direct YouTube download
|
612
|
+
ambivo-agents youtube download "https://youtube.com/watch?v=example"
|
613
|
+
|
614
|
+
# Smart message routing
|
615
|
+
ambivo-agents chat "download audio from https://youtube.com/watch?v=example"
|
616
|
+
ambivo-agents chat "search for latest AI trends"
|
617
|
+
ambivo-agents chat "extract audio from video.mp4"
|
618
|
+
```
|
619
|
+
|
620
|
+
### Command Line Examples
|
621
|
+
```bash
|
622
|
+
# YouTube Downloads
|
623
|
+
ambivo-agents youtube download "https://youtube.com/watch?v=example" --audio-only
|
624
|
+
ambivo-agents youtube download "https://youtube.com/watch?v=example" --video
|
625
|
+
ambivo-agents youtube info "https://youtube.com/watch?v=example"
|
626
|
+
|
627
|
+
# Smart Chat (automatically routes to appropriate agent)
|
628
|
+
ambivo-agents chat "download audio from https://youtube.com/watch?v=example"
|
629
|
+
ambivo-agents chat "search for latest AI developments"
|
630
|
+
ambivo-agents chat "extract audio from video.mp4 as high quality mp3"
|
631
|
+
|
632
|
+
# Interactive mode with smart routing
|
633
|
+
ambivo-agents interactive
|
634
|
+
```
|
635
|
+
|
636
|
+
## Architecture
|
637
|
+
|
638
|
+
### Agent Capabilities
|
639
|
+
Each agent provides specialized functionality:
|
640
|
+
|
641
|
+
- **YouTube Download Agent** → Video/audio downloads with pytubefix
|
642
|
+
- **Media Editor Agent** → FFmpeg-based processing
|
643
|
+
- **Knowledge Base Agent** → Qdrant vector search
|
644
|
+
- **Web Search Agent** → Multi-provider search
|
645
|
+
- **Web Scraper Agent** → Proxy-enabled scraping
|
646
|
+
- **Code Executor Agent** → Docker-based execution
|
647
|
+
|
648
|
+
### Memory System
|
649
|
+
- **Redis-based persistence** with compression and caching
|
650
|
+
- **Built-in conversation history** for every agent
|
651
|
+
- **Session-aware context** with automatic cleanup
|
652
|
+
- **Multi-session support** with isolation
|
653
|
+
|
654
|
+
### LLM Provider Management
|
655
|
+
- **Automatic failover** between OpenAI, Anthropic, AWS Bedrock
|
656
|
+
- **Rate limiting** and error handling
|
657
|
+
- **Provider rotation** based on availability and performance
|
658
|
+
|
659
|
+
## Docker Setup
|
660
|
+
|
661
|
+
### Custom Docker Image
|
662
|
+
If you need additional dependencies, extend the base image:
|
663
|
+
|
664
|
+
```dockerfile
|
665
|
+
FROM sgosain/amb-ubuntu-python-public-pod
|
666
|
+
|
667
|
+
# Install additional packages
|
668
|
+
RUN pip install your-additional-packages
|
669
|
+
|
670
|
+
# Add custom scripts
|
671
|
+
COPY your-scripts/ /opt/scripts/
|
672
|
+
```
|
673
|
+
|
674
|
+
### Volume Mounting
|
675
|
+
The agents automatically handle volume mounting for:
|
676
|
+
- Media input/output directories
|
677
|
+
- YouTube download directories
|
678
|
+
- Code execution workspaces
|
679
|
+
|
680
|
+
## Troubleshooting
|
681
|
+
|
682
|
+
### Common Issues
|
683
|
+
|
684
|
+
1. **Redis Connection Failed**
|
685
|
+
```bash
|
686
|
+
# For cloud Redis: Check connection details in agent_config.yaml
|
687
|
+
# For local Redis: Check if running
|
688
|
+
redis-cli ping # Should return "PONG"
|
689
|
+
```
|
690
|
+
|
691
|
+
2. **Docker Not Available**
|
692
|
+
```bash
|
693
|
+
# Check Docker is running
|
694
|
+
docker ps
|
695
|
+
# Install if missing: https://docs.docker.com/get-docker/
|
696
|
+
```
|
697
|
+
|
698
|
+
3. **Agent Creation Errors**
|
699
|
+
```python
|
700
|
+
# Check agent can be created
|
701
|
+
from ambivo_agents import YouTubeDownloadAgent
|
702
|
+
try:
|
703
|
+
agent, context = YouTubeDownloadAgent.create(user_id="test")
|
704
|
+
print(f"✅ Success: {context.session_id}")
|
705
|
+
await agent.cleanup_session()
|
706
|
+
except Exception as e:
|
707
|
+
print(f"❌ Error: {e}")
|
708
|
+
```
|
709
|
+
|
710
|
+
4. **Import Errors**
|
711
|
+
```bash
|
712
|
+
# Ensure clean imports work
|
713
|
+
python -c "from ambivo_agents import YouTubeDownloadAgent; print('✅ Import success')"
|
714
|
+
```
|
715
|
+
|
716
|
+
### Debug Mode
|
717
|
+
Enable verbose logging:
|
718
|
+
```yaml
|
719
|
+
service:
|
720
|
+
log_level: "DEBUG"
|
721
|
+
log_to_file: true
|
722
|
+
```
|
723
|
+
|
724
|
+
## Security Considerations
|
725
|
+
|
726
|
+
- **Docker Isolation**: All code execution happens in isolated containers
|
727
|
+
- **Network Restrictions**: Containers run with `network_disabled=True` by default
|
728
|
+
- **Resource Limits**: Memory and CPU limits prevent resource exhaustion
|
729
|
+
- **API Key Management**: Store sensitive keys in environment variables
|
730
|
+
- **Input Sanitization**: All user inputs are validated and sanitized
|
731
|
+
- **Session Isolation**: Each agent session is completely isolated
|
732
|
+
|
733
|
+
## Contributing
|
734
|
+
|
735
|
+
We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.
|
736
|
+
|
737
|
+
### Development Setup
|
738
|
+
```bash
|
739
|
+
# Clone repository
|
740
|
+
git clone https://github.com/ambivo-corp/ambivo-agents.git
|
741
|
+
cd ambivo-agents
|
742
|
+
|
743
|
+
# Install in development mode
|
744
|
+
pip install -e .
|
745
|
+
|
746
|
+
# Run examples
|
747
|
+
python examples/<example.py>
|
748
|
+
```
|
749
|
+
|
750
|
+
## License
|
751
|
+
|
752
|
+
MIT License - see [LICENSE](LICENSE) file for details.
|
753
|
+
|
754
|
+
**Alpha Release**: This software is provided "as is" without warranty. Users assume all risks associated with its use, particularly in production environments.
|
755
|
+
|
756
|
+
## Author
|
757
|
+
|
758
|
+
**Hemant Gosain 'Sunny'**
|
759
|
+
- Company: [Ambivo](https://www.ambivo.com)
|
760
|
+
- Email: info@ambivo.com
|
761
|
+
|
762
|
+
## Support
|
763
|
+
|
764
|
+
- 📧 Email: info@ambivo.com
|
765
|
+
- 🌐 Website: https://www.ambivo.com
|
766
|
+
- 📖 Documentation: [Coming Soon]
|
767
|
+
- 🐛 Issues: [GitHub Issues](https://github.com/ambivo-corp/ambivo-agents/issues)
|
768
|
+
|
769
|
+
**Alpha Support**: As an alpha release, support is provided on a best-effort basis. Response times may vary, and some issues may require significant investigation.
|
770
|
+
|
771
|
+
---
|
772
|
+
|
773
|
+
*Developed by the Ambivo team.*
|