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
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.
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.