Metadata-Version: 2.2
Name: ambivo-agents
Version: 2.1.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

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

[![PyPI version](https://img.shields.io/pypi/v/ambivo-agents.svg)](https://pypi.org/project/ambivo-agents/)
[![Python](https://img.shields.io/pypi/pyversions/ambivo-agents.svg)](https://pypi.org/project/ambivo-agents/)

## Why v2.x

v2 is a focused rewrite. We cut 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.x |
|--------|------|------|
| Agents | 14 | 7 |
| Core dependencies | 12 | 9 |
| Requires Redis | Yes | No (in-memory default) |
| Requires Docker | Yes | No |
| Requires Playwright | Yes (~400 MB browsers) | No (API-based scraping) |
| Install size | ~500 MB | ~15 MB |

## Quick Start

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

```python
import asyncio
from ambivo_agents import AssistantAgent

async def main():
    agent = AssistantAgent.create_simple(user_id="demo")
    response = await agent.chat("Explain quantum computing in 3 sentences.")
    print(response)
    await agent.cleanup_session()

asyncio.run(main())
```

No Redis. No Docker. No config file. 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) |
| `GatherAgent` | Conversational form filling with conditional logic |

## Minimal Configuration

The only **required** variable is one LLM provider API key. Everything else has sensible defaults.

```bash
# Required — at least one
export AMBIVO_AGENTS_OPENAI_API_KEY="sk-..."
export AMBIVO_AGENTS_ANTHROPIC_API_KEY="sk-ant-..."
```

That's it. You can now create any agent and call `.chat()`.

### Optional: Enable web search and scraping

```bash
# Web search (optional — enables WebSearchAgent)
export AMBIVO_AGENTS_BRAVE_API_KEY="..."
export AMBIVO_AGENTS_ENABLE_WEB_SEARCH="true"

# Web scraping (optional — Jina Reader works without a key)
export AMBIVO_AGENTS_ENABLE_WEB_SCRAPING="true"
export AMBIVO_AGENTS_JINA_API_KEY="..."        # optional, higher rate limits
export AMBIVO_AGENTS_FIRECRAWL_API_KEY="..."   # optional, premium scraping
```

### Optional: Knowledge base (requires Qdrant)

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

```bash
export AMBIVO_AGENTS_ENABLE_KNOWLEDGE_BASE="true"
export AMBIVO_AGENTS_QDRANT_URL="https://your-cluster.qdrant.tech:6333"
export AMBIVO_AGENTS_QDRANT_API_KEY="..."
```

### Optional: Distributed memory via Redis

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

```bash
export AMBIVO_AGENTS_REDIS_HOST="localhost"
export AMBIVO_AGENTS_REDIS_PORT="6379"
export AMBIVO_AGENTS_REDIS_PASSWORD=""
```

By default the framework uses an in-memory store. Set Redis variables only for multi-process or distributed deployments.

### YAML config alternative (`agent_config.yaml`)

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

agent_capabilities:
  enable_web_search: true
  enable_web_scraping: true
  enable_knowledge_base: false

web_search:
  brave_api_key: ...

web_scraping:
  scraping:
    provider: jina   # jina | firecrawl | requests
```

## Core Differentiator: Quality-Gated Synthesis

```python
from ambivo_agents import KnowledgeSynthesisAgent

agent = KnowledgeSynthesisAgent.create_simple(user_id="researcher")
response = await agent.chat("What are the latest advances in quantum error correction?")
```

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

No other mainstream agent framework ships this out of the box.

## 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 best 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. Just HTTP APIs with SSRF protection:

| Provider | Cost | JS rendering | Default |
|----------|------|-------------|---------|
| Jina Reader | Free tier | Yes | Yes |
| Firecrawl | Paid | Yes | No |
| requests+bs4 | Free | No | Offline fallback |

```python
from ambivo_agents import WebScraperAgent

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

All scraped URLs are validated to block SSRF attacks against private IPs, loopback addresses, and cloud metadata services.

## 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
```

## All Environment Variables

Only set what you need:

| Variable | Purpose |
|----------|---------|
| `AMBIVO_AGENTS_OPENAI_API_KEY` | OpenAI API key |
| `AMBIVO_AGENTS_ANTHROPIC_API_KEY` | Anthropic API key |
| `AMBIVO_AGENTS_AWS_ACCESS_KEY_ID` | AWS Bedrock access key |
| `AMBIVO_AGENTS_AWS_SECRET_ACCESS_KEY` | AWS Bedrock secret |
| `AMBIVO_AGENTS_AWS_REGION` | AWS region (default: us-east-1) |
| `AMBIVO_AGENTS_LLM_PREFERRED_PROVIDER` | `openai`, `anthropic`, or `bedrock` |
| `AMBIVO_AGENTS_LLM_TEMPERATURE` | LLM temperature (default: 0.5) |
| `AMBIVO_AGENTS_ENABLE_WEB_SEARCH` | Enable WebSearchAgent |
| `AMBIVO_AGENTS_ENABLE_WEB_SCRAPING` | Enable WebScraperAgent |
| `AMBIVO_AGENTS_ENABLE_KNOWLEDGE_BASE` | Enable KnowledgeBaseAgent |
| `AMBIVO_AGENTS_BRAVE_API_KEY` | Brave Search API key |
| `AMBIVO_AGENTS_AVESAPI_API_KEY` | AVES Search API key |
| `AMBIVO_AGENTS_SCRAPING_PROVIDER` | `jina` (default), `firecrawl`, or `requests` |
| `AMBIVO_AGENTS_JINA_API_KEY` | Jina Reader API key (optional) |
| `AMBIVO_AGENTS_FIRECRAWL_API_KEY` | Firecrawl API key (optional) |
| `AMBIVO_AGENTS_QDRANT_URL` | Qdrant vector DB URL |
| `AMBIVO_AGENTS_QDRANT_API_KEY` | Qdrant API key |
| `AMBIVO_AGENTS_REDIS_HOST` | Redis host (optional) |
| `AMBIVO_AGENTS_REDIS_PORT` | Redis port (default: 6379) |
| `AMBIVO_AGENTS_REDIS_PASSWORD` | Redis password |
| `AMBIVO_AGENTS_LOG_LEVEL` | Log level (default: INFO) |

## 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
```

## Maintainers

- **Arnav Gosain** — [@agosain1](https://github.com/agosain1)

## Contributors

- **Arnav Gosain** ([@agosain1](https://github.com/agosain1))

See the [full contributors list](https://github.com/ambivo-corp/ambivo-agents/graphs/contributors) on GitHub.

## License

MIT License — see [LICENSE](LICENSE) file.
