openapi: 3.0.3
info:
  title: AutoPilot TaskMate Commons Protocol
  version: 0.1.0-draft
  description: |
    Open protocol for AI-driven business process automation.
    
    This is a DRAFT specification for NGI Commons grant proposal.
    Full protocol will be completed with NGI funding (6 months, €50k).
    
    License: MIT
    Project: https://github.com/seoframe-com/AutoPilot-TaskMate-Commons    
  contact:
    name: AutoPilot TaskMate Commons
    email: info@seoframe.com
    url: https://seoframe.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://api.example.com/v1
    description: Reference implementation (to be built with NGI funding)

paths:
  /tasks/invoice-extraction:
    post:
      summary: Extract structured data from invoice documents
      description: |
        Parse invoice PDFs/images and extract vendor, amount, date, invoice number.
        Supports multiple formats (PDF, JPG, PNG).        
      operationId: extractInvoice
      tags:
        - Invoice Processing
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: Invoice document (PDF, JPG, PNG)
                fields:
                  type: array
                  items:
                    type: string
                  description: Fields to extract (default: vendor, amount, date, invoice_number)
                  example: ["vendor", "amount", "date", "invoice_number"]
      responses:
        '200':
          description: Successful extraction
          content:
            application/json:
              schema:
                type: object
                properties:
                  task_id:
                    type: string
                    example: "inv_20260119_abc123"
                  status:
                    type: string
                    enum: [completed, failed]
                    example: completed
                  data:
                    type: object
                    properties:
                      vendor:
                        type: string
                        example: "Acme Corp Ltd"
                      amount:
                        type: number
                        example: 1250.50
                      currency:
                        type: string
                        example: "EUR"
                      date:
                        type: string
                        format: date
                        example: "2026-01-15"
                      invoice_number:
                        type: string
                        example: "INV-2026-001"
                  confidence:
                    type: number
                    description: Extraction confidence (0-1)
                    example: 0.95
        '400':
          description: Invalid file format
        '500':
          description: Processing error

  /tasks/email-classification:
    post:
      summary: Classify and route incoming emails
      description: |
        Analyze email content and classify by urgency, category, department.
        Returns routing recommendation.        
      operationId: classifyEmail
      tags:
        - Email Classification
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - subject
                - body
              properties:
                subject:
                  type: string
                  example: "Urgent: Order #12345 delivery issue"
                body:
                  type: string
                  example: "Customer reports missing items in shipment..."
                sender:
                  type: string
                  format: email
                  example: "customer@example.com"
                categories:
                  type: array
                  items:
                    type: string
                  description: Custom categories for classification
                  example: ["urgent", "order", "support", "billing"]
      responses:
        '200':
          description: Successful classification
          content:
            application/json:
              schema:
                type: object
                properties:
                  task_id:
                    type: string
                    example: "email_20260119_xyz789"
                  status:
                    type: string
                    enum: [completed, failed]
                  classification:
                    type: object
                    properties:
                      category:
                        type: string
                        example: "order"
                      urgency:
                        type: string
                        enum: [low, medium, high, critical]
                        example: "high"
                      department:
                        type: string
                        example: "logistics"
                      sentiment:
                        type: string
                        enum: [positive, neutral, negative]
                        example: "negative"
                  confidence:
                    type: number
                    example: 0.88
        '400':
          description: Invalid request
        '500':
          description: Processing error

  /tasks/data-validation:
    post:
      summary: Validate spreadsheet data integrity
      description: |
        Check CSV/Excel files for duplicates, missing fields, format errors.
        Returns validation report with flagged issues.        
      operationId: validateData
      tags:
        - Data Validation
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
                - rules
              properties:
                file:
                  type: string
                  format: binary
                  description: Data file (CSV, XLSX)
                rules:
                  type: array
                  items:
                    type: string
                  description: Validation rules to apply
                  example: ["no_duplicates", "required_fields", "email_format", "date_format"]
                required_fields:
                  type: array
                  items:
                    type: string
                  example: ["email", "name", "amount"]
      responses:
        '200':
          description: Validation completed
          content:
            application/json:
              schema:
                type: object
                properties:
                  task_id:
                    type: string
                    example: "val_20260119_def456"
                  status:
                    type: string
                    enum: [completed, failed]
                  validation_result:
                    type: object
                    properties:
                      total_rows:
                        type: integer
                        example: 500
                      valid_rows:
                        type: integer
                        example: 485
                      invalid_rows:
                        type: integer
                        example: 15
                      errors:
                        type: array
                        items:
                          type: object
                          properties:
                            row:
                              type: integer
                              example: 42
                            field:
                              type: string
                              example: "email"
                            error:
                              type: string
                              example: "Invalid email format"
                      duplicates:
                        type: array
                        items:
                          type: object
                          properties:
                            rows:
                              type: array
                              items:
                                type: integer
                              example: [23, 67]
                            field:
                              type: string
                              example: "customer_id"
        '400':
          description: Invalid file or rules
        '500':
          description: Processing error

components:
  schemas:
    TaskStatus:
      type: object
      properties:
        task_id:
          type: string
        status:
          type: string
          enum: [pending, processing, completed, failed]
        created_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
    
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        task_id:
          type: string

tags:
  - name: Invoice Processing
    description: Extract structured data from invoices
  - name: Email Classification
    description: Route and categorize emails
  - name: Data Validation
    description: Validate spreadsheet integrity