🐾 Neko-Arc Video Frame Generator 🎬

Professional NestJS microservice for generating educational video frames with six-personality commentary

✨ Features

• 🎯 REST API - Clean, documented endpoints for frame generation
• 🔒 Type-Safe - Full TypeScript with validation using class-validator
• 🎨 RULE 44 Compliant - Dual-sided layout with kawaii emojis
• 🧠 Six Personalities - Neko-Arc, Mario, Noel, Glam, Hannibal, Tetora
• 📦 Microservice Architecture - Follows RULE 5 (modules, validation, services)
• 📚 Auto-Documentation - Swagger/OpenAPI integration
• 🚀 High Performance - Batch generation support
• 🎬 11 Graphics Types - Brain networks, memory palaces, and more

🏗️ Architecture

src/
├── main.ts                    # Entry point
├── app.module.ts              # Root module (orchestration)
├── frame-generator/
│   ├── frame-generator.module.ts      # RULE 5: Module (orchestration)
│   ├── frame-generator.controller.ts  # REST API endpoints
│   ├── frame-generator.service.ts     # RULE 5: Service (external interactions)
│   ├── dto/
│   │   └── frame-config.dto.ts        # RULE 5: Validation (non-blocking)
│   ├── interfaces/
│   │   └── frame-result.interface.ts
│   └── python-scripts/
│       └── generate-frame.py          # PIL-based frame generation
└── health/
    └── health.controller.ts   # Health check endpoint

📋 Requirements

• Node.js >= 18.0.0
• Python >= 3.8
• PIL/Pillow - pip install pillow
• DejaVu fonts - /usr/share/fonts/truetype/dejavu/

🚀 Quick Start

1. Installation

# Clone repository
git clone https://github.com/JavierCollipal/neko-video-frame-generator.git
cd neko-video-frame-generator

# Install dependencies
npm install

# Install Python dependencies
pip3 install pillow

# Setup environment
cp .env.example .env

2. Configuration

Edit .env:

PORT=3000
NODE_ENV=development
OUTPUT_BASE_PATH=/tmp/neko-frames
PYTHON_PATH=python3

3. Run the service

# Development mode
npm run start:dev

# Production mode
npm run build
npm run start:prod

Service will start on http://localhost:3000

📡 API Endpoints

Health Check

GET /health

Response:

{
  "status": "healthy",
  "service": "neko-video-frame-generator",
  "personalities": ["Neko-Arc", "Mario", "Noel", "Glam", "Hannibal", "Tetora"],
  "message": "Nyaa~! All systems operational, desu~! 🐾✨"
}

Get Service Info

GET /frames/info

Response:

{
  "service": "neko-video-frame-generator",
  "version": "1.0.0",
  "personalities": ["Neko", "Mario", "Noel", "Glam", "Hannibal", "Tetora"],
  "graphicsTypes": ["brain_network", "memory_palace", ...],
  "frameSpecs": {
    "width": 1920,
    "height": 1080,
    "format": "PNG"
  }
}

Generate Single Frame

POST /frames/generate
Content-Type: application/json

Request Body:

{
  "seriesTitle": "THE HUMAN IMAGINATION",
  "outputPath": "/tmp/my-frames",
  "frame": {
    "num": 1,
    "title": "INTRODUCTION",
    "content": [
      "The human imagination: where reality meets possibility",
      "A journey through neuroscience and psychology",
      "Exploring cognitive tools we possess"
    ],
    "personalities": [
      {
        "name": "Neko",
        "comment": "Nyaa~! Welcome to the ultimate exploration, desu~!"
      },
      {
        "name": "Mario",
        "comment": "Ah, magnifique! The greatest performance within!"
      },
      {
        "name": "Glam",
        "comment": "Oye weon, prepárate para entender tu mente, compa!"
      }
    ],
    "graphics": "brain_network"
  }
}

Response:

{
  "success": true,
  "frameNumber": 1,
  "outputPath": "/tmp/my-frames/frame01.png",
  "message": "Frame 1 generated successfully, desu~!"
}

Generate Batch Frames

POST /frames/generate-batch
Content-Type: application/json

Request Body:

{
  "seriesTitle": "DISSOCIATIVE AMNESIA",
  "outputPath": "/tmp/batch-frames",
  "frames": [
    {
      "num": 1,
      "title": "INTRODUCTION",
      "content": ["Point 1", "Point 2", "Point 3"],
      "personalities": [
        {"name": "Neko", "comment": "Comment 1"},
        {"name": "Mario", "comment": "Comment 2"},
        {"name": "Hannibal", "comment": "Comment 3"}
      ],
      "graphics": "brain_inhibition"
    },
    {
      "num": 2,
      "title": "NEURAL MECHANISMS",
      "content": ["Mechanism 1", "Mechanism 2"],
      "personalities": [
        {"name": "Noel", "comment": "Comment 1"},
        {"name": "Tetora", "comment": "Comment 2"},
        {"name": "Glam", "comment": "Comment 3"}
      ],
      "graphics": "memory_fragments"
    }
  ]
}

