Metadata-Version: 2.1
Name: aigility
Version: 0.0.2
Summary: 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.
Home-page: https://github.com/AIGility-Cloud-Innovation/timem-python
Author: AIGility Cloud Innovation
Author-email: AIGility Cloud Innovation <contact@aigility.com>
Maintainer-email: AIGility Cloud Innovation <contact@aigility.com>
License: MIT
Project-URL: Homepage, https://github.com/AIGility-Cloud-Innovation/aigility
Project-URL: Documentation, https://aigility.readthedocs.io
Project-URL: Repository, https://github.com/AIGility-Cloud-Innovation/aigility
Project-URL: Issues, https://github.com/AIGility-Cloud-Innovation/aigility/issues
Project-URL: Changelog, https://github.com/AIGility-Cloud-Innovation/aigility/blob/main/CHANGELOG.md
Keywords: adk,agent,langchain,langgraph,workflow,chat,rag,memory,ai,llm
Classifier: Development Status :: 3 - Alpha
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.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: typing-extensions>=4.0.0
Requires-Dist: langchain>=0.1.0
Requires-Dist: langgraph>=0.0.20
Requires-Dist: langchain-openai>=0.0.5
Requires-Dist: langchain-anthropic>=0.1.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: isort>=5.0.0; extra == "dev"
Requires-Dist: flake8>=5.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=2.20.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=5.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
Requires-Dist: myst-parser>=0.18.0; extra == "docs"

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

```bash
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**

```python
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**

```python
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**

```python
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**

```python
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**

```python
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**

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

```bash
# Format code
make format

# Lint code
make lint

# Run type checking
make type-check

# Run all checks
make check
```

**Testing**

```bash
# Run tests
make test

# Run tests with coverage
make test-cov

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

**Build & Publish**

```bash
# 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](DEVELOPMENT.md) - Setup, workflow, and contribution guidelines
- [ADK README](adk/README.md) - Detailed module documentation
- [Release Notes](CHANGELOG.md) - 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](DEVELOPMENT.md) for detailed development guidelines.

📄 **License**

This project is licensed under the MIT License - see the [LICENSE](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
