agstack 1.0.0__tar.gz

agstack-1.0.0/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: agstack
+Version: 1.0.0
+Summary: Production-ready toolkit for building FastAPI and LLM applications
+Author-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>
+Maintainer-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>
+License-Expression: MIT
+Keywords: fastapi,llm,agents,ai,infrastructure,framework,casbin,openai,logging,configuration
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Framework :: FastAPI
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: ag-ui-protocol>=0.1.10
+Requires-Dist: aio-pika>=9.5.8
+Requires-Dist: asyncpg>=0.30.0
+Requires-Dist: elasticsearch[async]>=9.2.1
+Requires-Dist: fastapi>=0.121.3
+Requires-Dist: jwcrypto>=1.5.6
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: openai>=2.16.0
+Requires-Dist: passlib[bcrypt]>=1.7.4
+Requires-Dist: pycasbin>=2.6.0
+Requires-Dist: pydantic>=2.12.4
+Requires-Dist: python-multipart>=0.0.20
+Requires-Dist: requests>=2.32.5
+Requires-Dist: sqlalchemy[asyncio]>=2.0.46
+Requires-Dist: sqlobjects>=1.0.16
+Requires-Dist: tiktoken>=0.12.0
+Requires-Dist: uvicorn>=0.38.0
+
+# AgStack
+
+> Production-ready toolkit for building FastAPI and LLM applications
+
+[![Python](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Version](https://img.shields.io/badge/version-1.0.0-orange.svg)](https://github.com/xtravisions/agstack)
+
+## 📖 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
+
+```bash
+pip install agstack
+```
+
+### Basic Usage
+
+```python
+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](docs/USAGE_GUIDE.md)** - Learn how to use AgStack in your projects
+- **[Development Rules](docs/DEVELOPMENT_RULES.md)** - 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
+
+```bash
+# 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
+
+```bash
+# Format code
+ruff format .
+
+# Lint
+ruff check .
+
+# Type check
+pyright
+```
+
+### Contributing
+
+Please read [DEVELOPMENT_RULES.md](docs/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](docs/DEVELOPMENT_RULES.md) 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](LICENSE) file for details.
+
+## 👥 Authors
+
+- **XtraVisions** - [gitadmin@xtravisions.com](mailto:gitadmin@xtravisions.com)
+- **Chen Hao** - [chenhao@xtravisions.com](mailto:chenhao@xtravisions.com)
+
+## 🔗 Links
+
+- **Documentation**: [docs/](docs/)
+- **GitHub**: (TBD)
+- **Issues**: (TBD)
+- **PyPI**: (TBD)
+
+## 📝 Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for release history.
+
+---
+
+**Note**: AgStack is under active development. APIs may change before the 1.0 stable release.

agstack-1.0.0/README.md

@@ -0,0 +1,199 @@
+# AgStack
+
+> Production-ready toolkit for building FastAPI and LLM applications
+
+[![Python](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Version](https://img.shields.io/badge/version-1.0.0-orange.svg)](https://github.com/xtravisions/agstack)
+
+## 📖 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
+
+```bash
+pip install agstack
+```
+
+### Basic Usage
+
+```python
+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](docs/USAGE_GUIDE.md)** - Learn how to use AgStack in your projects
+- **[Development Rules](docs/DEVELOPMENT_RULES.md)** - 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
+
+```bash
+# 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
+
+```bash
+# Format code
+ruff format .
+
+# Lint
+ruff check .
+
+# Type check
+pyright
+```
+
+### Contributing
+
+Please read [DEVELOPMENT_RULES.md](docs/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](docs/DEVELOPMENT_RULES.md) 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](LICENSE) file for details.
+
+## 👥 Authors
+
+- **XtraVisions** - [gitadmin@xtravisions.com](mailto:gitadmin@xtravisions.com)
+- **Chen Hao** - [chenhao@xtravisions.com](mailto:chenhao@xtravisions.com)
+
+## 🔗 Links
+
+- **Documentation**: [docs/](docs/)
+- **GitHub**: (TBD)
+- **Issues**: (TBD)
+- **PyPI**: (TBD)
+
+## 📝 Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for release history.
+
+---
+
+**Note**: AgStack is under active development. APIs may change before the 1.0 stable release.

agstack-1.0.0/agstack/__init__.py

@@ -0,0 +1,2 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+

agstack-1.0.0/agstack/config/__init__.py

@@ -0,0 +1,2 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+

agstack-1.0.0/agstack/config/logger.py

@@ -0,0 +1,80 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+import logging
+import sys
+from datetime import time, timedelta
+from pathlib import Path
+
+from loguru import RetentionFunction, RotationFunction, logger
+
+
+class InterceptHandler(logging.Handler):
+    """拦截标准 logging 并重定向到 loguru"""
+
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            level = logger.level(record.levelname).name
+        except ValueError:
+            level = record.levelno
+
+        # 直接使用 logging.LogRecord 的信息，避免栈帧查找
+        logger.patch(
+            lambda r: r.update(
+                name=record.name,
+                file={"name": record.pathname, "path": record.pathname},  # type: ignore[arg-type]
+                line=record.lineno,
+                function=record.funcName,
+            )
+        ).log(level, record.getMessage())
+
+        # CRITICAL/FATAL 级别自动退出
+        if record.levelno >= logging.CRITICAL:
+            sys.exit(1)
+
+
+def setup_logger(
+    appname: str,
+    output: str | Path,
+    level: str | int = "INFO",
+    rotation: str | int | time | timedelta | RotationFunction | None = "1 day",
+    retention: str | int | timedelta | RetentionFunction | None = "30 days",
+) -> None:
+    """初始化日志系统
+
+    :param appname: 应用名称
+    :param output: 日志输出目录
+    :param level: 日志级别（默认 INFO）
+    :param rotation: 日志轮转策略（默认每天轮转）
+    :param retention: 日志保留策略（默认保留 30 天）
+    """
+    log_path = Path(output)
+    log_path.mkdir(parents=True, exist_ok=True)
+
+    log_format = "[{time:YYYY-MM-DD HH:mm:ss}] | {level: <8} | {name}:{line} - {message}"
+
+    # 移除默认 handler
+    logger.remove()
+
+    # 添加控制台 handler
+    logger.add(
+        sys.stderr,
+        format=log_format,
+        level=level,
+        colorize=True,
+    )
+
+    # 添加文件 handler（带轮转）
+    logger.add(
+        log_path / f"{appname}.log",
+        format=log_format,
+        level=level,
+        rotation=rotation,
+        retention=retention,
+        encoding="utf8",
+    )
+
+    # 拦截标准 logging
+    logging.basicConfig(handlers=[InterceptHandler()], level=0, force=True)
+    for name in logging.root.manager.loggerDict.keys():
+        logging.getLogger(name).handlers = []
+        logging.getLogger(name).propagate = True

agstack-1.0.0/agstack/config/manager.py

@@ -0,0 +1,131 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+import json
+import os
+import tomllib
+from pathlib import Path
+from typing import Any
+
+from .logger import setup_logger
+from .types import AppConfig
+
+
+def _load_config_file(config_path: Path) -> dict[str, Any]:
+    """加载配置文件（容错处理）"""
+    if not config_path.exists():
+        return {}
+
+    try:
+        with open(config_path, "rb") as f:
+            return tomllib.load(f)
+    except Exception:  # noqa
+        print(f"Failed to load config file: {config_path}")
+        return {}
+
+
+def _load_env_overrides(prefix: str = "APP") -> dict[str, Any]:
+    """加载环境变量覆盖配置
+
+    支持格式：
+    - APP_DATABASE_HOST=localhost
+    - APP_WEBAPI_DEBUG=true
+    - APP_MODELS_EMBEDDING_ENGINE=bedrock
+    """
+    config_data = {}
+    prefix = prefix.upper() + "_"
+
+    for key, value in os.environ.items():
+        if key.startswith(prefix):
+            config_key = key[len(prefix) :].lower()
+            _set_nested_value(config_data, config_key, _parse_env_value(value))
+
+    return config_data
+
+
+def _set_nested_value(data: dict[str, Any], key: str, value: Any) -> None:
+    """设置嵌套字典值（支持下划线分隔）"""
+    if "_" in key:
+        parts = key.split("_", 1)
+        if parts[0] not in data:
+            data[parts[0]] = {}
+        _set_nested_value(data[parts[0]], parts[1], value)
+    else:
+        data[key] = value
+
+
+def _parse_env_value(value: str) -> Any:
+    """解析环境变量值（自动类型转换）"""
+    # 布尔值
+    if value.lower() in ("true", "false"):
+        return value.lower() == "true"
+
+    # 数字
+    try:
+        if "." in value:
+            return float(value)
+        return int(value)
+    except ValueError:
+        pass
+
+    # JSON
+    if value.startswith(("{", "[")):
+        try:
+            return json.loads(value)
+        except json.JSONDecodeError:
+            pass
+
+    return value
+
+
+def _determine_log_level(config_data: dict[str, Any]) -> str:
+    """确定日志级别（优先级：环境变量 > debug 模式 > 配置文件）"""
+    # 1. 环境变量优先级最高
+    env_level = os.environ.get("METAMATRIX_LOG_LEVEL")
+    if env_level:
+        level = env_level.upper()
+        if level in ("TRACE", "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"):
+            return level
+
+    # 2. debug 模式强制使用 DEBUG
+    mode = config_data.get("mode", "").lower()
+    if mode == "dev":
+        return "DEBUG"
+
+    # 3. 使用配置文件中的级别
+    return config_data.get("logger", {}).get("level", "INFO")
+
+
+def setup_config(appname: str, envprefix: str = "APP") -> AppConfig:
+    """初始化配置
+
+    Args:
+        appname: 应用名称
+        envprefix: 环境变量前缀
+
+    Returns:
+        AppConfig: 配置实例
+    """
+    approot = Path.cwd()
+    config_path = approot / "config.toml"
+
+    # 1. 加载配置文件（容错）
+    config_data = _load_config_file(config_path)
+
+    # 2. 加载环境变量覆盖
+    env_overrides = _load_env_overrides(envprefix)
+    config_data.update(env_overrides)
+
+    # 3. 设置应用信息
+    config_data.update({"appname": appname, "approot": approot})
+
+    # 4. 确定日志级别（优先级处理）
+    log_level = _determine_log_level(config_data)
+    config_data.setdefault("logger", {})["level"] = log_level
+
+    # 5. 初始化日志（使用字典配置）
+    setup_logger(appname, **config_data["logger"])
+
+    # 8. 创建配置实例（最后验证）
+    config = AppConfig.model_validate(config_data)
+
+    return config