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.1

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.1
File Size Uploaded Provenance Actions
agstack-3.5.1.tar.gz 160.1 kB Without provenance Details for agstack-3.5.1.tar.gz

Built distribution (wheel)

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

Total release size: 301.7 kB

Release files / agstack-3.5.1.tar.gz

Download URL agstack-3.5.1.tar.gz
Size 160.1 kB
Tags Source
SHA-256 checksum
How to use checksums
2b492a79f7aa42eccf4069ac9e6a136de214328a2bbc8678637e2c46f4f88382
BLAKE2b-256 checksum
How to use checksums
ee0874dc981aaaeee04bfe8e740b0df5c2f2ff894047fa1d47d13b9a92de8f20
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.1-py3-none-any.whl

Download URL agstack-3.5.1-py3-none-any.whl
Size 141.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
43b48ef27ddd606548f820d845fe39f9b1e8f907563ad15ee3dbc88e00596de8
BLAKE2b-256 checksum
How to use checksums
38ea43c23571095027029c6e43c52490c8fecf51f806bae776f5e237824f9561
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.1

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.1 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