ingenious 0.1.2

An enterprise-grade Python library for quickly setting up APIs to interact with AI Agents

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.

Quick Start

Get up and running in 5 minutes with Azure OpenAI!

Prerequisites

• Python 3.13+
• Azure OpenAI API credentials
• uv package manager

5-Minute Setup

1. Install and Initialize:

   # From your project directory
   uv add ingenious
   uv run ingen init
   

2. Configure Credentials:

   For Linux-based Environments

   # Edit .env with your Azure OpenAI credentials
   cp .env.example .env
   nano .env  # Add AZURE_OPENAI_API_KEY and AZURE_OPENAI_BASE_URL
   

   For Windows-based Environments

   # Edit .env with your Azure OpenAI credentials
   cp .env.example .env
   # Assuming you have VSCode installation. If none, open .env file with your favorite editor
   # and add  AZURE_OPENAI_API_KEY and AZURE_OPENAI_BASE_URL to it.
   code .env  # Add AZURE_OPENAI_API_KEY and AZURE_OPENAI_BASE_URL
   

3. Validate Setup (Recommended):

   For Linux-based Environments

   export INGENIOUS_PROJECT_PATH=$(pwd)/config.yml
   export INGENIOUS_PROFILE_PATH=$(pwd)/profiles.yml
   uv run ingen validate  # Check configuration before starting
   

   For Windows-based Environments

   $env:INGENIOUS_PROJECT_PATH = "{your_project_folder}/config.yml"
   $env:INGENIOUS_PROFILE_PATH = "{profile_folder_location}/profiles.yml"                        
   uv run ingen validate  # Check configuration before starting
   

4. Start the Server:

   uv run ingen serve
   

5. Verify Health:

   # Check server health
   curl http://localhost:80/api/v1/health
   

6. Test the API:

   # 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. You can now build on bike-insights as a template for your specific use case.

Workflow Categories

Insight Ingenious provides multiple conversation workflows with different configuration requirements:

Core Workflows (Available in library)

• classification-agent - Route input to specialized agents based on content (Azure OpenAI only)
• knowledge-base-agent - Search knowledge bases using local ChromaDB (stable local implementation)
• sql-manipulation-agent - Execute SQL queries using local SQLite (stable local implementation)

Extension Template Workflows (Available via project template)

• bike-insights - Comprehensive bike sales analysis showcasing multi-agent coordination (created when you run ingen init)

Note: Only local implementations (ChromaDB for knowledge-base-agent, SQLite for sql-manipulation-agent) are currently stable. Azure Search and Azure SQL integrations are experimental and may contain bugs.

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:

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

This project is licensed under the terms specified in the LICENSE file.