Skip to main content

AgStack

Production-ready toolkit for building FastAPI and LLM applications

Python License Version

📖 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

  • 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.5.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.5.0
File Size Uploaded Provenance Actions
agstack-3.5.0.tar.gz 159.2 kB Without provenance Details for agstack-3.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agstack 3.5.0
File Interpreter ABI Platform Actions
agstack-3.5.0-py3-none-any.whl Python 3 none any Details for agstack-3.5.0-py3-none-any.whl

Total release size: 300.7 kB

Release files / agstack-3.5.0.tar.gz

Download URL agstack-3.5.0.tar.gz
Size 159.2 kB
Tags Source
SHA-256 checksum
How to use checksums
979ced5adfd8f5b88bdeb7e13048029f43438c0cca21be25d2930a4d9d0967d1
BLAKE2b-256 checksum
How to use checksums
8c20df17f52e30044d2bd4b4e9a7fb0536443cb5011c9908b4c1835dc56ec08f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","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.5.0-py3-none-any.whl

Download URL agstack-3.5.0-py3-none-any.whl
Size 141.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ca9498d319aba5b1ce92413a90c9649f4a2e62574a8e208f66a18d6a8a43ae9b
BLAKE2b-256 checksum
How to use checksums
431e820f69c5d029c40e216a95960bed35e44e4930d6476824365b0d455c17f1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","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}

Security for agstack 3.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

3.5.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page