APAI is an open protocol for describing, documenting, and validating artificial intelligence systems. It provides a structured format to specify AI models, prompts, constraints, workflows, and evaluation metrics in a clean, readable way.

Balanced Approach: The specification follows essential best practices while maintaining simplicity and readability. It's designed to be enterprise-ready without over-engineering, making it accessible for both beginners and advanced users.

• Key Features - Core capabilities and design principles
• Generative Map Potential - Code generation and automation possibilities
• Quick Start - Get started with APAI in minutes
• Examples - Real-world implementations and templates
• Hierarchical Composition - Building complex systems through inheritance
• Specification - Official specification and documentation
• Tools and Libraries - Validators and community tools
• Automation Integration - External platform integration
• Contributing - How to contribute to APAI
• Governance - Project governance and community structure
• Whitepapers - Comprehensive technical and business analysis

• AI-Focused Design: Models, prompts, and constraints as core components
• Provider Independence: Works with any AI provider (OpenAI, Anthropic, Google, etc.)
• Multi-Modal Support: LLM, Vision, Audio, and Multimodal AI systems
• Automation Integration: Integration with n8n, Zapier, and other automation platforms
• Built-in Ethics: Required fields for safety, bias prevention, and explainability
• Evaluation Framework: Metrics for accuracy, performance, and safety
• Extensible: Support for custom use cases and domain-specific requirements
• Hierarchical Composition: Inherit and compose specifications across organizational levels
• Multi-Environment Support: Different configurations for dev, staging, and production
• Clean & Readable: Simple, well-documented format that's easy to understand and maintain

The APAI YAML specification's clean, structured format provides several practical benefits for AI system development:

• API Clients: Generate client libraries in multiple languages (Python, JavaScript, PHP, Go)
• Server Implementations: Create backend services that implement the AI system
• SDK Generation: Build software development kits for easy integration
• Configuration Files: Generate deployment configs for Docker, Kubernetes, cloud platforms

• Interactive Docs: Create web-based documentation with live examples
• API References: Generate comprehensive API documentation
• Integration Guides: Auto-create step-by-step integration tutorials
• Architecture Diagrams: Visual representations of AI system architecture

• Workflow Automation: Deploy n8n, Zapier, or custom automation workflows
• MCP Server Setup: Configure Model Context Protocol servers automatically
• Monitoring Dashboards: Set up metrics collection and alerting systems
• Testing Frameworks: Generate test suites and validation scripts

• Cloud Deployments: Generate Terraform, CloudFormation, or Pulumi configurations
• Container Orchestration: Create Docker Compose and Kubernetes manifests
• CI/CD Pipelines: Set up automated testing and deployment workflows
• Environment Management: Configure dev, staging, and production environments

# Customer Support AI
apai: "0.1.0"
info:
  title: "Customer Support AI"
  version: "1.0.0"
  description: "AI assistant for customer support"
  author: "AI Team"
  license: "MIT"
  ai_metadata:
    domain: "customer_service"
    complexity: "medium"
    deployment: "production"
    last_updated: "2025-01-15T10:30:00Z"
models:
  - id: "support_model"
    type: "LLM"
    provider: "openai"
    name: "gpt-4"
    version: "4.0"
    purpose: "Customer support conversations"
tasks:
  - id: "handle_support"
    name: "Handle Support Request"
    description: "Process customer support inquiries"
    type: "conversational"
    priority: "high"
    steps:
      - name: "respond"
        action: "generate"
        model: "support_model"

This clean format enables:

• Easy understanding and maintenance
• Automated validation and testing
• Code generation and tooling
• Team collaboration and documentation
• Enterprise governance and compliance

git clone https://github.com/FabioGuin/APAI.git
cd APAI

# Copy the template and fill in your actual values
cp .env.example .env
# Edit .env with your API keys and credentials
# NEVER commit the .env file to version control

apai: "0.1.0"
info:
  title: "My AI Assistant"
  version: "1.0.0"
  description: "A helpful AI assistant for customer support"

models:
  - id: "main_model"
    type: "LLM"
    provider: "openai"
    name: "gpt-4"
    purpose: "conversation"

