Bellator Schedule Intelligence Simulation & Analysis API

openapi: 3.2.0
info:
  title: Bellator Schedule Intelligence Simulation & Analysis API
  description: 'Bellator Schedule Intelligence APIs - Stateless Schedule Health APIs


    ## Features


    * **Schedule Analysis** - Comprehensive schedule health analysis

    * **Critical Path** - CPM-based critical path calculation

    * **Validation** - Schedule validation and quality checks

    * **Future: Resource Management** - Resource allocation and leveling

    * **Future: Simulation** - Monte Carlo and what-if analysis

    * **Future: AI Recommendations** - LLM-powered optimization suggestions


    ## Authentication


    API key authentication via `x-api-key` header or OAuth 2.0 Bearer token via `Authorization` header.


    ### API Key Authentication (Legacy)

    Include API key in `x-api-key` header.


    ### OAuth 2.0 / Azure AD Authentication (Recommended)

    Include Bearer token in `Authorization` header: `Authorization: Bearer `


    Tiers:

    - **Free**: 2,000 tasks, 100 req/min, 5MB payload

    - **Professional**: 5,000 tasks, 500 req/min, 25MB payload

    - **Enterprise**: 50,000 tasks, 2,000 req/min, 100MB payload

    - **Government**: 100,000+ tasks, 10,000 req/min, 500MB payload


    ## Usage Metering


    All API requests are metered and tracked for:

    - Request duration (milliseconds)

    - Task count processed

    - Token consumption (for LLM operations)

    - Estimated cost (USD)


    Metering events are emitted to logs and can be integrated with billing systems.


    ## Security


    * Tier-based task limits (500-100,000 tasks per request)

    * Tier-based payload limits (5-500 MB)

    * Input validation and sanitization

    * Tier-based rate limiting (100-10,000 requests per 60 seconds)'
  version: 0.4.0
