aegis-stack 0.2.0rc2__py3-none-any.whl

aegis/templates/copier-aegis-project/{{ project_slug }}/.copier-answers.yml.jinja

@@ -0,0 +1,21 @@
+# Changes here will be overwritten by Copier; NEVER EDIT MANUALLY
+_commit: {{ _copier_conf.vcs_ref_hash | default('unknown') }}
+_src_path: {{ _copier_conf.src_path }}
+project_name: {{ project_name }}
+project_slug: {{ project_slug }}
+project_description: {{ project_description }}
+author_name: {{ author_name }}
+author_email: {{ author_email }}
+github_username: {{ github_username }}
+version: {{ version }}
+python_version: {{ python_version }}
+include_scheduler: {{ include_scheduler }}
+scheduler_backend: {{ scheduler_backend }}
+scheduler_with_persistence: {{ scheduler_with_persistence }}
+include_worker: {{ include_worker }}
+include_redis: {{ include_redis }}
+include_database: {{ include_database }}
+include_cache: {{ include_cache }}
+include_auth: {{ include_auth }}
+include_ai: {{ include_ai }}
+ai_providers: {{ ai_providers }}

aegis/templates/copier-aegis-project/{{ project_slug }}/.dockerignore

@@ -0,0 +1,71 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments - don't mount host venv into container
+.venv/
+.env/
+venv/
+ENV/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Logs
+*.log
+
+# Temporary files
+*.tmp
+*.temp
+
+# Git
+.git/
+.gitignore
+
+# Documentation build
+site/
+docs/_build/
+
+# Cache
+.cache/
+.mypy_cache/
+.ruff_cache/

aegis/templates/copier-aegis-project/{{ project_slug }}/.env.example.jinja

@@ -0,0 +1,130 @@
+# Aegis Stack Environment Variables Example
+# Copy this file to .env and customize for your environment
+
+# =============================================================================
+# APPLICATION SETTINGS
+# =============================================================================
+
+# Environment: dev, qa, stg, prod
+APP_ENV=dev
+
+# Port to run the webserver on
+PORT=8000
+
+# Logging level: DEBUG, INFO, WARNING, ERROR
+LOG_LEVEL=INFO
+
+# Auto-reload server on code changes (development only)
+AUTO_RELOAD=true
+
+# =============================================================================
+# DOCKER SETTINGS
+# =============================================================================
+
+# Docker image tag (used by docker-compose)
+AEGIS_STACK_TAG=aegis-stack:latest
+
+# Version tag for builds
+AEGIS_STACK_VERSION=dev
+
+# Environment file to use (defaults to .env)
+# AEGIS_STACK_ENV_FILE=.env
+
+# =============================================================================
+# COMPONENT SETTINGS
+# =============================================================================
+
+{%- if include_database %}
+# Database settings
+# DATABASE_URL=sqlite:///./data/app.db  # SQLite database (default)
+# DATABASE_ENGINE_ECHO=false  # Set to true to log all SQL queries (debugging)
+{% endif %}
+
+{% if include_redis or include_cache %}
+# Redis settings
+# For Docker: redis://redis:6379 (default)
+# For local development: redis://localhost:6379
+REDIS_URL=redis://redis:6379
+
+# Override for local CLI commands (when not running in Docker)
+# Uncomment for local development:
+REDIS_URL_LOCAL=redis://localhost:6379
+# REDIS_HOST=redis
+# REDIS_PORT=6379
+# REDIS_PASSWORD=
+
+# Redis connection settings (for high-load scenarios)
+# REDIS_CONN_TIMEOUT=5  # Connection timeout in seconds
+# REDIS_CONN_RETRIES=5  # Number of connection retry attempts
+# REDIS_CONN_RETRY_DELAY=1  # Delay between retries in seconds
+{% endif %}
+
+{%- if include_scheduler %}
+# Scheduler settings
+# SCHEDULER_TIMEZONE=UTC
+# SCHEDULER_MAX_WORKERS=10
+{% endif %}
+
+# API Keys and Secrets (add as needed)
+# SECRET_KEY=your-super-secret-key-here
+# API_KEY=your-api-key-here
+
+{%- if include_ai %}
+# =============================================================================
+# AI SERVICE CONFIGURATION
+# =============================================================================
+
+# AI Service Settings
+AI_ENABLED=true
+AI_PROVIDER=public  # Primary provider: openai, anthropic, google, groq, mistral, cohere, public
+AI_MODEL=auto  # Model to use (PUBLIC provider uses available free models)
+AI_TEMPERATURE=0.7  # Response creativity (0.0-2.0)
+AI_MAX_TOKENS=1000  # Maximum response length
+AI_TIMEOUT_SECONDS=30.0  # Request timeout
+
+# Conversation Management
+AI_MAX_CONVERSATION_LENGTH=50  # Max messages per conversation
+AI_CONVERSATION_TIMEOUT_HOURS=24  # Auto-cleanup old conversations
+
+# Provider API Keys (optional - many offer free tiers)
+# ⚡ PUBLIC provider works immediately without API keys (currently set as default)
+# Get your API keys from:
+# - OpenAI: https://platform.openai.com/api-keys
+# - Anthropic: https://console.anthropic.com/
+# - Google: https://aistudio.google.com/app/apikey
+# - Groq: https://console.groq.com/keys (FREE - Recommended for getting started)
+# - Mistral: https://console.mistral.ai/api-keys/
+# - Cohere: https://dashboard.cohere.com/api-keys
+
+# OPENAI_API_KEY=sk-...
+# ANTHROPIC_API_KEY=sk-ant-...
+# GOOGLE_API_KEY=AI...
+# GROQ_API_KEY=gsk_...  # FREE tier available!
+# MISTRAL_API_KEY=...
+# COHERE_API_KEY=...
+
+# Provider-Specific Notes:
+# - Public: Works immediately without API keys (uses free endpoints, actual model varies)
+# - Groq: Excellent free tier with fast inference (recommended for testing)
+# - Google: Generous free tier with Gemini Flash model
+# - OpenAI: Requires paid account but excellent quality
+# - Anthropic: Requires paid account, very good for reasoning
+# - Mistral: Good open source models, some free options
+# - Cohere: Enterprise focused, limited free tier
+{% endif %}
+
+# =============================================================================
+# DEVELOPMENT OVERRIDES
+# =============================================================================
+
+# Worker auto-reload settings
+# WORKER_WATCH=false  # Disable worker auto-reload (useful for debugging)
+
+{% if include_worker %}
+# Worker health check settings
+# WORKER_HEALTH_CHECK_INTERVAL=15  # Health check interval in seconds (default: 15)
+{% endif %}
+
+# Override for local development
+# Use this to point to local services instead of Docker services
+# DATABASE_HOST=host.docker.internal  # For connecting to host DB from container