prompts:
  - id: "system_prompt"
    role: "system"
    template: "You are a helpful AI assistant for {{company_name}}"

constraints:
  - id: "safety"
    rule: "output NOT contains harmful_content"
    severity: "critical"

tasks:
  - id: "handle_query"
    description: "Process user queries safely"
    steps:
      - action: "generate"
        model: "main_model"
        prompt: "system_prompt"

apai: "0.1.0"

# Inherit from parent specifications
inherits:
  - "../apai-global.yaml"
  - "../../apai-team.yaml"

info:
  title: "Feature-Specific AI Assistant"
  version: "1.0.0"
  description: "AI assistant for specific feature"
  ai_metadata:
    hierarchy_info:
      level: "feature"
      scope: "project"
      inheritance_mode: "merge"

# Additional models and constraints specific to this feature
models:
  - id: "feature_specific_model"
    type: "Classification"
    provider: "huggingface"
    name: "sentiment-analyzer"

constraints:
  - id: "feature_performance"
    type: "performance"
    rule: "response_time < 2s"
    severity: "high"

# Simple validation
python validators/python/apai_validator.py validate spec/my-ai-system.yaml

# Hierarchical validation (with inheritance)
python validators/python/apai_validator.py validate spec/my-ai-system.yaml --hierarchical

# Using JavaScript validator
node validators/javascript/cli.js validate spec/my-ai-system.yaml

# Using PHP validator
php validators/php/cli.php validate spec/my-ai-system.yaml

# Using Go validator
go run validators/go/cli.go validate spec/my-ai-system.yaml

Check out our examples directory for complete implementations organized by category and complexity:

• Customer Support AI - E-commerce assistant with order management and multilingual support
• Content Moderator - AI-powered content filtering and safety enforcement
• Multilingual Chatbot - Multi-language conversation support

• Multi-Agent Customer Support - Complete multi-agent system using hierarchical composition
• Sentiment Analysis Agent - Specialized agent for sentiment analysis

• E-commerce with n8n - Complete order processing with automation workflows
• Customer Support with Zapier - Simple webhook-based automation integration
• MCP Integration - Model Context Protocol server integration

• Basic Template - Minimal starting template for new specifications
• Complete JSON Example - Machine-readable reference for tools and SDKs

See the Examples README for detailed descriptions and learning paths.

APAI supports hierarchical composition for complex organizational structures:

• Hierarchical Composition Guide - Complete guide to inheritance and composition
• Enterprise Use Cases - Global, regional, and department-level specifications
• Team Development - Sprint and feature-level configurations
• Environment Management - Dev, staging, and production configurations

# Global specification
apai: "0.1.0"
info:
  title: "Global AI Standards"
  ai_metadata:
    hierarchy_info:
      level: "global"
      scope: "organization"

# Feature specification inheriting from global
apai: "0.1.0"
inherits:
  - "../apai-global.yaml"
info:
  title: "Feature-Specific AI"
  ai_metadata:
    hierarchy_info:
      level: "feature"
      scope: "project"

The APAI specification is available in multiple formats:

