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.0.0.tar.gz
(81.5 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.0.0-py3-none-any.whl
(83.7 kB
view details)
File details
Details for the file agstack-2.0.0.tar.gz.
File metadata
- Download URL: agstack-2.0.0.tar.gz
- Upload date:
- Size: 81.5 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 |
a2cce248dffc291d68eb4e4ef2b82b57498781b8871c4531dd0d784887791c52
|
|
| MD5 |
53f52e5b88376e850dfea5882399fa4f
|
|
| BLAKE2b-256 |
2fb71a50106a3bbac07294c48ebebe33975f23441dc19036e12f32edd26a9740
|
File details
Details for the file agstack-2.0.0-py3-none-any.whl.
File metadata
- Download URL: agstack-2.0.0-py3-none-any.whl
- Upload date:
- Size: 83.7 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 |
92f2810f531a20500a54af24b94e20ac77a9a0f0d23195094ada6ed760daafb8
|
|
| MD5 |
6175afd5e973396b67c1cc8feec9c349
|
|
| BLAKE2b-256 |
2f5d3c0180f01f04e50035f5b54707e205832bb888a7e964dd33fdf2b4abe6a5
|
