Metadata-Version: 2.4
Name: ingenious
Version: 0.1.0
Summary: An enterprise-grade Python library for quickly setting up APIs to interact with AI Agents
Project-URL: Homepage, https://github.com/Insight-Services-APAC/ingenious
Project-URL: Documentation, https://insight-services-apac.github.io/ingenious/
Project-URL: Repository, https://github.com/Insight-Services-APAC/ingenious
Project-URL: Issues, https://github.com/Insight-Services-APAC/ingenious/issues
Author-email: John Rampono <john.rampono@insight.com>, Kokko Ng <kokko.ng@insight.com>, Elliot Zhu <elliot.zhu@insight.com>
License: MIT
License-File: LICENSE
Keywords: agent,autogen,azure,fastapi
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.13
Requires-Dist: aiosqlite>=0.21.0
Requires-Dist: annotated-types==0.7.0
Requires-Dist: anyio>=4.9.0
Requires-Dist: autogen-agentchat==0.5.7
Requires-Dist: autogen-ext[openai]==0.5.7
Requires-Dist: azure-core==1.34.0
Requires-Dist: azure-cosmos>=4.9.0
Requires-Dist: azure-identity>=1.17.1
Requires-Dist: azure-keyvault>=4.2.0
Requires-Dist: azure-search-documents==11.5.2
Requires-Dist: azure-storage-blob>=12.25.1
Requires-Dist: certifi==2025.4.26
Requires-Dist: chainlit==2.5.5
Requires-Dist: chromadb==1.0.11
Requires-Dist: colorlog>=6.9.0
Requires-Dist: duckdb==1.3.0
Requires-Dist: fastapi-cli==0.0.7
Requires-Dist: fastapi==0.115.9
Requires-Dist: flask==3.1.1
Requires-Dist: ipython==9.2.0
Requires-Dist: jinja2==3.1.6
Requires-Dist: jsonpickle==4.1.0
Requires-Dist: markdown-it-py==3.0.0
Requires-Dist: markdown==3.8
Requires-Dist: markdownify==1.0.0
Requires-Dist: markpickle==1.6.1
Requires-Dist: matplotlib==3.10.3
Requires-Dist: numpy==2.2.6
Requires-Dist: openai==1.82.0
Requires-Dist: pandas==2.2.3
Requires-Dist: pyautogen<0.3.0,>=0.2.0
Requires-Dist: pydantic==2.11.5
Requires-Dist: pyodbc==5.2.0
Requires-Dist: pypdf==5.5.0
Requires-Dist: seaborn==0.13.2
Requires-Dist: typer>=0.15.4
Provides-Extra: dataprep
Requires-Dist: backoff==2.2; extra == 'dataprep'
Requires-Dist: python-dotenv==1.0.1; extra == 'dataprep'
Requires-Dist: scrapfly-sdk==0.8.23; extra == 'dataprep'
Provides-Extra: document-processing
Requires-Dist: azure-ai-documentintelligence==1.0.2; extra == 'document-processing'
Requires-Dist: pymupdf==1.26.1; extra == 'document-processing'
Provides-Extra: pdfminer
Requires-Dist: pdfminer-six==20250506; extra == 'pdfminer'
Provides-Extra: tests
Requires-Dist: pre-commit==4.2.0; extra == 'tests'
Requires-Dist: pytest-asyncio==0.26.0; extra == 'tests'
Requires-Dist: pytest-cov==6.1.1; extra == 'tests'
Requires-Dist: pytest-mock==3.14.0; extra == 'tests'
Requires-Dist: pytest-timeout==2.4.0; extra == 'tests'
Requires-Dist: pytest==8.3.5; extra == 'tests'
Requires-Dist: ruff==0.11.10; extra == 'tests'
Requires-Dist: vulture==2.14; extra == 'tests'
Provides-Extra: unstructured
Requires-Dist: unstructured[all-docs]==0.17.2; extra == 'unstructured'
Description-Content-Type: text/markdown

# Insight Ingenious

An enterprise-grade Python library for quickly setting up APIs to interact with AI Agents, featuring tight integrations with Microsoft Azure services and comprehensive utilities for debugging and customization.

## Overview
Insight Ingenious is a production-ready library that enables developers to rapidly deploy sophisticated AI agent APIs with minimal configuration. Built specifically for enterprise environments, it provides seamless Microsoft Azure integrations, robust debugging tools, and extensive customization capabilities for building scalable AI-powered applications.

## ⚡ Quick Start

Get up and running in 5 minutes with Azure OpenAI!