aegis/templates/copier-aegis-project/{{ project_slug }}/.gitignore

@@ -0,0 +1,131 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*.so
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Database files and data directory
+data/
+*.db
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db

aegis/templates/copier-aegis-project/{{ project_slug }}/Dockerfile

@@ -0,0 +1,53 @@
+FROM python:3.11-slim
+
+# Install system dependencies and clean up
+RUN apt-get update -y && \
+    apt-get install -y --no-install-recommends \
+      build-essential \
+      ca-certificates \
+      curl \
+    && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
+
+# Install uv with specific version for reproducibility
+RUN pip install --no-cache-dir uv==0.4.18
+
+# Set environment variables
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONPATH=/code \
+    UV_CACHE_DIR=/tmp/uv-cache
+
+WORKDIR /code
+
+# Copy dependency files and README (needed by pyproject.toml)
+COPY pyproject.toml uv.lock README.md /code/
+
+# Install dependencies
+RUN uv sync --all-extras && \
+    rm -rf /tmp/uv-cache
+
+# Copy application code
+COPY . /code
+
+# Make entrypoint executable
+RUN chmod +x /code/scripts/entrypoint.sh
+
+# Set default port as an environment variable
+ARG PORT=8000
+ENV PORT=$PORT
+
+# Expose the port
+EXPOSE $PORT
+
+# Add health check
+HEALTHCHECK --interval=30s --timeout=30s --start-period=5s --retries=3 \
+  CMD curl -f http://localhost:$PORT/health || exit 1
+
+
+# Labels for better container management
+LABEL maintainer="contact@aegis-stack.dev" \
+      version="0.1.0" \
+      description="Aegis Stack - Production-ready async Python foundation"
+
+ENTRYPOINT ["uv", "run", "/code/scripts/entrypoint.sh"]

aegis/templates/copier-aegis-project/{{ project_slug }}/Makefile.jinja

