AgStack
Production-ready toolkit for building FastAPI and LLM applications
📖 Overview
AgStack is a comprehensive Python framework designed for building production-ready FastAPI applications with integrated LLM capabilities. It provides:
- 🚀 FastAPI Integration - Production-ready web framework setup
- 🤖 LLM Flow System - Orchestrate Agents, Tools, and Flows
- 📦 Component Registry - Unified registration and factory pattern
- 🔐 Security - Built-in authentication and authorization (Casbin)
- 🗄️ Infrastructure - Database, Elasticsearch, and Message Queue support
- 📊 Schema System - Unified Pydantic models with enhanced serialization
🚀 Quick Start
Installation
pip install agstack
Basic Usage
from agstack.llm.flow import (
Tool,
FlowContext,
registry,
create_tool
)
# Define a tool
class MyTool(Tool):
def __init__(self):
super().__init__(
name="my_tool",
description="My custom tool",
function=self.execute
)
async def execute(self, context: FlowContext):
return "Tool result"
# Register the tool
registry.register_tool("my_tool", MyTool)
# Use the tool
context = FlowContext(session_id="test")
tool = create_tool("my_tool")
result = await tool.run(context)
📚 Documentation
- Usage Guide - Learn how to use AgStack in your projects
- Development Rules - Guidelines for contributing to AgStack
- API Reference - Coming soon
- Examples - Coming soon
🏗️ Architecture
Project Structure
agstack/
├── schema.py # Base Pydantic models
├── registry.py # Global component registry
├── exceptions.py # Exception hierarchy
├── llm/ # LLM and AI features
│ ├── client.py # LLM client
│ └── flow/ # Flow execution framework
│ ├── agent.py # Agent definition
│ ├── tool.py # Tool definition
│ ├── flow.py # Flow orchestration
│ └── ...
├── fastapi/ # FastAPI integration
├── infra/ # Infrastructure components
│ ├── db/ # Database
│ ├── es/ # Elasticsearch
│ └── mq/ # Message Queue
└── security/ # Security features
Core Concepts
- Agent - LLM-powered intelligent agents
- Tool - Functions that can be called by agents
- Flow - Orchestration of multiple agents and tools
- Registry - Centralized component management
- BaseSchema - Enhanced Pydantic models with unified configuration
🛠️ Development
Requirements
- Python >= 3.12
- Dependencies listed in
pyproject.toml
Setup
# Clone the repository
git clone https://github.com/xtravisions/agstack.git
cd agstack
# Install dependencies
pip install -e ".[dev]"
# Install pre-commit hooks
pre-commit install
Code Quality
# Format code
ruff format .
# Lint
ruff check .
# Type check
pyright
Contributing
Please read DEVELOPMENT_RULES.md for development guidelines and coding standards.
📦 Features
LLM Flow System
- Agent System - Create and manage LLM-powered agents
- Tool System - Define reusable tools for agents
- Flow Orchestration - Chain multiple agents and tools
- Context Management - Maintain state across execution
- Event System - AG-UI protocol support
FastAPI Integration
- Production-ready setup
- Middleware support
- Exception handling
- Request/Response schemas
Infrastructure
- Database - PostgreSQL with async support (asyncpg)
- Elasticsearch - Full-text search integration
- Message Queue - Async message processing (aio-pika)
Security
- JWT authentication
- Casbin authorization
- Password hashing (bcrypt)
🤝 Contributing
We welcome contributions! Please see our Development Rules for guidelines.
Key Guidelines
- Use relative imports (not
from agstack...) - Inherit from
BaseSchemafor Pydantic models - Use
ruffandpyrightfor code quality - Follow Python 3.12+ standards
- Write tests for new features
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
👥 Authors
- XtraVisions - gitadmin@xtravisions.com
- Chen Hao - chenhao@xtravisions.com
🔗 Links
- Documentation: docs/
- GitHub: (TBD)
- Issues: (TBD)
- PyPI: (TBD)
📝 Changelog
See CHANGELOG.md for release history.
Note: AgStack is under active development. APIs may change before the 1.0 stable release.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
agstack-2.1.0.tar.gz
(90.1 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
agstack-2.1.0-py3-none-any.whl
(87.2 kB
view details)
File details
Details for the file agstack-2.1.0.tar.gz.
File metadata
- Download URL: agstack-2.1.0.tar.gz
- Upload date:
- Size: 90.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.11.14 {"installer":{"name":"uv","version":"0.11.14","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
bbddf17dcc5a5b6fd490a29d6661671344442ee16274f09cddd6c030e1e75f86
|
|
| MD5 |
70328391a4cf1268e77bc7dcaf4d1ab7
|
|
| BLAKE2b-256 |
7cfe069acfecdf37418a01c0ddfb324be68c0dbd401e3897f5f6e67aad5294ce
|
File details
Details for the file agstack-2.1.0-py3-none-any.whl.
File metadata
- Download URL: agstack-2.1.0-py3-none-any.whl
- Upload date:
- Size: 87.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.11.14 {"installer":{"name":"uv","version":"0.11.14","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
85faa355352587dd9d56c25f5f857b7d5deb80e04f49bbe2a4d49d34c8907de5
|
|
| MD5 |
6a856be17de96a6b6ae83173550d49f0
|
|
| BLAKE2b-256 |
f7aea1bbe8bc4782cda3e0140416678e33c311b52c80b7f678a516e120e2e80b
|
