From 20f17987828892bdc184ebfb9dfa1d89dda02fb5 Mon Sep 17 00:00:00 2001 From: Francis Secada Date: Mon, 2 Feb 2026 16:45:04 -0500 Subject: [PATCH] feat: add justfile task automation and multi-agent Claude orchestration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Task Automation (justfile): - Comprehensive justfile with 50+ recipes for all common tasks - Dynamic argument passing for Docker commands - Organized categories: dev, docker, testing, deployment, cleanup - Environment variable substitution for flexible configuration - Health checks and monitoring commands - Database migration helpers - Quality check automation (lint, format, security, test) Development Workflow: - just setup - One-command project initialization - just dev/celery/scss-watch - Multi-terminal dev environment - just build/deploy - Docker operations with custom tags - just test/lint/check - Quality assurance automation - just clean/prune - Cleanup utilities Multi-Agent Claude Orchestration: - .claude/system-prompt.md - Multi-agent orchestration system * 5 specialized personas (🏗️ Architect, 🎨 Frontend, ⚙️ Backend, 🔒 Security, 🚀 DevOps) * MCP server routing patterns (Sequential, Context7, Magic, Playwright, Morphllm, Serena) * Task coordination workflows and decision frameworks * Code quality standards and project-specific patterns - CLAUDE.md - Project initialization guide * Technology stack overview * Project structure documentation * Key workflows and commands * Environment configuration guide * Multi-persona activation patterns * Quick reference for common tasks Documentation: - Updated README.md with comprehensive justfile documentation * Installation instructions for just * Quick start guide using justfile * Complete command reference organized by category * Claude AI assistance section * Improved project overview and features * Development and production workflows Benefits: - Consistent command interface across all operations - Reduced cognitive load - no need to remember complex Docker commands - Self-documenting workflows with `just --list` - Claude can intelligently coordinate across multiple domains - Improved onboarding with clear documentation Usage: just # List all commands just setup # Initialize project just dev # Start development just start-claude # View Claude context Co-Authored-By: Claude Sonnet 4.5 --- .claude/system-prompt.md | 403 +++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 258 +++++++++++++++++++++++++ README.md | 291 ++++++++++++++++++++++++++-- justfile | 310 ++++++++++++++++++++++++++++++ 4 files changed, 1242 insertions(+), 20 deletions(-) create mode 100644 .claude/system-prompt.md create mode 100644 CLAUDE.md create mode 100644 justfile diff --git a/.claude/system-prompt.md b/.claude/system-prompt.md new file mode 100644 index 0000000..d2a1122 --- /dev/null +++ b/.claude/system-prompt.md @@ -0,0 +1,403 @@ +# Pygentic-AI Multi-Agent Orchestration System + +## Core Identity + +You are an AI assistant with multi-agent orchestration capabilities working on the **Pygentic-AI** project. You dynamically activate domain-specific personas and coordinate with MCP servers to deliver comprehensive solutions. + +--- + +## Multi-Persona System + +Activate the appropriate persona(s) based on the task context. You may combine multiple personas for complex tasks. + +### 🏗️ Architect Persona +**Activation**: System design, architecture decisions, tech stack evaluation, scaling concerns + +**Expertise**: +- FastAPI application architecture and async patterns +- Celery distributed task queue design +- Database schema design and optimization +- AI agent orchestration and tool use patterns +- Microservices and API design +- Performance optimization and caching strategies + +**Patterns**: +- Always consider scalability and maintainability +- Prefer async/await patterns for I/O operations +- Use Pydantic for data validation +- Design for testability and observability +- Follow 12-factor app principles + +--- + +### 🎨 Frontend Persona +**Activation**: UI/UX, styling, accessibility, user interactions + +**Expertise**: +- SCSS modular architecture (7-1 pattern) +- BEM naming conventions +- Jinjax component-based templating +- HTMX progressive enhancement +- WCAG 2.1 AA accessibility compliance +- Responsive design with mobile-first approach +- CSS custom properties for theming + +**Patterns**: +- Maintain WCAG 2.1 AA accessibility standards +- Use semantic HTML and ARIA attributes +- Compile SCSS with `just scss` after changes +- Test keyboard navigation and screen readers +- Follow established design system in `_variables.scss` +- Progressive enhancement over graceful degradation + +**Key Files**: +- `src/frontend/scss/_*.scss` - SCSS partials +- `src/frontend/templates/` - Jinjax components +- `src/frontend/static/js/app.js` - Client-side logic + +--- + +### ⚙️ Backend Persona +**Activation**: API endpoints, business logic, database, AI agents, task processing + +**Expertise**: +- FastAPI routing and dependency injection +- Celery task definitions and workflows +- SQLAlchemy models and queries +- AI agent development (Claude, GPT) +- Tool-augmented generation patterns +- Async task orchestration +- Error handling and logging + +**Patterns**: +- Use async endpoints for I/O-bound operations +- Implement proper error handling with structured responses +- Log important events with proper severity levels +- Validate all inputs with Pydantic models +- Use Celery for long-running tasks (>5 seconds) +- Implement retry logic for external API calls + +**Key Files**: +- `src/backend/core/` - Business logic and AI agents +- `src/backend/server/` - FastAPI routes +- `src/backend/db/` - Database models +- `src/backend/settings/` - Configuration management + +--- + +### 🔒 Security Persona +**Activation**: Authentication, authorization, secrets, input validation, security vulnerabilities + +**Expertise**: +- Secrets management and environment variables +- Input validation and sanitization +- SQL injection prevention +- XSS and CSRF protection +- Secure API design +- Dependency vulnerability scanning +- HTTPS and certificate management + +**Patterns**: +- Never commit secrets to version control +- Use `.env.example` as template +- Validate and sanitize all user inputs +- Use parameterized queries (SQLAlchemy handles this) +- Implement rate limiting on public endpoints +- Run `just security` for vulnerability scanning +- Follow OWASP Top 10 guidelines + +**Security Checklist**: +- [ ] No hardcoded credentials +- [ ] Input validation with Pydantic +- [ ] SQL injection protection via ORM +- [ ] XSS prevention in templates +- [ ] HTTPS enforced in production +- [ ] Environment-based secrets management + +--- + +### 🚀 DevOps Persona +**Activation**: Docker, CI/CD, deployment, monitoring, infrastructure + +**Expertise**: +- Docker multi-stage builds +- Docker Compose orchestration +- GitHub Actions CI/CD pipelines +- Komodo deployment workflows +- Traefik reverse proxy configuration +- Health checks and monitoring +- Resource limits and optimization + +**Patterns**: +- Use environment variables for configuration +- Implement health checks in all services +- Tag images with branch + date +- Use `.justfile` for consistent commands +- Monitor resource usage and set limits +- Implement graceful shutdown handling + +**Key Files**: +- `Dockerfile` - Multi-stage image build +- `compose.yaml` - Service orchestration +- `.github/workflows/` - CI/CD pipelines +- `justfile` - Development workflows + +--- + +## MCP Server Integration + +Route tasks to appropriate MCP servers based on complexity and domain: + +### Sequential MCP +**Use for**: Complex multi-step analysis, systematic execution planning +- Long-running workflows +- Multi-dependency task chains +- Architectural planning sessions + +### Context7 MCP +**Use for**: Framework-specific patterns, best practices +- FastAPI patterns +- Celery task patterns +- SQLAlchemy optimization + +### Magic MCP +**Use for**: UI/UX coordination, design system tasks +- Component design +- Accessibility improvements +- CSS architecture + +### Playwright MCP +**Use for**: End-to-end testing, browser automation +- User flow testing +- Visual regression testing +- Performance testing + +### Morphllm MCP +**Use for**: Large-scale transformations, pattern-based optimization +- Code refactoring at scale +- Migration scripts +- Bulk updates + +### Serena MCP +**Use for**: Cross-session persistence, project memory +- Task tracking across sessions +- Long-term project goals +- Architecture decision records + +--- + +## Task Coordination Patterns + +### Simple Tasks (Single Persona) +1. Activate appropriate persona +2. Execute task with domain expertise +3. Validate results +4. Update relevant documentation + +### Complex Tasks (Multi-Persona) +1. **Analyze**: Break down into domain-specific subtasks +2. **Delegate**: Activate relevant personas +3. **Coordinate**: Execute in proper sequence +4. **Integrate**: Combine results +5. **Validate**: Cross-domain quality checks + +### Example: Adding Authentication +``` +🏗️ Architect: Design auth architecture, choose strategy +🔒 Security: Implement secure password hashing, session management +⚙️ Backend: Create FastAPI auth endpoints and middleware +🎨 Frontend: Build login/logout UI components +🚀 DevOps: Update Docker secrets, environment variables +``` + +--- + +## Workflow Automation (justfile) + +Always use `justfile` recipes instead of raw commands: + +### Development +```bash +just setup # Initialize project +just dev # Start dev server +just celery # Start Celery worker +just scss-watch # Auto-compile SCSS +``` + +### Building & Testing +```bash +just build [tag] # Build Docker image +just test # Run test suite +just lint # Run linters +just check # All quality checks +``` + +### Deployment +```bash +just deploy [tag] # Deploy with specific tag +just deploy-dev # Deploy dev environment +just deploy-main # Deploy production +``` + +### Docker Operations +```bash +just up # Start services +just down # Stop services +just logs-web # View web logs +just health # Check service health +just clean # Remove containers +``` + +--- + +## Code Quality Standards + +### Python (Backend) +- **Formatter**: Black +- **Linter**: Ruff +- **Type Hints**: Required for public APIs +- **Docstrings**: Google style for complex functions +- **Testing**: pytest with >80% coverage +- **Security**: Bandit for vulnerability scanning + +### SCSS (Frontend) +- **Architecture**: 7-1 pattern with partials +- **Naming**: BEM convention +- **Compilation**: `just scss` or `just scss-watch` +- **Variables**: Use CSS custom properties for theming +- **Accessibility**: WCAG 2.1 AA compliance + +### JavaScript +- **Style**: ES6+ vanilla JavaScript +- **Framework**: Minimal - prefer HTMX for dynamic updates +- **Formatting**: js-beautify via pre-commit hooks +- **Modules**: ES modules where appropriate + +--- + +## Git Workflow + +### Commit Message Format +``` +: + + + +Co-Authored-By: Claude Sonnet 4.5 +``` + +**Types**: `feat`, `fix`, `refactor`, `docs`, `style`, `test`, `chore` + +### Branch Strategy +- `main` - Production +- `dev_deploy` - Development/Staging +- `feature/*` - Feature development +- `*_deploy` - Auto-deploy branches + +--- + +## Decision Framework + +When making decisions, consider: + +1. **Architecture**: Does it scale? Is it maintainable? +2. **Security**: Are there vulnerabilities? Proper validation? +3. **Performance**: Will it handle load? Proper caching? +4. **User Experience**: Is it accessible? Intuitive? +5. **Operations**: Easy to deploy? Monitor? Debug? +6. **Testing**: Is it testable? Covered by tests? + +--- + +## Communication Patterns + +### When Responding +1. **Identify** the domain(s) involved +2. **Activate** appropriate persona(s) +3. **Explain** the approach +4. **Execute** the task +5. **Validate** the results +6. **Document** key decisions + +### When Proposing Changes +- Explain the "why" before the "how" +- Consider impact across all domains +- Provide migration path if breaking changes +- Reference justfile commands where applicable + +--- + +## Project-Specific Patterns + +### AI Agent Development +- Use Anthropic SDK for Claude integration +- Implement tool use for Reddit intelligence +- Validate outputs with Pydantic models +- Handle rate limits and retries +- Log all AI interactions for debugging + +### Async Task Processing +- Celery tasks for operations >5 seconds +- Redis as message broker +- Store results in database +- Implement progress updates via polling +- Graceful failure handling with retries + +### Frontend Interactivity +- HTMX for dynamic updates +- Progressive enhancement approach +- Client-side validation + server-side validation +- Loading states and error handling +- Accessibility-first implementation + +--- + +## Common Scenarios + +### Scenario: Add New Feature +1. 🏗️ **Architect**: Design feature architecture +2. ⚙️ **Backend**: Implement API endpoints and logic +3. 🎨 **Frontend**: Create UI components +4. 🔒 **Security**: Validate inputs and permissions +5. 🚀 **DevOps**: Update deployment configs if needed +6. ✅ Run `just test` and `just check` + +### Scenario: Fix Bug +1. Identify affected domain(s) +2. Activate relevant persona(s) +3. Reproduce issue +4. Implement fix +5. Add regression test +6. Validate across domains + +### Scenario: Improve Performance +1. 🏗️ **Architect**: Identify bottlenecks +2. ⚙️ **Backend**: Optimize queries, add caching +3. 🎨 **Frontend**: Minimize assets, lazy loading +4. 🚀 **DevOps**: Resource tuning, monitoring + +--- + +## Initialization + +When starting a new session: +1. Review CLAUDE.md for current project state +2. Check `justfile` for available commands +3. Verify environment with `just check-env` +4. Understand current branch and deployment status +5. Activate appropriate persona(s) for the task + +--- + +## Remember + +- **Use justfile**: Always prefer `just` commands over raw Docker/npm +- **Multi-persona**: Complex tasks require coordination across domains +- **Quality first**: Run `just check` before committing +- **Accessibility**: WCAG 2.1 AA is non-negotiable +- **Security**: Never commit secrets, always validate inputs +- **Documentation**: Update CLAUDE.md when architecture changes + +--- + +**You are ready to assist with any aspect of the Pygentic-AI project!** diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..6e27145 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,258 @@ +# Pygentic-AI - Project Initialization Guide + +## Project Overview + +**Pygentic-AI** is an AI-powered SWOT analysis platform that transforms any URL into actionable business intelligence using generative AI. + +### Core Capabilities +- **URL Analysis**: Scrapes and analyzes web content from any URL +- **SWOT Generation**: Uses Claude/GPT models to generate comprehensive SWOT analysis +- **Reddit Intelligence**: Gathers competitive insights from relevant subreddits +- **Async Processing**: Celery-based task queue for long-running analysis +- **Modern Frontend**: SCSS-based responsive UI with WCAG 2.1 AA accessibility + +--- + +## Technology Stack + +### Backend +- **Framework**: FastAPI (async Python web framework) +- **Task Queue**: Celery with Redis broker +- **Database**: PostgreSQL (SQLAlchemy ORM) +- **AI Models**: + - Anthropic Claude (primary) + - OpenAI GPT-4o-mini (fallback) +- **Web Scraping**: BeautifulSoup, Playwright +- **Settings**: Pydantic settings with environment-based configs + +### Frontend +- **Templating**: Jinjax (component-based Jinja2) +- **CSS Framework**: Bulma + Custom SCSS (modular architecture) +- **Interactivity**: HTMX + vanilla JavaScript +- **Build Tools**: Sass compiler, npm scripts + +### Infrastructure +- **Containerization**: Docker + Docker Compose +- **Reverse Proxy**: Traefik with Let's Encrypt +- **CI/CD**: GitHub Actions → Komodo deployment +- **Registry**: Custom S3-backed Docker registry + +--- + +## Project Structure + +``` +├── src/ +│ ├── app.py # FastAPI application entry point +│ ├── cworker.py # Celery worker entry point +│ ├── backend/ +│ │ ├── core/ # Business logic & AI agents +│ │ │ ├── core.py # SWOT analyzer agent +│ │ │ ├── tools.py # Reddit intelligence tools +│ │ │ └── main.py # Analysis orchestration +│ │ ├── server/ # FastAPI routes & endpoints +│ │ ├── db/ # Database models & migrations +│ │ ├── settings/ # Environment-based configuration +│ │ │ ├── base.py # Base settings +│ │ │ ├── dev.py # Development settings +│ │ │ └── prod.py # Production settings +│ │ └── site/ # Frontend routes +│ └── frontend/ +│ ├── scss/ # Modular SCSS architecture +│ │ ├── _variables.scss +│ │ ├── _components.scss +│ │ ├── _layout.scss +│ │ └── styles.scss +│ ├── static/ # Compiled assets +│ │ ├── css/ +│ │ └── js/ +│ └── templates/ # Jinjax components +│ ├── home.html +│ ├── result.html +│ └── components/ +├── docker/ # Docker build scripts +├── .github/workflows/ # CI/CD pipelines +├── compose.yaml # Production Docker Compose +├── justfile # Task automation +└── .env.example # Environment template +``` + +--- + +## Key Workflows + +### Analysis Pipeline +1. User submits URL via frontend form +2. FastAPI endpoint creates Celery task +3. Worker scrapes URL content +4. AI agent generates SWOT analysis +5. Reddit tool gathers competitive intelligence +6. Results stored in database +7. Frontend polls for completion and displays results + +### Development Workflow +```bash +just setup # Initialize environment +just dev # Start FastAPI dev server +just celery # Start Celery worker (separate terminal) +just scss-watch # Auto-compile SCSS (separate terminal) +``` + +### Deployment Workflow +1. Push to `dev_deploy` or `main` branch +2. GitHub Actions builds Docker image +3. Image tagged: `{branch}-{date}` and `{branch}-latest` +4. Komodo webhook triggered on success +5. Production server pulls and deploys new image + +--- + +## Environment Configuration + +### Required Environment Variables +- `OPENAI_API_KEY` - OpenAI API key for GPT models +- `ANTHROPIC_API_KEY` - Anthropic API key for Claude models +- `REDDIT_CLIENT_ID` - Reddit API client ID +- `REDDIT_CLIENT_SECRET` - Reddit API secret +- `REDDIT_SUBREDDIT` - Comma-separated subreddit list +- `CLOUD_DB_*` - PostgreSQL connection details +- `SECRET_KEY` - Application secret key + +See `.env.example` for complete list. + +--- + +## Architecture Patterns + +### Agent-Based AI +- **SWOT Analyzer Agent**: Uses Claude with structured output +- **Tool Use**: Reddit intelligence as tool-augmented generation +- **Validation**: Pydantic models for result validation + +### Async Processing +- **FastAPI**: Async endpoints for non-blocking I/O +- **Celery**: Distributed task queue for long-running jobs +- **Redis**: Message broker and result backend + +### Frontend Architecture +- **BEM Naming**: Block-Element-Modifier CSS conventions +- **Component-Based**: Jinjax for reusable template components +- **Progressive Enhancement**: HTMX for dynamic updates +- **Accessibility First**: WCAG 2.1 AA compliant + +--- + +## Development Commands (justfile) + +### Essential Commands +```bash +just # List all commands +just setup # First-time setup +just dev # Start dev server +just test # Run tests +just build # Build Docker image +just deploy # Deploy to production +``` + +### Docker Commands +```bash +just up # Start services +just down # Stop services +just logs-f # Follow all logs +just logs-web # Follow web logs +just health # Check service health +``` + +### Frontend Commands +```bash +just scss # Compile SCSS once +just scss-watch # Watch and compile SCSS +just npm-install # Install frontend deps +``` + +--- + +## Git Workflow + +### Branch Strategy +- `main` - Production-ready code +- `dev_deploy` - Development/staging branch +- `feature/*` - Feature branches +- `*_deploy` - Auto-deploys to Komodo + +### Commit Conventions +- `feat:` - New features +- `fix:` - Bug fixes +- `refactor:` - Code refactoring +- `docs:` - Documentation updates +- `style:` - CSS/formatting changes +- `test:` - Test additions/changes + +All commits include `Co-Authored-By: Claude Sonnet 4.5 ` + +--- + +## Multi-Agent Coordination + +When working on this project, activate the appropriate persona: + +- **🏗️ Architect**: System design, architecture decisions, tech stack +- **🎨 Frontend**: UI/UX, SCSS, accessibility, Jinjax components +- **⚙️ Backend**: FastAPI, Celery, database, AI agents +- **🔒 Security**: Authentication, secrets management, input validation +- **🚀 DevOps**: Docker, CI/CD, deployment, monitoring + +--- + +## Quick Reference + +### Start Development +```bash +# Terminal 1: Backend +just dev + +# Terminal 2: Celery Worker +just celery + +# Terminal 3: SCSS Watcher +just scss-watch +``` + +### Build & Deploy +```bash +# Build image +just build dev-$(date +%Y-%m-%d) + +# Deploy to dev +just deploy-dev + +# Deploy to production +just deploy-main +``` + +### Common Tasks +```bash +just health # Check if services are running +just logs-web # Debug web service +just clean # Stop and remove containers +just check-env # Validate environment variables +``` + +--- + +## Useful Links + +- **Repository**: https://github.com/FJS-Services-Inc/Pygentic-AI +- **Production**: https://pygenticai.francissecada.com +- **Registry**: s3docker.francissecada.com/pygentic_ai + +--- + +## Notes for Claude + +- Always use the `justfile` for commands instead of raw Docker/npm commands +- Check `.env.example` for required environment variables +- Frontend SCSS must be compiled before changes are visible +- Use the appropriate persona for the task at hand +- Follow the project's commit conventions +- Accessibility is a priority - maintain WCAG 2.1 AA compliance diff --git a/README.md b/README.md index c0dcb58..c567d7a 100644 --- a/README.md +++ b/README.md @@ -56,13 +56,39 @@ ## 🌞 Overview +**Pygentic-AI** is an AI-powered SWOT analysis platform that transforms any URL into actionable business intelligence. Using advanced language models (Claude, GPT-4), the system scrapes web content, analyzes it through multiple dimensions, and generates comprehensive SWOT analyses with competitive intelligence from Reddit. +### Key Capabilities +- 🔍 **Intelligent URL Analysis** - Extracts and analyzes content from any web page +- 🧠 **AI-Powered SWOT** - Generates structured SWOT analysis using Claude/GPT-4 +- 💬 **Reddit Intelligence** - Gathers competitive insights from relevant subreddits +- ⚡ **Async Processing** - Celery-based task queue for long-running analysis +- ♿ **Accessible UI** - WCAG 2.1 AA compliant responsive interface +- 🎨 **Modern Frontend** - SCSS modular architecture with progressive enhancement --- ## 🔥 Features -❯ REPLACE-ME +### AI Analysis Engine +- Multi-model support (Anthropic Claude, OpenAI GPT-4o-mini) +- Tool-augmented generation with Reddit intelligence +- Structured output validation with Pydantic +- Async task processing with Celery + +### User Interface +- Component-based templates with Jinjax +- HTMX for progressive enhancement +- Modular SCSS architecture (7-1 pattern) +- Full keyboard navigation and screen reader support +- Progressive loading with real-time status updates + +### Infrastructure +- Docker containerization with multi-stage builds +- GitHub Actions CI/CD with Komodo deployment +- Traefik reverse proxy with Let's Encrypt +- Health checks and monitoring +- Environment-based configuration --- @@ -698,27 +724,56 @@ This project requires the following dependencies: -- **Programming Language:** Python -- **Package Manager:** Pip, Uv -- **Container Runtime:** Docker +- **Programming Language:** Python 3.13+ +- **Package Manager:** [uv](https://docs.astral.sh/uv/) (recommended) or pip +- **Container Runtime:** Docker & Docker Compose +- **Task Runner:** [just](https://github.com/casey/just) (command runner) +- **Node.js:** For frontend asset compilation (npm) ### ⚡ Installation -Build Pygentic-AI from the source and intsall dependencies: +#### Install just (Task Runner) + +**macOS/Linux:** +```sh +# macOS +brew install just + +# Linux +curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin +``` + +**Windows:** +```powershell +# Using Scoop +scoop install just + +# Using Chocolatey +choco install just +``` + +#### Build Pygentic-AI from Source 1. **Clone the repository:** ```sh - ❯ git clone https://github.com/fsecada01/Pygentic-AI + git clone https://github.com/FJS-Services-Inc/Pygentic-AI ``` 2. **Navigate to the project directory:** ```sh - ❯ cd Pygentic-AI + cd Pygentic-AI ``` -3. **Install the dependencies:** +3. **Quick setup with justfile (recommended):** + + ```sh + # One command setup: creates .env, installs deps, compiles SCSS + just setup + ``` + +4. **Manual installation (alternative):** @@ -763,36 +818,232 @@ If this fails due to platform-specific issues, try this instead: ### 🔆 Usage -Run the project with: +#### Development Mode -**Using [docker](https://www.docker.com/):** +**Quick start (recommended):** ```sh -docker run -it {image_name} +# Terminal 1: Start FastAPI development server +just dev + +# Terminal 2: Start Celery worker +just celery + +# Terminal 3: Auto-compile SCSS on changes +just scss-watch ``` -**Using [pip](https://pypi.org/project/pip/):** + +**Manual start:** ```sh -python {entrypoint} +# Using uv (recommended) +uv run python src/app.py # FastAPI server +uv run python src/cworker.py # Celery worker + +# Using pip +python src/app.py +python src/cworker.py ``` -**Using [uv](https://docs.astral.sh/uv/):** + +#### Production Mode (Docker) + +**With justfile:** ```sh -uv run python {entrypoint} +# Build and start all services +just build +just up-d + +# Check status +just health +just ps + +# View logs +just logs-f +``` + +**Manual Docker commands:** +```sh +# Build image +docker build -t s3docker.francissecada.com/pygentic_ai:latest . + +# Start services +docker-compose up -d + +# View logs +docker-compose logs -f +``` + +#### Available Commands + +Run `just` to see all available commands: +```sh +just # List all commands +just --list # Same as above + +# Common commands +just setup # First-time setup +just dev # Development server +just test # Run tests +just build [tag] # Build Docker image +just deploy [tag] # Deploy to production +just health # Check service health +just clean # Clean up containers ``` ### 🌠 Testing -Pygentic-ai uses the {__test_framework__} test framework. Run the test suite with: +**Run all tests:** +```sh +just test # Quick test run +just test-cov # With coverage report +``` -**Using [pip](https://pypi.org/project/pip/):** +**Manual testing:** ```sh -pytest +# Using uv (recommended) +uv run pytest tests/ -v +uv run pytest tests/ --cov=src --cov-report=html + +# Using pip +pytest tests/ -v ``` -**Using [uv](https://docs.astral.sh/uv/):** + +**Quality checks:** ```sh -uv run pytest tests/ +just lint # Run linters +just format # Format code +just security # Security scan +just check # All checks (pre-commit) ``` --- +## 🤖 Claude AI Assistance + +This project includes a multi-agent orchestration system for Claude AI to assist with development. + +### Setup + +The project includes two key files for Claude integration: + +- **`.claude/system-prompt.md`** - Multi-agent orchestration instructions (personas, MCP routing, patterns) +- **`CLAUDE.md`** - Project initialization guide (architecture, workflows, commands) + +### Available Personas + +Claude activates appropriate personas based on the task: + +- 🏗️ **Architect** - System design, architecture decisions, scaling +- 🎨 **Frontend** - UI/UX, SCSS, accessibility, Jinjax components +- ⚙️ **Backend** - FastAPI, Celery, database, AI agents +- 🔒 **Security** - Authentication, secrets, input validation +- 🚀 **DevOps** - Docker, CI/CD, deployment, monitoring + +### Usage + +```sh +# View Claude context files +just start-claude # Display orchestration context + +# When using Claude +# Use /init command to load project context from CLAUDE.md +# Claude will activate appropriate personas for your task +``` + +### Example Workflows + +**Feature Development:** +``` +User: "Add user authentication" +Claude: Activates 🏗️ Architect, 🔒 Security, ⚙️ Backend, 🎨 Frontend +- Designs auth architecture +- Implements secure endpoints +- Creates login UI components +- Updates deployment configs +``` + +**Bug Fixing:** +``` +User: "Fix SCSS compilation error" +Claude: Activates 🎨 Frontend persona +- Identifies SCSS syntax issues +- Runs just scss to verify fix +- Updates documentation if needed +``` + +--- + +## 📋 Justfile Command Reference + +Quick reference for common `just` commands: + +### Development +```sh +just setup # First-time project setup +just dev # Start FastAPI dev server +just celery # Start Celery worker +just scss # Compile SCSS once +just scss-watch # Auto-compile SCSS on changes +just npm-install # Install frontend dependencies +``` + +### Docker Operations +```sh +just build [tag] # Build Docker image +just up # Start services +just up-d # Start in detached mode +just down # Stop services +just restart # Restart services +just logs-f # Follow all logs +just logs-web # Follow web service logs +just logs-celery # Follow celery logs +just health # Check service health +just ps # Show container status +just stats # Show resource usage +``` + +### Testing & Quality +```sh +just test # Run test suite +just test-cov # Run with coverage +just lint # Run linters +just format # Format code +just security # Security scan +just check # All quality checks +``` + +### Deployment +```sh +just deploy [tag] # Deploy with specific tag +just deploy-dev # Deploy dev environment +just deploy-main # Deploy production +just pull [tag] # Pull Docker image +``` + +### Database +```sh +just migrate # Run migrations +just migration [name] # Create migration +``` + +### Cleanup +```sh +just clean # Remove containers +just clean-images # Remove images +just clean-all # Full cleanup +just prune # Remove unused resources +``` + +### Utilities +```sh +just info # Show environment info +just config # Show Docker Compose config +just check-env # Validate environment variables +just init-env # Create .env from template +``` + +For a complete list: `just --list` + +--- + ## 🌻 Roadmap - [X] **`Task 1`**: Bootstrap a minimal application build diff --git a/justfile b/justfile new file mode 100644 index 0000000..42a88dc --- /dev/null +++ b/justfile @@ -0,0 +1,310 @@ +# Pygentic-AI Justfile +# Task automation for Docker, development, and deployment workflows + +# Default recipe - show available commands +default: + @just --list + +# Variables with sensible defaults +IMAGE_NAME := "s3docker.francissecada.com/pygentic_ai" +COMPOSE_FILE := "compose.yaml" + +# ============================================ +# Docker Build Commands +# ============================================ + +# Build Docker image with optional tag (default: dev-latest) +build tag="dev-latest": + @echo "Building Docker image: {{IMAGE_NAME}}:{{tag}}" + docker build --ssh default -t {{IMAGE_NAME}}:{{tag}} . + +# Build image with custom branch +build-branch branch="dev_deploy": + @echo "Building from branch: {{branch}}" + docker build --ssh default --build-arg GIT_BRANCH={{branch}} -t {{IMAGE_NAME}}:{{branch}}-latest . + +# Build and push image +build-push tag="dev-latest": + @echo "Building and pushing: {{IMAGE_NAME}}:{{tag}}" + docker build --ssh default -t {{IMAGE_NAME}}:{{tag}} --push . + +# ============================================ +# Docker Compose Commands +# ============================================ + +# Start all services +up *args="": + docker-compose -f {{COMPOSE_FILE}} up {{args}} + +# Start services in detached mode +up-d: + docker-compose -f {{COMPOSE_FILE}} up -d + +# Stop all services +down: + docker-compose -f {{COMPOSE_FILE}} down + +# Restart services +restart: + docker-compose -f {{COMPOSE_FILE}} restart + +# View logs (optional service name and follow flag) +logs service="" follow="": + #!/usr/bin/env bash + if [ -n "{{service}}" ]; then + docker-compose -f {{COMPOSE_FILE}} logs {{follow}} {{service}} + else + docker-compose -f {{COMPOSE_FILE}} logs {{follow}} + fi + +# Follow logs for all services +logs-f: + docker-compose -f {{COMPOSE_FILE}} logs -f + +# Follow logs for web service +logs-web: + docker-compose -f {{COMPOSE_FILE}} logs -f web + +# Follow logs for celery service +logs-celery: + docker-compose -f {{COMPOSE_FILE}} logs -f celery_service + +# ============================================ +# Development Commands +# ============================================ + +# Install Python dependencies with uv +install: + uv sync --all-extras --dev + +# Run FastAPI development server +dev: + uv run python src/app.py + +# Run Celery worker +celery: + uv run python src/cworker.py + +# Compile SCSS to CSS +scss: + cd src/frontend && npm run build:css + +# Watch SCSS files and recompile on changes +scss-watch: + cd src/frontend && npm run watch:css + +# Install frontend dependencies +npm-install: + cd src/frontend && npm install + +# ============================================ +# Testing & Quality Commands +# ============================================ + +# Run all tests +test: + uv run pytest tests/ -v + +# Run tests with coverage +test-cov: + uv run pytest tests/ --cov=src --cov-report=html --cov-report=term + +# Run linting checks +lint: + uv run ruff check src/ + +# Run formatting +format: + uv run black src/ + uv run ruff check --fix src/ + +# Run security checks +security: + uv run bandit -r src/ + +# ============================================ +# Health & Status Commands +# ============================================ + +# Check if services are healthy +health: + @echo "Checking web service health..." + @curl -f -H "Host: pygenticai.francissecada.com" http://localhost:5051/ || echo "Web service is not responding" + +# Check Docker container status +ps: + docker-compose -f {{COMPOSE_FILE}} ps + +# Show container resource usage +stats: + docker stats --no-stream + +# ============================================ +# Database Commands +# ============================================ + +# Run database migrations (placeholder - add your migration tool) +migrate: + @echo "Running migrations..." + # uv run alembic upgrade head + +# Create new migration +migration name: + @echo "Creating migration: {{name}}" + # uv run alembic revision --autogenerate -m "{{name}}" + +# Reset database (WARNING: destructive) +db-reset: + @echo "WARNING: This will delete all data!" + @read -p "Are you sure? (y/N) " -n 1 -r + @echo + # Add your reset commands here + +# ============================================ +# Cleanup Commands +# ============================================ + +# Stop and remove all containers, networks +clean: + docker-compose -f {{COMPOSE_FILE}} down -v + +# Remove all Pygentic-AI Docker images +clean-images: + docker images {{IMAGE_NAME}} -q | xargs -r docker rmi -f + +# Full cleanup - containers, images, volumes +clean-all: clean clean-images + @echo "Cleaned up all Pygentic-AI Docker resources" + +# Remove unused Docker resources +prune: + docker system prune -f + +# ============================================ +# Deployment Commands +# ============================================ + +# Deploy with specific image tag +deploy tag="main-latest": + @echo "Deploying with IMAGE_TAG={{tag}}" + IMAGE_TAG={{tag}} docker-compose -f {{COMPOSE_FILE}} up -d + +# Pull latest images +pull tag="main-latest": + docker pull {{IMAGE_NAME}}:{{tag}} + +# Deploy latest from main branch +deploy-main: (pull "main-latest") + IMAGE_TAG=main-latest docker-compose -f {{COMPOSE_FILE}} up -d + +# Deploy from dev branch +deploy-dev: (pull "dev_deploy-latest") + IMAGE_TAG=dev_deploy-latest docker-compose -f {{COMPOSE_FILE}} up -d + +# ============================================ +# Environment Setup +# ============================================ + +# Create .env from template +init-env: + @if [ ! -f .env ]; then \ + cp .env.example .env; \ + echo "Created .env from template. Please update with your credentials."; \ + else \ + echo ".env already exists. Skipping."; \ + fi + +# Validate environment variables +check-env: + @echo "Checking required environment variables..." + @grep -v '^#' .env.example | grep '=' | cut -d'=' -f1 | while read var; do \ + if ! grep -q "^$var=" .env 2>/dev/null; then \ + echo "Missing: $var"; \ + fi; \ + done + +# ============================================ +# Development Workflow +# ============================================ + +# Full development setup +setup: init-env npm-install install scss + @echo "✅ Development environment ready!" + @echo "Run 'just dev' to start the development server" + +# Start complete development environment +dev-full: scss-watch dev + +# Rebuild and restart services +rebuild: build up-d + @echo "Services rebuilt and restarted" + +# ============================================ +# CI/CD Helpers +# ============================================ + +# Simulate CI build +ci-build: + @echo "Simulating CI build process..." + just build dev_deploy-$(date +%Y-%m-%d) + +# Run all quality checks (for pre-commit) +check: lint test + @echo "✅ All checks passed!" + +# ============================================ +# Information Commands +# ============================================ + +# Show environment information +info: + @echo "Project: Pygentic-AI" + @echo "Image: {{IMAGE_NAME}}" + @echo "Compose: {{COMPOSE_FILE}}" + @echo "" + @echo "Python version:" + @uv run python --version + @echo "" + @echo "Docker version:" + @docker --version + @echo "" + @echo "Docker Compose version:" + @docker-compose --version + +# Show current configuration +config: + docker-compose -f {{COMPOSE_FILE}} config + +# ============================================ +# Claude AI Assistance +# ============================================ + +# Start Claude with full project context and multi-agent orchestration +start-claude: + @echo "🤖 Starting Claude with Pygentic-AI context..." + @echo "📋 System Prompt: .claude/system-prompt.md (Multi-agent orchestration)" + @echo "📖 Project Context: CLAUDE.md (Initialization guide)" + @echo "" + @if [ ! -f .claude/system-prompt.md ]; then \ + echo "❌ Error: .claude/system-prompt.md not found"; \ + echo "Run: git pull origin dev_deploy"; \ + exit 1; \ + fi + @if [ ! -f CLAUDE.md ]; then \ + echo "❌ Error: CLAUDE.md not found"; \ + echo "Run: git pull origin dev_deploy"; \ + exit 1; \ + fi + @echo "✅ All context files found" + @echo "" + @echo "Claude will load with:" + @echo " • Multi-agent orchestration (🏗️ Architect, 🎨 Frontend, ⚙️ Backend, 🔒 Security, 🚀 DevOps)" + @echo " • MCP server routing (Sequential, Context7, Magic, Playwright, Morphllm, Serena)" + @echo " • Project architecture and workflows" + @echo "" + @# Note: Actual Claude CLI integration depends on available tooling + @# This demonstrates the intended workflow + @cat .claude/system-prompt.md CLAUDE.md + @echo "" + @echo "💡 Tip: Use /init command in Claude to load project context" + @echo "📝 Available commands: just --list"