aigility 0.0.2

A modern Python ADK - Agent Development Kit for building AI agents with LangGraph and LangChain. This library provides a comprehensive, type-safe framework for developing intelligent agents with chat, workflow, memory, and knowledge management capabilities.

AIGility

License: MIT

A modern Python ADK - Agent Development Kit for building AI agents with LangGraph and LangChain. This library provides a comprehensive, type-safe framework for developing intelligent agents with chat, workflow, memory, and knowledge management capabilities.

✨ Features

• Complete Agent Framework: Chat, ChatFlow, Workflow, Knowledge, and Memory management modules
• Builder Pattern: Fluent, chainable interface for constructing agents and workflows
• Sync & Async Support: Both synchronous and asynchronous operations
• Type Safety: Comprehensive type hints with Pydantic 2.x validation
• Memory Management: Intelligent memory storage and retrieval with semantic search
• Knowledge Base: RAG (Retrieval Augmented Generation) capabilities
• Workflow Engine: State-based workflow orchestration with LangGraph
• Modern HTTP Client: Built on httpx with connection pooling, circuit breaker, and retry mechanisms
• Connection Pool Optimization: Efficient TCP connection reuse to reduce resource overhead

📦 Installation

pip install aigility

Requirements: Python 3.8+

Core Dependencies:

• pydantic (^2) - Data validation and settings management with type safety
• httpx (^0.24) - Modern async HTTP client
• langchain (^0.1) - LLM framework for building applications
• langgraph (^0.0.20) - Workflow orchestration framework

Development Dependencies:

• pytest (^7) - Testing framework
• black (^22) - Code formatter
• isort (^5) - Import sorter
• flake8 (^5) - Linter
• mypy (^1) - Static type checking

🛠️ Technology Stack

• Language: Python 3.8+
• HTTP Client: httpx with connection pooling, circuit breaker, and retry optimization
• Type System: Pydantic 2.x with comprehensive type validation
• Architecture: Builder pattern with fluent API design + Service layer pattern
• Async Support: Full async/await support
• Agent Framework: LangChain for chat, LangGraph for workflows
• Code Quality: Black + isort (formatting) + Flake8 (linting) + MyPy (type checking)
• Testing: pytest with async support
• Packaging: Modern Python packaging with pyproject.toml

🚀 Quick Start

Basic Usage

from adk import create_client

# Initialize client with builder pattern
client = create_client(
    llm_provider="openai",
    llm_api_key="your-api-key",
    memory_api_key="your-memory-api-key",
    memory_base_url="http://localhost:8001"
)

# Use memory management
memory = client.memory
result = await memory.add(
    messages=[
        {"role": "user", "content": "Hello"},
        {"role": "assistant", "content": "Hi! How can I help you?"}
    ],
    user_id="user-123",
    character_id="assistant"
)

# Search memories
results = await memory.search(
    query="user preferences",
    user_id="user-123",
    limit=5
)

Builder Pattern

from adk import ADKClientBuilder

# Create client with builder pattern
client = (
    ADKClientBuilder()
    .with_llm(provider="openai", model="gpt-4", api_key="your-key")
    .with_memory(api_key="your-memory-key", base_url="http://localhost:8001")
    .with_knowledge(store_type="vector")
    .with_http(timeout=60.0, max_retries=3)
    .with_debug(enabled=True)
    .build()
)

🔧 Core Modules

Core Module

• Base Classes: BaseAgent, BaseTool, BaseMemory - Abstract base classes for extensibility
• Type System: State, Message, AgentResponse - Type-safe data structures
• Configuration: ADKConfig, AgentConfig, ToolConfig - Comprehensive configuration management

HTTP Transport Layer

• Connection Pool: Efficient connection reuse with health checks
• Circuit Breaker: Automatic failure detection and recovery
• Retry Mechanism: Configurable retry with exponential backoff

Memory Module

• Memory Management: Add, search, and manage memories with semantic search
• Layered Memory: Support for L1-L5 memory layers
• User Context: User-specific memory storage and retrieval

Chat Module (Based on LangChain)

• Chat Agents: Build conversational agents with LangChain
• Tool Integration: Seamless tool integration for agent capabilities
• Memory Integration: Automatic memory integration for context retention

ChatFlow Module (Based on LangGraph)

• Conversation Flow: Multi-agent conversation orchestration
• State Management: State-based flow control
• Event Streaming: Real-time event streaming support

Workflow Module (Based on LangGraph)

• Workflow Engine: State-based workflow orchestration
• Graph Builder: Visual workflow graph construction
• Node Management: Flexible node definition and execution

Knowledge Module (RAG)

• Retriever: Abstract retriever interface for various backends
• Knowledge Store: Vector, graph, and hybrid storage support
• RAG Pipeline: Complete RAG pipeline builder

