openapi: 3.1.0
info:
  title: GCN AI Worker API
  version: 1.0.0
  description: Production-ready AI API for Global Capital Network. Provides lead scoring, startup summaries, founder bios, and flexible model routing between OpenAI and Anthropic.
  contact:
    name: GCN Labs
    url: https://ai.gcnlabs.com

servers:
  - url: https://ai.gcnlabs.com
    description: Production server

paths:
  /health:
    get:
      summary: Health check
      description: Returns the service health status
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  service:
                    type: string
                    example: ai.gcnlabs.com
                  timestamp:
                    type: number
                    example: 1234567890

  /models:
    get:
      summary: List available models
      description: Returns a list of available AI models and their capabilities
      responses:
        '200':
          description: List of available models
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  models:
                    type: array
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                          example: gpt-4o-mini
                        provider:
                          type: string
                          example: openai
                        defaultFor:
                          type: array
                          items:
                            type: string
                          example: [summary, bio]
                        costTier:
                          type: string
                          example: low

  /score/lead:
    post:
      summary: Score a lead
      description: Evaluate a startup or individual and predict their likelihood to engage with GCN services (pitch, booth, ticket, premium)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [lead]
              properties:
                lead:
                  type: object
                  description: Lead data with various fields (5-40 fields)
                  example:
                    name: Alice Johnson
                    company: TechStartup Inc
                    role: Founder & CEO
                    raiseAmount: 500000
                    stage: Seed
                    industry: Fintech
                model:
                  type: string
                  description: AI model to use (optional, default gpt-4o)
                  enum: [gpt-4o, gpt-4o-mini, claude-3.5-sonnet]
                  example: gpt-4o
      responses:
        '200':
          description: Lead scores with reasoning
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  model:
                    type: string
                    example: gpt-4o
                  scores:
                    type: object
                    properties:
                      pitchScore:
                        type: number
                        minimum: 0
                        maximum: 10
                        example: 7.5
                      boothScore:
                        type: number
                        minimum: 0
                        maximum: 10
                        example: 4
                      ticketScore:
                        type: number
                        minimum: 0
                        maximum: 10
                        example: 8
                      premiumScore:
                        type: number
                        minimum: 0
                        maximum: 10
                        example: 6
                      reasoning:
                        type: object
                        properties:
                          pitch:
                            type: string
                            example: Early-stage fintech with clear fundraising need.
                          booth:
                            type: string
                            example: Limited B2B focus for booth value.
                          ticket:
                            type: string
                            example: Strong founder profile for networking.
                          premium:
                            type: string
                            example: Moderate professional credentials.

  /score/investor:
    post:
      summary: Score an investor
      description: Evaluate an investor profile across 6 dimensions with overall score
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [investor]
              properties:
                investor:
                  type: object
                  description: Investor data with various fields (5-100 fields)
                  example:
                    name: John Smith
                    type: Angel Investor
                    checkSize: 50000
                    preferredStages: [Pre-seed, Seed]
                    industries: [Fintech, SaaS]
                    location: San Francisco
                model:
                  type: string
                  description: AI model to use (optional, default gpt-4o)
                  enum: [gpt-4o, gpt-4o-mini, claude-3.5-sonnet]
                  example: gpt-4o
      responses:
        '200':
          description: Investor scores with reasoning
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  model:
                    type: string
                    example: gpt-4o
                  scores:
                    type: object
                    properties:
                      overallInvestorScore:
                        type: number
                        minimum: 0
                        maximum: 10
                        example: 7.8
                      scores:
                        type: object
                        properties:
                          capitalStrength:
                            type: number
                            example: 8
                          dealVelocity:
                            type: number
                            example: 7
                          sectorAlignment:
                            type: number
                            example: 9
                          experienceTrackRecord:
                            type: number
                            example: 7
                          networkStrength:
                            type: number
                            example: 8
                          reputationSignal:
                            type: number
                            example: 7
                      reasoning:
                        type: object
                        properties:
                          capitalStrength:
                            type: string
                            example: Strong check size and portfolio
                          overall:
                            type: string
                            example: Highly qualified investor

  /score/startup:
    post:
      summary: Score a startup (GDF Investability Matrix)
      description: Evaluate a startup across 8 dimensions with overall investability score
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [startup]
              properties:
                startup:
                  type: object
                  description: Startup data with various fields (5-200 fields)
                  example:
                    name: TechVenture AI
                    industry: AI/ML
                    stage: Seed
                    revenue: 100000
                    growth: 15% MoM
                    teamSize: 5
                model:
                  type: string
                  description: AI model to use (optional, default gpt-4o)
                  enum: [gpt-4o, gpt-4o-mini, claude-3.5-sonnet]
                  example: gpt-4o
      responses:
        '200':
          description: Startup investability scores with reasoning
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  model:
                    type: string
                    example: gpt-4o
                  scores:
                    type: object
                    properties:
                      overallInvestabilityScore:
                        type: number
                        minimum: 0
                        maximum: 10
                        example: 8.2
                      scores:
                        type: object
                        properties:
                          team:
                            type: number
                            example: 9
                          traction:
                            type: number
                            example: 7
                          market:
                            type: number
                            example: 9
                          competitiveAdvantage:
                            type: number
                            example: 8
                          businessModel:
                            type: number
                            example: 7
                          pitchQuality:
                            type: number
                            example: 8
                          profileCompleteness:
                            type: number
                            example: 8
                          riskLevel:
                            type: number
                            example: 7
                      reasoning:
                        type: object
                        properties:
                          team:
                            type: string
                            example: Exceptional team with Google experience
                          overall:
                            type: string
                            example: Highly investable with strong team

  /ai/summary:
    post:
      summary: Generate startup summary
      description: Create a concise 1-2 paragraph summary of a startup (max 600 characters)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [description]
              properties:
                startupName:
                  type: string
                  example: Acme AI
                description:
                  type: string
                  example: We build AI-powered tools for small businesses to automate their customer service...
                industry:
                  type: string
                  example: AI/ML
                stage:
                  type: string
                  example: Seed
                model:
                  type: string
                  description: AI model to use (optional, default gpt-4o-mini)
                  enum: [gpt-4o-mini, gpt-4o, claude-3.5-sonnet]
                  example: gpt-4o-mini
      responses:
        '200':
          description: Generated summary
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  model:
                    type: string
                    example: gpt-4o-mini
                  summary:
                    type: string
                    example: Acme AI is a platform that provides AI-powered customer service automation for small businesses...

  /ai/bio:
    post:
      summary: Generate founder bio
      description: Create a concise third-person bio for a founder (max 600 characters)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name:
                  type: string
                  example: Jane Doe
                role:
                  type: string
                  example: Founder & CEO
                background:
                  type: string
                  example: Former Google engineer with 10 years in ML, Stanford CS grad...
                company:
                  type: string
                  example: Acme AI
                tone:
                  type: string
                  enum: [professional, casual, investor-facing]
                  example: professional
                model:
                  type: string
                  description: AI model to use (optional, default gpt-4o-mini)
                  enum: [gpt-4o-mini, gpt-4o, claude-3.5-sonnet]
                  example: gpt-4o-mini
      responses:
        '200':
          description: Generated bio
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  model:
                    type: string
                    example: gpt-4o-mini
                  bio:
                    type: string
                    example: Jane Doe is the Founder & CEO of Acme AI, bringing over 10 years of machine learning expertise...

  /ai/image:
    post:
      summary: Generate images with DALL-E
      description: Generate images using OpenAI DALL-E models
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [prompt]
              properties:
                prompt:
                  type: string
                  example: A professional logo for a tech startup
                model:
                  type: string
                  description: AI model to use (optional, default dall-e-3)
                  enum: [dall-e-2, dall-e-3]
                  example: dall-e-3
                size:
                  type: string
                  description: Image size (optional, default 1024x1024)
                  enum: [1024x1024, 1792x1024, 1024x1792, 256x256, 512x512]
                  example: 1024x1024
                quality:
                  type: string
                  description: Image quality (optional, default standard)
                  enum: [standard, hd]
                  example: standard
      responses:
        '200':
          description: Generated image
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  model:
                    type: string
                    example: dall-e-3
                  size:
                    type: string
                    example: 1024x1024
                  quality:
                    type: string
                    example: standard
                  prompt:
                    type: string
                    example: A professional logo for a tech startup
                  images:
                    type: array
                    items:
                      type: object
                      properties:
                        url:
                          type: string
                          example: https://...
                        revised_prompt:
                          type: string
                          example: A modern, minimalist logo...

  /ai/generate:
    post:
      summary: Generic generation with model router
      description: Advanced endpoint for custom AI generation tasks with flexible model selection
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [task, input]
              properties:
                task:
                  type: string
                  enum: [summary, bio, custom]
                  example: summary
                input:
                  type: object
                  description: Task-specific input fields
                  example:
                    description: A fintech startup...
                model:
                  type: string
                  enum: [gpt-4o-mini, gpt-4o, claude-3.5-haiku, claude-3.5-sonnet]
                  example: gpt-4o-mini
      responses:
        '200':
          description: Generated output
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  task:
                    type: string
                    example: summary
                  model:
                    type: string
                    example: gpt-4o-mini
                  output:
                    type: string
                    example: Generated content...