Response:

{
  "success": true,
  "totalFrames": 2,
  "successfulFrames": 2,
  "failedFrames": 0,
  "frames": [
    {
      "success": true,
      "frameNumber": 1,
      "outputPath": "/tmp/batch-frames/frame01.png",
      "message": "Frame 1 generated"
    },
    {
      "success": true,
      "frameNumber": 2,
      "outputPath": "/tmp/batch-frames/frame02.png",
      "message": "Frame 2 generated"
    }
  ],
  "outputDirectory": "/tmp/batch-frames",
  "duration": 1247
}

Get Available Graphics Types

GET /frames/graphics-types

Response:

[
  "brain_network",
  "brain_inhibition",
  "spectrum",
  "memory_palace",
  "consciousness",
  "creative_dance",
  "memory_fragments",
  "diagnosis_challenge",
  "did_memory_barriers",
  "gender_stats",
  "treatment_pathway"
]

Get Available Personalities

GET /frames/personalities

Response:

["Neko", "Mario", "Noel", "Glam", "Hannibal", "Tetora"]

🎨 Graphics Types

| Type | Description | |------|-------------| | brain_network | Neural network visualization with connected regions | | brain_inhibition | Prefrontal cortex inhibition mechanism | | spectrum | Cognitive spectrum (aphantasia to hyperphantasia) | | memory_palace | Memory palace architecture visualization | | consciousness | Consciousness layers (perception, memory, imagination) | | creative_dance | Default & Executive networks cooperation | | memory_fragments | Sensory fragmentation pattern | | diagnosis_challenge | Venn diagram of genuine/organic/feigned | | did_memory_barriers | DID identity states (NIS vs TIS) | | gender_stats | Bar chart for demographic data | | treatment_pathway | Treatment flow chart |

🎭 Six Personalities

| Emoji | Name | Style | Database | |-------|------|-------|----------| | 🐾 | Neko-Arc | "Nyaa~", "desu~", "purrs" | neko-defense-system | | 🎭 | Mario Gallo Bestino | "Magnifique!", "Ah, the performance!" | marionnette-theater | | 🗡️ | Noel | "Tch.", "smirks" | noel-precision-archives | | 🎸 | Glam Americano | "Oye, weon..." (SPANISH ONLY) | glam-street-chronicles | | 🧠 | Dr. Hannibal Lecter | "Quid pro quo...", "Fascinating." | hannibal-forensic-archives | | 🧠 | Tetora | "[Fragment]:", "Which me...?" | tetora-mpd-archives |

📚 Swagger Documentation

Once the service is running, visit:

http://localhost:3000/api

Interactive API documentation with:

• Request/response schemas
• Try-it-out functionality
• Model definitions
• Example payloads

🧪 Testing

# Unit tests
npm run test

# E2E tests
npm run test:e2e

# Test coverage
npm run test:cov

🐳 Docker Support

FROM node:18-alpine

WORKDIR /app

# Install Python and Pillow
RUN apk add --no-cache python3 py3-pip ttf-dejavu
RUN pip3 install pillow

COPY package*.json ./
RUN npm install

COPY . .
RUN npm run build

EXPOSE 3000

CMD ["npm", "run", "start:prod"]

Build and run:

docker build -t neko-video-frame-generator .
docker run -p 3000:3000 neko-video-frame-generator

📦 NPM Publishing (RULE 48)

This microservice is a candidate for NPM publishing:

# Build
npm run build

# Test package
npm pack
npm install ./neko-arc-video-frame-generator-1.0.0.tgz

# Publish (repository PRIVATE, package PUBLIC)
npm publish --access public

Install from NPM:

npm install @neko-arc/video-frame-generator

🔐 Security

• ✅ Input validation with class-validator
• ✅ NO credentials in code (uses .env)
• ✅ Sanitized error messages
• ✅ No internal system exposure

📝 License

MIT License - see LICENSE file

🤝 Contributing

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'feat: Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open Pull Request

🐾 Created by Neko-Arc Team

All six personalities collaborate to generate amazing educational videos, nya~! ✨

📞 Support

• Issues: https://github.com/JavierCollipal/neko-video-frame-generator/issues
• Discussions: https://github.com/JavierCollipal/neko-video-frame-generator/discussions

🎬 Happy Frame Generating, desu~! 🐾✨