tags:
- name: Simulation & Analysis
paths:
  /api/v1/simulation/monte-carlo:
    post:
      tags:
      - Simulation & Analysis
      summary: Monte Carlo Simulation (Placeholder)
      description: Monte Carlo simulation for schedule risk analysis - not yet implemented
      operationId: run_monte_carlo_api_v1_simulation_monte_carlo_post
      parameters:
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-bellator-internal-dispatch
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Bellator-Internal-Dispatch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MonteCarloRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonteCarloResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/simulation/what-if:
    post:
      tags:
      - Simulation & Analysis
      summary: What-If Analysis (Placeholder)
      description: What-if scenario analysis - not yet implemented
      operationId: run_what_if_api_v1_simulation_what_if_post
      parameters:
      - name: scenario
        in: query
        required: false
        schema:
          type: string
          default: baseline
          title: Scenario
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-bellator-internal-dispatch
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Bellator-Internal-Dispatch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScheduleRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    app__models__schemas__ResourceAvailability__1:
      properties:
        resource_name:
          type: string
          title: Resource Name
          description: Resource name (must match tasks[*].resources)
        available_from:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Available From
          description: Start of availability window (ISO 8601). Null = project start.
        available_to:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Available To
          description: End of availability window (ISO 8601). Null = project finish.
        units_per_day:
          type: number
          minimum: 0.0
          title: Units Per Day
          description: 'Available resource-units per working day (default: 1.0 = 100%)'
          default: 1.0
      type: object
      required:
      - resource_name
      title: ResourceAvailability
      description: 'Per-resource availability window for Resource Analysis.


        Specifies how many units of a resource are available over a date range.

        resource_name must match a value appearing in tasks[*].resources.'
    MonteCarloRequest:
      properties:
        tasks:
          items:
            $ref: '#/components/schemas/Task'
          type: array
          title: Tasks
        iterations:
          type: integer
          maximum: 10000.0
          minimum: 100.0
          title: Iterations
          description: Number of simulation iterations
          default: 1000
      type: object
      required:
      - tasks
      title: MonteCarloRequest
      description: Request model for Monte Carlo simulation (placeholder).
    ValidationOptions:
      properties:
        calculate_pop:
          type: boolean
          title: Calculate Pop
          description: Calculate Probability of Performance (PoP) score (v0.2.0).
          default: false
        include_pop_details:
          type: boolean
          title: Include Pop Details
          description: Include dimensional PoP breakdown in response.
          default: true
        strict_mode:
          type: boolean
          title: Strict Mode
          description: Treat warnings as errors (fail validation on any issue).
          default: false
        check_dcma_compliance:
          type: boolean
          title: Check Dcma Compliance
          description: 'Include DCMA-specific checks (#1, #8).'
          default: true
      type: object
      title: ValidationOptions
      description: Options for POST /api/v1/schedule/validate (v0.2.0).
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    MonteCarloResponse:
      properties:
        simulations:
          type: integer
          title: Simulations
          default: 0
        confidence_intervals:
          additionalProperties: true
          type: object
          title: Confidence Intervals
        message:
          type: string
          title: Message
          default: Monte Carlo simulation is not yet implemented
      type: object
      title: MonteCarloResponse
      description: Response model for Monte Carlo simulation (placeholder).
    ScheduleRequest:
      properties:
        tasks:
          items:
            $ref: '#/components/schemas/Task'
          type: array
          maxItems: 100000
          title: Tasks
          description: List of tasks in the schedule
        start_task_ids:
          items:
            type: string
          type: array
          title: Start Task Ids
          description: 'Task IDs that anchor the project start (DCMA Check #1). If empty, tasks with no predecessors are treated as start tasks.'
        finish_task_ids:
          items:
            type: string
          type: array
          title: Finish Task Ids
          description: 'Task IDs that anchor the project finish (DCMA Check #1). If empty, tasks with no successors are treated as finish tasks.'
        status_date:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Status Date
          description: Data date / status date for progress validation (ISO 8601 YYYY-MM-DD)
        target_finish_date:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Target Finish Date
          description: Target project finish date or key milestone date for CPLI calculation (ISO 8601)
        baseline_approved_date:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Baseline Approved Date
          description: Date when baseline was approved (for governance tracking)
        resource_availability:
          items:
            $ref: '#/components/schemas/app__models__schemas__ResourceAvailability__1'
          type: array
          title: Resource Availability
          description: Per-resource availability for over-allocation detection (Resource Analysis API).
        options:
          $ref: '#/components/schemas/ValidationOptions'
          description: Validation options including Probability of Performance (v0.2.0).
      type: object
      required:
      - tasks
      title: ScheduleRequest
      description: 'Request model for schedule analysis.


        This is the base schedule payload used across all Tier 1 and Tier 2 APIs.

        Additional Tier 2-specific fields enable full DCMA 14-Point compliance.'
      example:
        tasks:
        - duration_days: 5
          id: T1
          name: Design
          predecessors: []
        - duration_days: 10
          id: T2
          name: Development
          predecessors:
          - T1
        - duration_days: 5
          id: T3
          name: Testing
          predecessors:
          - T2
    RelationshipType:
      type: string
      enum:
      - FS
      - SS
      - FF
      - SF
      title: RelationshipType
      description: "Task relationship types per PMBOK 6.3.2.2.\n\nAttributes:\n    FINISH_START: Predecessor finish → successor start (most common, ~90%)\n    START_START: Predecessor start → successor start (~5%)\n    FINISH_FINISH: Predecessor finish → successor finish (~4%)\n    START_FINISH: Predecessor start → successor finish (rare, ~1%)"
    DependencyLink:
      properties:
        task_id:
          type: string
          title: Task Id
          description: Predecessor task ID
        relationship_type:
          $ref: '#/components/schemas/RelationshipType'
          description: Relationship type (FS/SS/FF/SF)
          default: FS
        lag_days:
          type: number
          title: Lag Days
          description: Lag (positive) or lead (negative) in days
          default: 0.0
        is_external:
          type: boolean
          title: Is External
          description: True if link to external project file
          default: false
        external_path:
          anyOf:
          - type: string
          - type: 'null'
          title: External Path
          description: Path to external file if is_external=True
      type: object
      required:
      - task_id
      title: DependencyLink
      description: "Rich dependency link with relationship type and lag/lead.\n\nSupports parsing from various scheduling tool formats including:\n- MS Project: \"10FS+5 d\", \"/path/file.mpp/10FS+5 d\"\n- Primavera P6: Similar format with XER encoding\n- Server-based: \"<ServerFile>10FS+5 d\"\n- Simple: \"10\" (defaults to FS with zero lag)\n\nExamples:\n    >>> DependencyLink(task_id=\"10\", relationship_type=\"FS\", lag_days=5.0)\n    >>> DependencyLink.from_string(\"10FS+5 d\")\n    >>> DependencyLink.from_string(\"15SS-2 d\")"
      examples:
      - is_external: false
        lag_days: 5.0
        relationship_type: FS
        task_id: '10'
      - is_external: false
        lag_days: -2.0
        relationship_type: SS
        task_id: '15'
      - external_path: /path/to/external.mpp
        is_external: true
        lag_days: 5.0
        relationship_type: FS
        task_id: '20'
    Task:
      properties:
        id:
          type: string
          title: Id
          description: Unique task identifier
        duration_days:
          type: number
          minimum: 0.0
          title: Duration Days
          description: Task duration in days
          default: 0
        predecessors:
          items:
            anyOf:
            - type: string
            - additionalProperties: true
              type: object
            - $ref: '#/components/schemas/DependencyLink'
          type: array
          title: Predecessors
          description: 'List of predecessor task IDs or dependency links. Supports: ''T1'', ''T1FS+5 d'', ''T2SS-2 d'', or DependencyLink objects'
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: Task name
        resource:
          anyOf:
          - type: string
          - type: 'null'
          title: Resource
          description: Resource assigned to task
        resources:
          items:
            type: string
          type: array
          title: Resources
          description: List of resources assigned (for multi-resource tasks)
        percent_complete:
          type: number
          maximum: 100.0
          minimum: 0.0
          title: Percent Complete
          description: Percent complete (0-100)
          default: 0
        physical_percent_complete:
          anyOf:
          - type: number
            maximum: 100.0
            minimum: 0.0
          - type: 'null'
          title: Physical Percent Complete
          description: Physical percent complete (0-100). Manual EVM entry by scheduler (MSP PhysicalPercentComplete). Authoritative for BCWP calculations. Captured separately from percent_complete on MSP imports.
        planned_start:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Planned Start
          description: Planned start date (ISO 8601)
        planned_finish:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Planned Finish
          description: Planned finish date (ISO 8601)
        actual_start:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Actual Start
          description: Actual start date (ISO 8601)
        actual_finish:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Actual Finish
          description: Actual finish date (ISO 8601)
        baseline_start:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Baseline Start
          description: Baseline start date (ISO 8601)
        baseline_finish:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Baseline Finish
          description: Baseline finish date (ISO 8601)
        constraint_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Constraint Type
          description: 'Constraint type: ASAP, ALAP, SNET, SNLT, FNET, FNLT, MSO, MFO'
        constraint_date:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Constraint Date
          description: Constraint date if applicable (ISO 8601)
        task_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Task Type
          description: 'Task type classification. Valid values: task (default), milestone, loe, summary, schedule_margin, planning_package, slpp, schedule_visibility. Drives DCMA check exclusions per PAM 200.1 § 3.2.'
        wbs_code:
          anyOf:
          - type: string
            maxLength: 100
          - type: 'null'
          title: Wbs Code
          description: WBS code (e.g., '1.2.3')
        organization_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Organization Code
          description: Org/dept identifier for anomaly categorization (Progress Audit)
        custom_field_map:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Custom Field Map
          description: All WBS/OBS-pattern custom fields discovered in this MS Project file, keyed by alias (e.g., 'CWBS', 'OBS'). Null for XER imports or when no matching aliases exist.
        forecast_start:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Forecast Start
          description: Current forecast start date (ISO 8601)
        forecast_finish:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Forecast Finish
          description: Current forecast finish date (ISO 8601)
        total_float_days:
          anyOf:
          - type: number
          - type: 'null'
          title: Total Float Days
          description: Pre-computed total float in days. Auto-computed by CPM if absent.
        baseline_duration_days:
          anyOf:
          - type: number
            minimum: 0.0
          - type: 'null'
          title: Baseline Duration Days
          description: Baseline duration in days. Auto-computed from baseline dates if absent.
        delay_category:
          anyOf:
          - type: string
          - type: 'null'
          title: Delay Category
          description: 'Delay attribution category. Valid values: owner, contractor, design, procurement, weather, force_majeure.'
        earned_value:
          anyOf:
          - type: number
            minimum: 0.0
          - type: 'null'
          title: Earned Value
          description: Earned Value (BCWP) in cost units. Requires options.include_ev_validation.
        budgeted_cost:
          anyOf:
          - type: number
            minimum: 0.0
          - type: 'null'
          title: Budgeted Cost
          description: Budgeted Cost of Work Scheduled (BCWS) in cost units.
        approval_required:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Approval Required
          description: Whether this task requires explicit approval before it can start.
        approval_status:
          anyOf:
          - type: string
          - type: 'null'
          title: Approval Status
          description: 'Approval workflow state. Valid values: not_required, pending, approved, rejected.'
      type: object
      required:
      - id
      title: Task
      description: 'Unified task model for all schedule analysis endpoints.


        This model is used across all Tier 1 and Tier 2 APIs. Fields are optional

        unless specifically required by an endpoint.


        Field Naming Rationale:

        - duration_days: Explicit time unit (vs generic "duration")

        - predecessors: Standard scheduling terminology (vs generic "dependencies")


        Dependency Format Support:

        - Simple: ["task1", "task2"]

        - Rich: ["task1FS+5 d", "task2SS-2 d"]

        - Objects: [DependencyLink(...), ...]'
      example:
        duration_days: 10
        id: T1
        name: Design Phase
        percent_complete: 0
        planned_finish: '2026-01-15'
        planned_start: '2026-01-01'
        predecessors: []
        resource: Team A
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for authentication. Required when API_KEY is configured.
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize
          tokenUrl: https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
          scopes:
            api.read: Read access to API
            api.write: Write access to API
      description: OAuth 2.0 / Azure AD authentication (recommended)
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT Bearer token from OAuth 2.0 / Azure AD