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.
@@ -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.*