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.genai.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
├── genai/            # Generative AI, three one-way layers
│   ├── llm/          # Model access: client, call hooks, prompts, token counting
│   ├── flow/         # Flow execution framework (agent / tool / flow / nodes / guards)
│   └── harness/      # Runtime: ports, events, projection, metering, overflow, context, spill
├── 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 BaseSchema for Pydantic models
Use ruff and pyright for 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.

Metadata

Release files for agstack 3.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agstack 3.1.0
File	Size	Uploaded
agstack-3.1.0.tar.gz	140.2 kB	Oct 8, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for agstack 3.1.0
File	Interpreter	ABI	Platform	Reset
agstack-3.1.0-py3-none-any.whl 129.8 kB Oct 8, 2026	Python 3	none	any	Details

Total release size: 270.0 kB

Release files / agstack-3.1.0.tar.gz

Download URL	agstack-3.1.0.tar.gz
Size	140.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`a1f033ce9fa8b3cd5dca651337f063a2a33c4f5b4de2a9ff096bb148b329824e`
BLAKE2b-256 checksum How to use checksums	`a531b47209f8f3008b2ef74015148dfc24a906bfc7947fb0f4dc54f09fe4b85e`
Upload date	Oct 8, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.21 {"installer":{"name":"uv","version":"0.12.21","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}`

Release files / agstack-3.1.0-py3-none-any.whl

Download URL	agstack-3.1.0-py3-none-any.whl
Size	129.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`d6c67c583efb723bcf3646b1cf02fbf171ce15a29bf3f36189a21e49c0821bb0`
BLAKE2b-256 checksum How to use checksums	`2fe937d83c0bca3c9b5f1ab5de1927a279cf2c074e5b44d8099f24bb73c75b6d`
Upload date	Oct 8, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.21 {"installer":{"name":"uv","version":"0.12.21","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}`