### Prerequisites
- ✅ Python 3.13+
- ✅ Azure OpenAI API credentials
- ✅ [uv package manager](https://docs.astral.sh/uv/)

### 5-Minute Setup

1. **Install and Initialize**:
    ```bash
    # From your project directory
    uv pip install -e ./ingenious
    uv run ingen init
    ```

2. **Configure Credentials**:
    ```bash
    # Edit .env with your Azure OpenAI credentials
    cp .env.example .env
    nano .env  # Add AZURE_OPENAI_API_KEY and AZURE_OPENAI_BASE_URL
    ```

3. **Validate Setup** (Recommended):
    ```bash
    export INGENIOUS_PROJECT_PATH=$(pwd)/config.yml
    export INGENIOUS_PROFILE_PATH=$(pwd)/profiles.yml
    uv run ingen validate  # Check configuration before starting
    ```

4. **Start the Server**:
    ```bash
    uv run ingen serve
    ```

5. **Verify Health**:
    ```bash
    # Check server health
    curl http://localhost:80/api/v1/health
    ```

6. **Test the API**:
    ```bash
    # Test bike insights workflow (the "Hello World" of Ingenious)
    curl -X POST http://localhost:80/api/v1/chat \
      -H "Content-Type: application/json" \
      -d '{
        "user_prompt": "{\"stores\": [{\"name\": \"QuickStart Store\", \"location\": \"NSW\", \"bike_sales\": [{\"product_code\": \"QS-001\", \"quantity_sold\": 1, \"sale_date\": \"2023-04-15\", \"year\": 2023, \"month\": \"April\", \"customer_review\": {\"rating\": 5.0, \"comment\": \"Perfect bike for getting started!\"}}], \"bike_stock\": []}], \"revision_id\": \"quickstart-1\", \"identifier\": \"hello-world\"}",
        "conversation_flow": "bike-insights"
      }'
    ```

🎉 **That's it!** You should see a comprehensive JSON response with insights from multiple AI agents analyzing the bike sales data.

**Note**: The `bike-insights` workflow is created when you run `ingen init` - it's part of the project template setup, not included in the core library.

### 📚 Detailed Setup
- **📖 Complete guide**: [docs/QUICKSTART.md](docs/QUICKSTART.md) - Full walkthrough with examples
- **🔧 Troubleshooting**: [docs/troubleshooting/README.md](docs/troubleshooting/README.md) - Common issues & fixes
- **📡 API Reference**: [docs/api/WORKFLOWS.md](docs/api/WORKFLOWS.md) - All endpoints & workflows

## 🎯 Workflow Categories

Insight Ingenious provides multiple conversation workflows with different configuration requirements:

### ✅ **Core Workflows (Azure OpenAI only)**
- `classification-agent` - Route input to specialized agents based on content

### 🔍 **Core Workflows (Require Additional Services)**
- `knowledge-base-agent` - Search knowledge bases (requires Azure Search Service)
- `sql-manipulation-agent` - Execute SQL queries (requires database connection)

### ⭐ **"Hello World" Workflow** (Available via project template)
- `bike-insights` - **The recommended starting point** - Comprehensive bike sales analysis showcasing multi-agent coordination (created when you run `ingen init`)

**📋 See [Workflow Configuration Requirements](docs/workflows/README.md) for detailed setup instructions.**

**🔄 Naming Formats**: Workflows support both hyphenated (`bike-insights`) and underscored (`bike_insights`) naming formats for backward compatibility. New projects should use hyphenated names.

## Project Structure

- `ingenious/`: Core framework code
  - `api/`: API endpoints and routes
  - `chainlit/`: Web UI components
  - `config/`: Configuration management
  - `core/`: Core logging and utilities
  - `dataprep/`: Data preparation utilities
  - `db/`: Database integration
  - `document_processing/`: Document analysis and processing
  - `errors/`: Error handling and custom exceptions
  - `external_services/`: External service integrations
  - `files/`: File storage utilities
  - `models/`: Data models and schemas
  - `services/`: Core services including chat and agent services
  - `templates/`: Prompt templates and HTML templates
  - `utils/`: Utility functions
  - `ingenious_extensions_template/`: Template for custom extensions
    - `api/`: Custom API routes
    - `models/`: Custom data models
    - `sample_data/`: Sample data for testing
    - `services/`: Custom agent services
    - `templates/`: Custom prompt templates
    - `tests/`: Test harness for agent prompts

- `ingenious_prompt_tuner/`: Tool for tuning and testing prompts

## Documentation

For detailed documentation, see the [docs/](docs/) directory:

- **[⚡ Quick Start Guide](docs/QUICKSTART.md)** - **Complete 5-minute setup with examples**
- **[🛠️ Troubleshooting](docs/troubleshooting/README.md)** - **Common issues and solutions**
- **[📡 API Reference](docs/api/WORKFLOWS.md)** - **All endpoints and workflows**
- [Getting Started](docs/getting-started/README.md) - Installation and setup details
- [Workflow Configuration Requirements](docs/workflows/README.md) - Service setup for different workflows
- [User Guides](docs/guides/README.md) - Feature-specific usage guides
- [Extensions & Customization](docs/extensions/README.md) - Creating custom components
- [Configuration Guide](docs/configuration/README.md) - Detailed configuration reference
- [Architecture Overview](docs/architecture/README.md) - System design and architecture
- [Development Guide](docs/development/README.md) - Contributing and development setup
- [Components Reference](docs/components/README.md) - Technical component documentation

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

This project is licensed under the terms specified in the [LICENSE](LICENSE) file.
