Metadata-Version: 2.2
Name: ambivo-agents
Version: 2.0.0
Summary: Lightweight AI agent framework for research synthesis
Author-email: Hemant Gosain 'Sunny' <info@ambivo.com>
License: MIT
Project-URL: Homepage, https://github.com/ambivo-corp/ambivo-agents
Project-URL: Repository, https://github.com/ambivo-corp/ambivo-agents
Project-URL: Issues, https://github.com/ambivo-corp/ambivo-agents/issues
Project-URL: Documentation, https://github.com/ambivo-corp/ambivo-agents/blob/main/README.md
Project-URL: Company, https://www.ambivo.com
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Framework :: AsyncIO
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests<3,>=2.32
Requires-Dist: click<9,>=8.2
Requires-Dist: cachetools<7,>=6.1
Requires-Dist: psutil<8,>=7.0
Requires-Dist: openai<2,>=1.84
Requires-Dist: anthropic<1,>=0.55
Requires-Dist: httpx>=0.28.1
Requires-Dist: beautifulsoup4>=4.13.4
Requires-Dist: pydantic<3,>=2.11
Requires-Dist: python-dotenv<2,>=1.1
Requires-Dist: pyyaml<7,>=6.0
Provides-Extra: redis
Requires-Dist: redis<7,>=6.2.0; extra == "redis"
Requires-Dist: redis[asyncio]; extra == "redis"
Requires-Dist: lz4<5,>=4.4; extra == "redis"
Provides-Extra: aws
Requires-Dist: boto3<2,>=1.38; extra == "aws"
Provides-Extra: voyageai
Requires-Dist: langchain-core<0.4,>=0.3.63; extra == "voyageai"
Requires-Dist: langchain-voyageai<0.2,>=0.1.6; extra == "voyageai"
Provides-Extra: knowledge
Requires-Dist: qdrant-client<2,>=1.16; extra == "knowledge"
Requires-Dist: langchain<0.4,>=0.3.25; extra == "knowledge"
Requires-Dist: langchain-core<0.4,>=0.3.63; extra == "knowledge"
Requires-Dist: langchain-openai<0.4,>=0.3.19; extra == "knowledge"
Requires-Dist: langchain-aws<0.3,>=0.2.24; extra == "knowledge"
Requires-Dist: langchain-unstructured~=0.1.6; extra == "knowledge"
Requires-Dist: unstructured~=0.17; extra == "knowledge"
Requires-Dist: llama-index-core<0.13,>=0.12.43; extra == "knowledge"
Requires-Dist: llama-index-embeddings-langchain<0.4,>=0.3; extra == "knowledge"
Requires-Dist: llama-index-llms-langchain<0.7,>=0.6; extra == "knowledge"
Requires-Dist: llama-index-llms-openai<0.5,>=0.4; extra == "knowledge"
Requires-Dist: llama-index-vector-stores-qdrant<0.7,>=0.6; extra == "knowledge"
Requires-Dist: llama-index-readers-smart-pdf-loader<0.4,>=0.3; extra == "knowledge"
Provides-Extra: documents
Requires-Dist: pypdf>=5.6.1; extra == "documents"
Requires-Dist: python-docx>=1.2.0; extra == "documents"
Requires-Dist: python-pptx>=1.0.2; extra == "documents"
Requires-Dist: pillow>=11.2.1; extra == "documents"
Requires-Dist: pytesseract>=0.3.13; extra == "documents"
Provides-Extra: async
Requires-Dist: aiohttp>=3.8.0; extra == "async"
Requires-Dist: aiofiles>=22.1.0; extra == "async"
Requires-Dist: aiosqlite>=0.19.0; extra == "async"
Provides-Extra: test
Requires-Dist: pytest>=8.4.1; extra == "test"
Requires-Dist: pytest-asyncio>=1.0.0; extra == "test"
Requires-Dist: pytest-timeout>=2.1.0; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest>=8.4.1; extra == "dev"
Requires-Dist: pytest-asyncio>=1.0.0; extra == "dev"
Requires-Dist: black>=25.1.0; extra == "dev"
Requires-Dist: isort>=6.0.1; extra == "dev"
Requires-Dist: pytest-timeout>=2.1.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Provides-Extra: full
Requires-Dist: ambivo-agents[async,aws,documents,redis]; extra == "full"
Provides-Extra: all
Requires-Dist: ambivo-agents[dev,full]; extra == "all"
Provides-Extra: all-ml
Requires-Dist: ambivo-agents[all,knowledge,voyageai]; extra == "all-ml"

# Ambivo Agents v2.0.0

A lightweight AI agent framework for research synthesis with quality-gated multi-source knowledge gathering.

## What's Different

v2.0.0 is a focused rewrite. We removed 7 commodity agents and their heavy dependencies (Docker, Redis, Playwright) to focus on what's actually unique: **quality-gated knowledge synthesis** — iteratively consulting multiple sources, assessing response quality, and refining until a threshold is met.

| Metric | v1.x | v2.0.0 |
|--------|------|--------|
| Agents | 14 | 7 |
| Core deps | 12 (redis, docker, lz4...) | 9 (httpx, bs4, openai...) |
| Requires Redis | Yes | No (in-memory default) |
| Requires Docker | Yes (5 agents) | No |
| Requires Playwright | Yes (400MB browsers) | No (API-based scraping) |

## Quick Start

```bash
pip install ambivo-agents
```

```python
from ambivo_agents import AssistantAgent

agent = AssistantAgent.create_simple(user_id="demo")
response = await agent.chat("What is quantum computing?")
print(response)
await agent.cleanup_session()
```