• YAML: spec/apai-0.1.yaml - Official specification (human-readable)
• JSON Example: examples/apai-0.1-example.json - Complete working example for tools and SDKs
• JSON Schema: spec/schemas/apai-0.1-schema.json - Validation schema
• Examples: examples/*.yaml - Real-world use case examples

See spec/README.md for detailed file structure and usage guide.

The specification includes these core sections:

• apai - Specification version
• info - System metadata and AI-specific information
• models - AI models with capabilities, limits, and costs
• prompts - Structured prompts with variables and configuration
• constraints - Safety, ethical, and operational constraints
• tasks - Declarative workflows and business logic
• context - State management and memory configuration
• evaluation - Metrics, tests, and performance monitoring

• Documentation Index - Complete documentation overview and learning paths
• Getting Started Guide - Step-by-step tutorial for new users
• APAI 0.1 Specification - Complete formal specification documentation
• Hierarchical Composition Guide - Advanced inheritance and composition patterns
• Multi-Agent Systems Guide - Building multi-agent systems using existing APAI features
• Automation Integration Guide - Integrating with external automation platforms
• Security Best Practices - Managing secrets and environment variables securely
• AI Security Considerations - Comprehensive AI-specific security framework
• Security Vulnerabilities - Common AI security vulnerabilities and prevention

• Python Validator - Full-featured validation library
• PHP Validator - PHP validation with Symfony YAML
• JavaScript Validator - Node.js and browser support
• Go Validator - High-performance validation

• The APAI community is encouraged to build generative tools and integrations
• Examples: Code generators, documentation tools, deployment automation, testing frameworks

Each validator includes a command-line interface for easy validation:

# Python
python validators/python/apai_validator.py spec.yaml

# PHP
php validators/php/cli.php -f spec.yaml

# JavaScript
node validators/javascript/cli.js -f spec.yaml

# Go
go run validators/go/. -f spec.yaml

APAI 0.1 includes integration with external automation platforms, allowing AI systems to trigger and coordinate with automation workflows without tight coupling.

• n8n: Complex business process automation
• Zapier: Simple integrations and notifications
• Microsoft Power Automate: Enterprise workflows
• Custom Webhooks: Legacy system connections

automations:
  - id: "order_processing_workflow"
    name: "Order Processing Automation"
    provider: "n8n"
    
    trigger:
      type: "webhook"
      endpoint: "/webhooks/order-created"
      conditions:
        - "order_status == 'validated'"
    
    integration:
      type: "external_workflow"
      workflow_id: "n8n://workflows/order-processing"
      timeout: "5m"
    
    data_contract:
      input:
        order_id:
          type: "string"
          required: true
        customer_id:
          type: "string"
          required: true
      output:
        processing_status:
          type: "string"
          enum: ["processing", "shipped", "delivered", "failed"]

tasks:
  - id: "process_order"
    steps:
      - name: "trigger_processing"
        action: "automation"
        automation: "order_processing_workflow"
        automation_parameters:
          order_id: "${input.order_id}"
          customer_id: "${input.customer_id}"

• Declarative: Define what automations to trigger, not how
• Platform Independent: Works with any automation platform
• Monitored: Built-in health checks and metrics
• Secure: Configurable authentication and validation

• Automation Integration Guide - Complete guide with examples and best practices
• E-commerce Example - Full n8n integration example
• Zapier Example - Simple webhook integration example

We welcome contributions! Please see our Contributing Guidelines for details.

1. Issues: Open an issue to discuss changes
2. Pull Requests: Submit PRs for implementation
3. Review: Maintainer review with community feedback
4. Decision: Transparent decision-making process

APAI is currently in Bootstrap Phase with Fabio Guin as the initial maintainer. We plan to transition to a community-driven governance model as the project grows.

See GOVERNANCE.md for details.

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Comprehensive whitepapers providing detailed analysis and insights into APAI:

• APAI Whitepaper (English) - Complete technical and business analysis of APAI's capabilities, architecture, and potential
• APAI Whitepaper (Italiano) - Analisi completa tecnica e business delle capacità, architettura e potenziale di APAI

Both whitepapers cover:

• Executive Summary - Overview of APAI's value proposition
• AI Standardization Challenge - Current industry challenges and needs
• Core Architecture - Detailed technical specifications and features
• Advanced Capabilities - Multi-agent systems, automation integration, MCP support
• Generative Development Potential - Code generation, documentation, and tooling opportunities
• Implementation Guide - Getting started and adoption strategies
• Governance & Community - Project governance and contribution guidelines
• Future Roadmap - Long-term vision and development plans

Perfect for:

• Technical Leaders - Understanding APAI's technical capabilities
• Business Stakeholders - Evaluating APAI's business value
• Developers - Learning implementation approaches and best practices
• Decision Makers - Making informed adoption decisions

• Discussions: GitHub Discussions
• Issues: GitHub Issues

APAI is inspired by:

• ISO/IEC 42001 for AI governance
• LangChain for AI orchestration
• IEEE AI-ESTATE for AI component formalization

Note: This project is in active development. The specification may change between versions. Please check the CHANGELOG for breaking changes.