Model Module

• LLM Provider: Unified interface for multiple LLM providers (OpenAI, Anthropic, etc.)
• Embeddings Provider: Embedding model integration

💡 Examples

Memory Management

from adk import create_client

client = create_client(memory_api_key="your-key")

# Add memory
result = await client.memory.add(
    messages=[{"role": "user", "content": "I love Python"}],
    user_id="user-123",
    character_id="assistant"
)

# Search memories
results = await client.memory.search(
    query="programming preferences",
    user_id="user-123",
    limit=5
)

Creating Chat Agents

from adk import create_client
from adk.core.config import AgentConfig

client = create_client(llm_provider="openai", llm_api_key="your-key")

# Create chat agent
agent = client.create_chat_agent(
    name="my_agent",
    config=AgentConfig(
        name="my_agent",
        description="A helpful assistant",
        prompt_template="You are a helpful assistant.",
        tools=["search", "calculator"]
    )
)

Workflow Creation

from adk.workflow import WorkflowGraphBuilder
from adk.core.types import State

# Build workflow
builder = WorkflowGraphBuilder()
builder.add_node("start", start_node_func)
builder.add_node("process", process_node_func)
builder.add_edge("start", "process")
builder.set_start("start")

# Create and run workflow
workflow = builder.build()
result = await workflow.invoke(initial_state=State())

🛠️ Development

Prerequisites

• Python 3.8+
• pip or poetry (for dependency management)
• Git (for version control)

Setup

# Clone repository
git clone https://github.com/AIGility-Cloud-Innovation/aigility.git
cd aigility

# Install in development mode
pip install -e ".[dev]"

# Or with poetry
poetry install

Code Quality Tools

# Format code
make format

# Lint code
make lint

# Run type checking
make type-check

# Run all checks
make check

Testing

# Run tests
make test

# Run tests with coverage
make test-cov

# Run specific test module
pytest tests/memory/ -v

Build & Publish

# Build package
make build

# Publish to PyPI
make publish

📁 Project Structure

aigility/
├── adk/                    # Main SDK package
│   ├── core/               # Core functionality
│   │   ├── base.py         # Base classes (BaseAgent, BaseTool, BaseMemory)
│   │   ├── config.py       # Configuration management
│   │   └── types.py        # Type definitions
│   ├── http/               # HTTP transport layer
│   │   ├── client.py       # HTTP client
│   │   ├── pool.py         # Connection pool
│   │   ├── circuit_breaker.py  # Circuit breaker
│   │   └── retry.py        # Retry mechanism
│   ├── model/              # Model layer
│   │   ├── llm.py          # LLM provider
│   │   └── embeddings.py   # Embeddings provider
│   ├── utils/              # Utility functions
│   │   ├── logger.py       # Logging utilities
│   │   └── workflow.py     # Workflow utilities
│   ├── memory/             # Memory management
│   │   ├── client.py       # Memory client
│   │   ├── memory.py       # Memory interface
│   │   └── types.py        # Memory types
│   ├── chat/               # Chat module (LangChain)
│   │   └── agent.py        # Chat agent
│   ├── chatflow/           # ChatFlow module (LangGraph)
│   │   └── flow.py         # ChatFlow
│   ├── workflow/           # Workflow module (LangGraph)
│   │   ├── engine.py       # Workflow engine
│   │   └── builder.py      # Workflow builder
│   ├── knowledge/          # Knowledge module (RAG)
│   │   ├── retriever.py    # Retriever interface
│   │   └── store.py        # Knowledge store
│   └── client.py           # Main client interface
├── docs/                   # Documentation
├── examples/               # Usage examples
├── tests/                  # Test suite
├── pyproject.toml          # Project configuration
├── Makefile               # Development automation
└── DEVELOPMENT.md         # Development guide

📖 Documentation

• Development Guide - Setup, workflow, and contribution guidelines
• ADK README - Detailed module documentation
• Release Notes - Version history and changes

🤝 Contributing

Contributions are welcome! Please follow our development workflow:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes with comprehensive tests
4. Ensure code quality passes (make check)
5. Run the full test suite (make test)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Submit a pull request

Branch Strategy

• main - Main development branch
• feature/* - Feature branches
• bugfix/* - Bug fix branches
• hotfix/* - Urgent fixes

See DEVELOPMENT.md for detailed development guidelines.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• PyPI Package: https://pypi.org/project/aigility/
• Source Code: https://github.com/AIGility-Cloud-Innovation/aigility
• Documentation: https://aigility.readthedocs.io

Keywords: aigility, agent, langchain, langgraph, workflow, chat, rag, memory, ai, llm, python-sdk, async, type-safe, api-client