@@ -0,0 +1,236 @@
+# {{ project_name }} - Aegis Stack Project
+# Developer-friendly commands for Docker workflow
+
+#=============================================================================
+# CORE DOCKER COMMANDS
+#=============================================================================
+
+build: ## Build all Docker images (safe, sequential)
+	@echo "🔨 Building Docker images..."
+	@docker compose --profile dev build
+
+serve: ## Run all services (assumes images are built)
+	@echo "🚀 Starting services... (Press Ctrl+C to stop)"
+	@docker compose --profile dev up --remove-orphans
+
+serve-bg: ## Run all services in background
+	@echo "🚀 Starting services in background..."
+	@docker compose --profile dev up -d --remove-orphans
+
+stop: ## Gracefully stop all services
+	@echo "⏹️  Stopping services..."
+	@docker compose --profile dev down --remove-orphans
+
+clean: ## Nuclear cleanup - remove containers, networks, and images
+	@echo "🧹 Nuclear cleanup - removing everything..."
+	@docker compose down --remove-orphans --volumes --rmi all 2>/dev/null || true
+	@docker system prune -f
+
+#=============================================================================
+# DEVELOPER WORKFLOW COMMANDS (the ones you'll actually use)
+#=============================================================================
+
+rebuild: build serve ## Build images and start services
+
+refresh: clean build serve ## Nuclear reset - clean everything and rebuild
+
+restart: stop serve ## Quick restart (no rebuild)
+
+#=============================================================================
+# DEBUGGING AND LOGS
+#=============================================================================
+
+logs: ## Follow logs from all services
+	@echo "📋 Following all service logs..."
+	@docker compose logs -f
+
+logs-web: ## Follow webserver logs only
+	@echo "📋 Following webserver logs..."
+	@docker compose logs -f webserver
+
+logs-worker: ## Follow worker logs only
+	@echo "📋 Following worker logs..."
+	@docker compose logs -f worker-system worker-load-test
+
+logs-redis: ## Follow Redis logs only
+	@echo "📋 Following Redis logs..."
+	@docker compose logs -f redis{% if include_scheduler %}
+
+logs-scheduler: ## Follow scheduler logs only
+	@echo "📋 Following scheduler logs..."
+	@docker compose logs -f scheduler{% endif %}
+
+shell: ## Open shell in webserver container
+	@echo "🐚 Opening shell in webserver container..."
+	@docker compose exec webserver /bin/bash
+
+shell-worker: ## Open shell in worker container
+	@echo "🐚 Opening shell in worker container..."
+	@docker compose exec worker-system /bin/bash
+
+ps: ## Show running containers
+	@echo "📊 Docker containers status:"
+	@docker compose ps
+
+#=============================================================================
+# REDIS DEBUGGING
+#=============================================================================
+
+redis-cli: ## Connect to Redis CLI
+	@echo "🔧 Connecting to Redis CLI..."
+	@docker compose exec redis redis-cli
+
+redis-stats: ## Show Redis memory and stats
+	@echo "📊 Redis statistics:"
+	@docker compose exec redis redis-cli info memory
+
+redis-keys: ## Show all Redis keys
+	@echo "🔑 Redis keys:"
+	@docker compose exec redis redis-cli keys "*"
+
+redis-reset: ## Clear all Redis data
+	@echo "🔄 Clearing all Redis data..."
+	@docker compose exec redis redis-cli flushall
+
+#=============================================================================
+# HEALTH AND TESTING
+#=============================================================================
+
+health: ## Check system health status
+	@echo "🩺 Checking system health..."
+	@uv run {{ project_slug }} health status
+
+health-detailed: ## Detailed system health information
+	@echo "🩺 Detailed system health..."
+	@uv run {{ project_slug }} health status --detailed
+
+health-json: ## System health as JSON
+	@uv run {{ project_slug }} health status --json
+
+health-probe: ## Health probe (exits 1 if unhealthy)
+	@uv run {{ project_slug }} health probe
+
+test: ## Run tests locally
+	@echo "🧪 Running tests..."
+	@uv run pytest
+
+test-verbose: ## Run tests with verbose output
+	@echo "🧪 Running tests (verbose)..."
+	@uv run pytest -v
+
+#=============================================================================
+# CODE QUALITY (local development tools)
+#=============================================================================
+
+lint: ## Check code style with ruff
+	@echo "🔍 Running linting..."
+	@uv run ruff check .
+
+fix: ## Auto-fix linting and formatting issues
+	@echo "🔧 Auto-fixing code issues..."
+	@uv run ruff check . --fix
+	@uv run ruff format .
+
+format: ## Format code with ruff
+	@echo "💄 Formatting code..."
+	@uv run ruff format .
+
+typecheck: ## Run type checking with ty
+	@echo "🔍 Running type checking..."
+	@uv run ty check
+
+check: lint typecheck test ## Run all code quality checks
+	@echo "✅ All checks completed successfully!"
+
+#=============================================================================
+# PROJECT MANAGEMENT
+#=============================================================================
+
+install: ## Install/sync dependencies with uv
+	@echo "📦 Installing dependencies..."
+	@uv sync --all-extras
+
+deps-update: ## Update dependencies
+	@echo "📦 Updating dependencies..."
+	@uv sync --upgrade
+
+clean-cache: ## Clean Python cache files
+	@echo "🧹 Cleaning Python cache files..."
+	@find . -type d -name "__pycache__" -exec rm -rf {} +
+	@find . -type f -name "*.pyc" -delete
+
+#=============================================================================
+# DOCUMENTATION
+#=============================================================================
+
+docs-serve: ## Serve documentation locally (http://localhost:8001)
+	@echo "📚 Serving documentation on http://localhost:8001"
+	@uv run mkdocs serve --dev-addr 0.0.0.0:8001
+
+docs-build: ## Build static documentation
+	@echo "📚 Building documentation..."
+	@uv run mkdocs build
+
+{% if include_database %}#=============================================================================
+# DATABASE MIGRATIONS
+#=============================================================================
+
+migrate: ## Apply database migrations
+	@echo "🗃️  Applying database migrations..."
+	@docker compose exec webserver uv run alembic -c alembic/alembic.ini upgrade head
+
+migrate-check: ## Check migration status
+	@echo "🔍 Checking migration status..."
+	@docker compose exec webserver uv run alembic -c alembic/alembic.ini current
+
+migrate-history: ## Show migration history
+	@echo "📜 Migration history:"
+	@docker compose exec webserver uv run alembic -c alembic/alembic.ini history --verbose
+
+migrate-reset: ## Reset database (WARNING: destructive)
+	@echo "⚠️  This will destroy all data in the database!"
+	@read -p "Are you sure? Type 'yes' to continue: " confirm && [ "$$confirm" = "yes" ] || exit 1
+	@docker compose exec webserver uv run alembic -c alembic/alembic.ini downgrade base
+	@docker compose exec webserver uv run alembic -c alembic/alembic.ini upgrade head
+	@echo "✅ Database reset complete"
+
+{% endif %}
+
+#=============================================================================
+# WORKER DEBUGGING (arq)
+#=============================================================================
+
+worker-test: ## Test workers in burst mode (process and exit)
+	@echo "🧪 Testing system worker in burst mode..."
+	@uv run python -m arq app.components.worker.queues.system.WorkerSettings --burst
+
+#=============================================================================
+# HELP AND INFO
+#=============================================================================
+
+status: ## Show current system status
+	@echo "📊 Current system status:"
+	@echo
+	@echo "🐳 Docker containers:"
+	@docker compose ps || echo "No containers running"
+	@echo
+	@echo "📦 Dependencies:"
+	@uv pip list | head -20 || echo "Dependencies not installed"
+
+help: ## Show this help message
+	@echo "{{ project_name }} development commands:"
+	@echo
+	@echo "🚀 WORKFLOW COMMANDS (start here):"
+	@echo "  make refresh      - Nuclear reset (clean + build + serve)"
+	@echo "  make rebuild      - Build and serve"
+	@echo "  make restart      - Quick restart"
+	@echo
+	@echo "🔧 CORE COMMANDS:"
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
+	@echo
+	@echo "💡 TIP: Use 'make refresh' when everything is broken!"
+
+.PHONY: build serve stop clean rebuild refresh restart logs logs-web logs-worker logs-redis{% if include_scheduler %} logs-scheduler{% endif %} shell shell-worker ps redis-cli redis-stats redis-keys redis-reset health health-detailed health-json health-probe test test-verbose lint fix format typecheck check install deps-update clean-cache docs-serve docs-build{% if include_database %} migrate migrate-check migrate-history migrate-reset{% endif %} worker-test status help
+
+# Default target - show help
+.DEFAULT_GOAL := help