Arclio Rules 🚀

Arclio Rules is a FastAPI-based service that implements rule processing using the FastMCP framework. It provides a robust and efficient system for managing and executing business rules in a microservices architecture.

Overview

Arclio Rules is built with Python 3.12+ and leverages modern async capabilities to provide high-performance rule processing. The service can be run either with session management or in a stateless mode using standard I/O.

Features

• FastAPI-based REST API
• Built on FastMCP framework for efficient rule processing
• Redis integration for rule indexing/storage and querying
• Git integration for version control of rules
• Support for both session-based and stateless operation modes
• Frontmatter parsing capabilities
• Comprehensive logging with Loguru
• UV package management for fast, reliable dependency handling
• Make-based workflow automation

Prerequisites

• Python 3.12.8 or higher
• UV package manager
• Docker (optional, for containerized deployment)
• Age (for secrets management)

Installation

1. Clone the repository:

git clone https://github.com/fisseha-estifanos/arclio-rules.git
cd arclio-rules

2. Install dependencies using UV:

make install

This will:

• Install project dependencies using UV
• Set up the development environment
• Sync all dependencies

Environment Setup

1. Initialize SOPS for secret management:

make init-key

2. Create your environment file:

# Copy the example environment file
cp .env.example .env

# Decrypt existing secrets (if you have access)
make decrypt

Required Environment Variables:

# GitHub API Configuration
GITHUB_TOKEN="add your GH PAT here"
GITHUB_ORG="add your GH Organization here"
REPO_NAME="add your repo that holds the rules here"
REDIS_HOST="localhost"
REDIS_PORT="6379"
REDIS_PASSWORD="add your password here if there is one"

Default Environmental Variables (No need to modify):

# Server Configuration
PORT=8000                     # Application port
HOST=0.0.0.0                  # Host to bind to

# Additional Settings
LOG_LEVEL=INFO                # Logging level (DEBUG, INFO, WARNING, ERROR)
ENVIRONMENT=development       # Application environment

Usage

The service can be run in two modes:

Stateless Mode (using stdio)

source .env
arclio-rules

Development Mode

make run-dev

Adding mcp-server on Arclio

Add these two configuration JSON templates to be able to add arclio-rules to Arclio as an mcp-server.

Configuration Template JSON

{
  "mcpServers": {
    "arclio-rules": {
      "command": "uvx",
      "args": [
        "--from",
        "arclio-rules",
        "arclio-rules"
      ],
      "env": {
        "GITHUB_TOKEN": "{{github_token}}",
        "GITHUB_ORG": "{{github_org}}",
        "RULES_REPO_NAME": "{{rules_repo_name}}",
        "PORT": "{{port}}",
        "HOST": "{{host}}",
        "LOG_LEVEL": "{{log_level}}",
        "ENVIRONMENT": "{{environment}}",
        "REDIS_HOST": "{{redis_host}}",
        "REDIS_PORT": "{{redis_port}}",
        "REDIS_PASSWORD": "{{redis_password}}"
      }
    }
  }
}

UI Schema JSON

{
  "sections": [
    {
      "title": "GitHub Configuration",
      "type": "instructions",
      "content": "Configure GitHub access for rule repository management"
    },
    {
      "title": "GitHub Personal Access Token",
      "type": "password",
      "field": "github_token"
    },
    {
      "title": "GitHub Organization",
      "type": "text",
      "field": "github_org"
    },
    {
      "title": "Repository Name",
      "type": "text",
      "field": "rules_repo_name"
    },
    {
      "title": "Server Configuration",
      "type": "instructions",
      "content": "Configure server settings"
    },
    {
      "title": "Application Port",
      "type": "text",
      "field": "port"
    },
    {
      "title": "Host Address",
      "type": "text",
      "field": "host"
    },
    {
      "title": "Log Level",
      "type": "text",
      "field": "log_level"
    },
    {
      "title": "Environment",
      "type": "text",
      "field": "environment"
    },
    {
      "title": "REDIS_HOST",
      "type": "text",
      "field": "redis_host"
    },
    {
      "title": "REDIS_PORT",
      "type": "text",
      "field": "redis_port"
    },
    {
      "title": "REDIS_PASSWORD",
      "type": "password",
      "field": "redis_password"
    }
  ]
}

Development Commands

The project includes a comprehensive Makefile for common development tasks:

# Development
make run-dev         # Run development server
make install         # Install dependencies
make build           # Build the project
make publish         # Publish the project to pypi

# Code Quality
make lint            # Run Ruff linter
make type-check      # Run Pyright type checker
make format          # Format code with Ruff
make pre-commit      # Run all code quality checks

# Secrets Management
make init-key        # Generate new age key for SOPS
make encrypt         # Encrypt .env to .env.sops
make decrypt         # Decrypt .env.sops to .env
make add-recipient   # Add new public key (make add-recipient KEY=age1...)

Project Structure

arclio-rules/ ├── .github/ │ └── workflows/ │ └── linting-and-pyright.yml ├── .gitignore ├── LICENSE ├── Makefile ├── README.md ├── pyproject.toml ├── pyrightconfig.json ├── src/ │ └── arclio_rules/ │ ├── init.py │ ├── main.py │ ├── datamodels/ │ │ ├── client_schema.py │ │ └── rule_schema.py │ ├── inhouse_rules/ │ │ └── example_rule.py │ ├── main.py │ ├── routes/ │ │ └── rules.py │ └── services/ │ ├── rule_indexing_service.py │ ├── rule_resolution_service.py │ └── rule_storage_service.py ├── tests/ └── .env.example

Configuration

The project uses various configuration files:

• pyproject.toml: Project metadata and dependencies
• pyrightconfig.json: Python type checking configuration
• .sops.yaml: Secrets management configuration
• docker-compose.yml: Container orchestration settings
• .env: Environment variables (created from .env.example)

Development

Package Management with UV

The project uses UV for dependency management, offering:

• Faster package installation
• Reliable dependency resolution
• Consistent environments across development and production
• Integration with virtual environments

Code Quality Tools

The project uses several tools to maintain code quality:

• Ruff: For linting and formatting
  • Enforces PEP 8 style guide
  • Manages import sorting
  • Checks docstring formatting (Google style)
• MyPy: For static type checking
• Pytest: For testing (with async support)

Linting Rules

The project enforces specific linting rules through Ruff, including:

• PEP 8 compliance (E)
• PyFlakes checks (F)
• Import sorting (I)
• Docstring formatting (D)

Dependencies

Key dependencies include:

• fastapi: Web framework
• fastmcp: MCP framework integration
• redis: Search and storage
• aiohttp: Async HTTP client
• pydantic: Data validation
• uvicorn: ASGI server

License

[Add your license information here]

Contributing

[Add contribution guidelines here]