No Redis. No Docker. No config files. Just works.

## Available Agents

| Agent | Purpose |
|-------|---------|
| **AssistantAgent** | General conversation and explanations |
| **ModeratorAgent** | Intelligent query routing to specialized agents |
| **KnowledgeSynthesisAgent** | Multi-source research with quality assessment loops |
| **WebSearchAgent** | Web search via Brave/AVES APIs |
| **WebScraperAgent** | Content extraction via Jina Reader/Firecrawl/requests+bs4 |
| **KnowledgeBaseAgent** | Document ingestion and semantic search (Qdrant + LlamaIndex) |
| **GatherAgent** | Conversational form filling with conditional logic |

## Core Differentiator: Quality-Gated Synthesis

```python
from ambivo_agents import KnowledgeSynthesisAgent

agent = KnowledgeSynthesisAgent.create_simple(user_id="researcher")
# Automatically: searches web -> scrapes pages -> queries KB -> assesses quality -> refines
response = await agent.chat("What are the latest advances in quantum error correction?")
```

The synthesis pipeline:
1. Analyzes query to select search strategy
2. Searches web (Brave API) + scrapes relevant pages (Jina Reader API)
3. Queries knowledge base if available
4. Assesses response quality (POOR/FAIR/GOOD/EXCELLENT)
5. If below threshold, gathers more sources and refines
6. Returns synthesized answer with confidence assessment

## Configuration

### Minimal (environment variables only)

```bash
# Required: at least one LLM provider
export AMBIVO_AGENTS_OPENAI_API_KEY="sk-..."
# or
export AMBIVO_AGENTS_ANTHROPIC_API_KEY="sk-ant-..."

# Optional: web search
export AMBIVO_AGENTS_BRAVE_API_KEY="..."

# Optional: scraping API (free Jina Reader works without key)
export AMBIVO_AGENTS_JINA_API_KEY="..."
export AMBIVO_AGENTS_FIRECRAWL_API_KEY="..."
```

### YAML config (agent_config.yaml)

```yaml
llm:
  preferred_provider: "anthropic"
  anthropic_api_key: "sk-ant-..."

agent_capabilities:
  enable_web_search: true
  enable_web_scraping: true
  enable_knowledge_base: false  # requires Qdrant

web_search:
  brave_api_key: "..."

web_scraping:
  scraping:
    provider: "jina"  # jina | firecrawl | requests
    jina_api_key: null  # optional, for higher rate limits
```

## Memory System

Default: **in-memory** (zero infrastructure). For distributed deployments:

```bash
pip install ambivo-agents[redis]
```

```bash
export AMBIVO_AGENTS_REDIS_HOST="localhost"
```

The framework automatically uses Redis when available, falls back to in-memory.

## Optional Extras

```bash
pip install ambivo-agents[redis]       # Distributed memory (Redis + lz4)
pip install ambivo-agents[aws]         # AWS Bedrock LLM support
pip install ambivo-agents[knowledge]   # Knowledge base (Qdrant + LlamaIndex, Python 3.11-3.12)
pip install ambivo-agents[documents]   # Document processing (PDF, DOCX, PPTX)
pip install ambivo-agents[async]       # Async utilities (aiohttp, aiofiles)
pip install ambivo-agents[full]        # All runtime extras
pip install ambivo-agents[all-ml]      # Everything including knowledge base
```

## Agent Creation Patterns

```python
# Simple (recommended)
agent = AssistantAgent.create_simple(user_id="user123")
response = await agent.chat("Hello!")
await agent.cleanup_session()

# With explicit context
agent, context = AssistantAgent.create(user_id="user123")
print(f"Session: {context.session_id}")

# ModeratorAgent auto-routes to the right agent
moderator = ModeratorAgent.create_simple(user_id="user123")
response = await moderator.chat("Search for AI news")  # -> WebSearchAgent
response = await moderator.chat("Scrape https://example.com")  # -> WebScraperAgent
```

## Web Scraping (API-Based)

No browsers, no Docker. Uses HTTP APIs:

| Provider | Cost | JS Support | Default |
|----------|------|-----------|---------|
| Jina Reader | Free tier | Yes | Yes |
| Firecrawl | Paid | Yes | No |
| requests+bs4 | Free | No | Fallback |

```python
from ambivo_agents import WebScraperAgent

scraper = WebScraperAgent.create_simple(user_id="demo")
response = await scraper.chat("scrape https://example.com")
```

## Migration from v1.x

### Removed agents (use alternatives)

| v1.x Agent | Alternative |
|-----------|-------------|
| CodeExecutorAgent | OpenAI code_interpreter, E2B |
| MediaEditorAgent | Direct FFmpeg, external service |
| YouTubeDownloadAgent | yt-dlp directly |
| DatabaseAgent | Direct DB drivers |
| AnalyticsAgent | pandas/DuckDB directly |
| APIAgent | LLM tool calling |
| WorkflowDeveloperAgent | Direct workflow API |

### Breaking changes

- `redis` and `docker` removed from core dependencies
- `create_redis_memory_manager()` still works but `create_memory_manager()` is preferred
- `InMemoryMemoryManager` is the new default when Redis is unavailable
- WebScraperAgent uses HTTP APIs instead of Playwright/Docker
- Many environment variables renamed/removed (see Configuration section)

## Development

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Format code
black ambivo_agents/ --line-length=100
isort ambivo_agents/ --profile black --line-length=100
```

## License

MIT License - See LICENSE file for details.
