🏷️ Project Title

ANIS – Personal AI Factory Controller

🧾 Executive Summary

ANIS (Autonomous Neural Intelligence Supervisor) is an enterprise-grade Personal AI Factory Controller designed to orchestrate complex data ingestion, transformation, analysis, and reporting workflows through a single, intent-driven interface. The system combines Custom GPT Actions, n8n workflow orchestration, Google Workspace automation, and a serverless OCR microservice to deliver a fully automated, auditable, scalable, and production-ready AI data pipeline.

ANIS is intentionally engineered as a control plane, not a monolithic processor. It delegates execution to specialized agents (Ingest, Clean, Analyze, Report) while enforcing strict contracts, schemas, logging, and observability across the entire data lifecycle.

📑 Table of Contents

🧩 Project Overview
🧠 System Philosophy & Design Principles
🎯 Objectives & Goals
✅ Acceptance Criteria
💻 Prerequisites
⚙️ Installation & Setup
🔗 API Documentation
🤖 Custom GPT Configuration
🖥️ UI / Frontend Architecture
🔢 Status Codes
🚀 Features
🧱 Tech Stack & Architecture
🛠️ Workflow & Implementation
🧠 Agent Responsibilities
🗄️ Data Lake Design
🧪 Testing & Validation
🔍 Validation Summary
🧰 Verification Tools
🧯 Troubleshooting
🔒 Security & Secrets
☁️ Deployment
⚡ Quick-Start Cheat Sheet
🧾 Usage Notes
🧠 Performance & Optimization
🌟 Enhancements
🧩 Maintenance & Future Work
🏆 Key Achievements
🧮 High-Level Architecture
🗂️ Folder Structure
🧭 How to Demonstrate Live
💡 Summary, Closure & Compliance

🧩 Project Overview

ANIS provides a unified command interface that allows users (human or system) to trigger complex automation pipelines using a single structured JSON command. The platform abstracts away workflow complexity while preserving transparency, traceability, and governance.

Core capabilities include:

Automated Gmail attachment ingestion
RAW → CLEAN → GOLD data lake transitions
OCR-based PDF text extraction
Structured normalization of CSV, XLS, JSON, TXT
AI-driven analysis and KPI generation
Daily scheduled execution via cron

🧠 System Philosophy & Design Principles

Single Responsibility Agents – Each agent performs exactly one domain function
Contract-First Design – All interactions validated via schemas
Auditability by Default – Every action logged
Stateless Execution – Workflows remain restart-safe
Enterprise Observability – Logs, metrics, and artifacts persisted

🎯 Objectives & Goals

Establish a centralized AI automation control plane driven by structured intent
Enable deterministic, schema-driven execution across ingestion, cleaning, analysis, and reporting
Decouple AI reasoning (GPT) from execution logic (n8n workflows)
Provide audit-ready data pipelines with full traceability
Support both interactive (on-demand) and scheduled automation

✅ Acceptance Criteria

Area	Acceptance Requirement
API	All requests validated via OpenAPI and JSON schemas
Agents	Each agent executes independently with clear responsibility
Data	RAW → CLEAN → GOLD data lifecycle enforced
Logging	Every execution logged with timestamp and status
Security	No secrets committed to repository
Scheduling	Cron workflows execute without manual intervention

💻 Prerequisites

Node.js ≥ 18
n8n ≥ 1.x (self-hosted or cloud)
Google Workspace (Gmail, Drive, Sheets)
OpenAI API access
Vercel account for OCR microservice

⚙️ Installation & Setup

Clone the repository
Create environment variables from .env.example
Install serverless dependencies
Import n8n workflows (agents, interactive, scheduled)
Configure Google OAuth credentials
Deploy OCR service on Vercel

🔗 API Documentation

Endpoint:

POST /webhook/anis

Core Request Fields:

Field	Description
agent	Target agent (ingest \| clean \| analyze \| report)
source	Optional data source parameters
options	Execution controls
return	Expected response format

All requests and responses are validated against versioned schemas to ensure backward compatibility and contract safety.

🧠 Custom GPT Configuration

Component	Purpose
action-schema.yaml	Defines allowed commands and payload structure
instructions.md	Constrains GPT behavior and output format
description.md	System-level role definition
conversation-starters.md	Guided user interaction examples

GPT operates strictly as an intent interpreter. It does not execute logic directly and cannot bypass schemas or workflows.

🖥️ UI / Frontend: Pages, Components, State Flow

This project intentionally avoids a traditional UI layer. Instead, it uses:

Custom GPT as the conversational interface
n8n as the visual execution canvas
Google Sheets as operational dashboards

State Flow:

User Intent → GPT → Webhook → Workflow State → Logs / Files

Styling, visualization, and reporting are delegated to Google Workspace and GPT responses.

🔢 Status Codes

Code	Meaning
200	Success
400	Invalid payload
401	Unauthorized
500	Execution failure

🚀 Features

ANIS (Autonomous Neural Intelligence Supervisor) is a production-grade AI Factory Control Plane that unifies LLM intent, workflow orchestration, and enterprise data engineering into a single deterministic, auditable, and scalable platform. Unlike typical AI automations, ANIS enforces strict governance, contract-first execution, and end-to-end data lineage.

1. Core Capability Domains

Domain	Capability	Enterprise-Grade Implementation
AI Governance	Schema-Locked GPT Control	GPT is sandboxed by OpenAPI + JSON Schema. It cannot generate arbitrary commands or bypass workflows.
Orchestration	Agent-Based Execution Fabric	Each business function is isolated into independently deployable Ingest, Clean, Analyze, and Report agents.
Data Engineering	RAW → CLEAN → GOLD Data Lake	Immutable RAW inputs, reproducible CLEAN data, and versioned GOLD analytics.
Observability	Enterprise Event Ledger	Every API call, transformation, KPI, and file write is logged into Google Sheets with timestamps.
Unstructured Data	OCR & Document Intelligence	Serverless OCR extracts text from PDFs and images and feeds it into the CLEAN pipeline.
Automation	Cron-Driven Autonomy	Fully automated daily execution via scheduled workflows.

2. Feature Execution Flow

User / System
      ↓
Custom GPT (Intent → Structured JSON)
      ↓
OpenAPI Schema Validation
      ↓
n8n Control Plane
      ↓
Ingest → Clean → Analyze → Report
      ↓
Enterprise Data Lake + KPI Ledger

🧱 Tech Stack & Architecture

1. Technology Layers

Layer	Technology	Role
AI Interface	Custom GPT + OpenAPI	Intent parsing, schema-validated command generation
Orchestration	n8n	Workflow execution engine and control plane
Data Lake	Google Drive	RAW / CLEAN / GOLD storage
Metadata & Logs	Google Sheets	Catalogs, KPIs, audit trails
OCR	Vercel Serverless	PDF & image text extraction
Contracts	JSON Schema + YAML	Validation and deterministic execution

2. Control Plane Architecture

┌──────────────┐
│ User / API   │
└──────┬───────┘
       ↓
┌──────────────────────┐
│ Custom GPT           │
│ (Intent Interpreter) │
└──────┬───────────────┘
       ↓
┌──────────────────────┐
│ OpenAPI + JSON Schema│
│ (Contract Layer)     │
└──────┬───────────────┘
       ↓
┌──────────────────────┐
│ n8n Orchestration    │
│ (Execution Fabric)  │
└──────┬───────────────┘
       ↓
┌─────────────────────────────┐
│ Ingest | Clean | Analyze |  │
│ Report (Stateless Agents)   │
└──────┬──────────────────────┘
       ↓
┌─────────────────────────────┐
│ Google Drive (RAW/CLEAN/GOLD)│
│ Google Sheets (Logs/KPIs)    │
└─────────────────────────────┘

🛠️ Workflow & Implementation

1. End-to-End Execution Pipeline

User Prompt
   ↓
GPT → Intent → JSON Command
   ↓
OpenAPI Schema Validation
   ↓
ANIS Webhook
   ↓
n8n Control Plane
   ↓
Agent Pipelines
   ↓
Data Lake + KPI Ledger

2. Agent Workflow Topology

        ┌─────────────┐
        │   Ingest    │ → Gmail, APIs, Drive
        └─────┬───────┘
              ↓
        ┌─────────────┐
        │    Clean    │ → Normalize, OCR, validate
        └─────┬───────┘
              ↓
        ┌─────────────┐
        │   Analyze   │ → KPIs, metrics, insights
        └─────┬───────┘
              ↓
        ┌─────────────┐
        │   Report    │ → Summaries, links
        └─────────────┘

3. Reliability & Determinism

Stateless workflows allow safe retries.
Schema validation prevents malformed executions.
All data transformations are reproducible.
Failures are isolated to individual agents.

🧠 Agent Responsibilities

Agent	Primary Responsibility	Key Outputs
Ingest Agent	Acquire raw data from external sources (Gmail, Drive, APIs)	RAW files, metadata entries
Clean Agent	Normalize, validate, and convert raw data into structured formats	CLEAN datasets (CSV / JSON)
Analyze Agent	Compute KPIs, metrics, and analytical insights	GOLD datasets, KPI tables
Report Agent	Generate summaries, reports, and shareable outputs	Reports, Drive links

Each agent is independently deployable, restart-safe, and stateless, ensuring fault isolation and operational resilience.

🗄️ Data Lake Design

ANIS enforces a strict, enterprise-grade data lake lifecycle to guarantee traceability, reproducibility, and governance.

Zone	Description	Mutability
RAW	Original ingested data (unchanged, immutable)	Read-only
CLEAN	Normalized, schema-aligned datasets	Rebuildable
GOLD	Analytics-ready, business-consumable outputs	Versioned

RAW → CLEAN → GOLD

🧪 Testing & Validation

ID	Area	Command	Expected Output	Explanation
T01	Ingest	POST /webhook/anis	RAW files created	Gmail ingestion
T02	Clean	Agent clean	CLEAN files created	Normalization

🔍 Validation Summary

All inbound requests validated via OpenAPI schemas
All transformations validated against structural schemas
All outputs verified before persistence
No silent failures or implicit transformations

Validation is enforced at every boundary to ensure deterministic behavior across environments.

🧰 Verification Tools

Tool	Purpose
Postman	Manual API verification
n8n UI	Workflow execution tracing
Google Sheets	Log and KPI verification
Drive Audit Logs	Artifact validation

🧯 Troubleshooting

Issue	Likely Cause	Resolution
Webhook returns 400	Schema violation	Validate request payload
No files generated	OAuth permission issue	Reauthorize Google credentials
Scheduled job not running	Cron workflow disabled	Enable workflow in n8n

🔒 Security & Secrets

Secrets stored in .env
OAuth credentials isolated
Webhook endpoints protected

☁️ Deployment (Vercel)

Serverless OCR deployment
Environment isolation
Stateless execution model

⚡ Quick-Start Cheat Sheet

git clone repo
cp .env.example .env
npm install
n8n start

🧾 Usage Notes

Designed for non-technical operators
All execution controlled via structured intent
No manual data manipulation required
Safe for repeated execution

🧠 Performance & Optimization

Parallel agent execution where applicable
Stateless workflows reduce memory overhead
Incremental processing minimizes rework
Serverless OCR scales automatically

🌟 Enhancements

Multi-tenant support
Role-based access control
Advanced KPI dashboards
Pluggable data sources

🧩 Maintenance & Future Work

Schema versioning strategy
Automated regression validation
Agent marketplace expansion
Enterprise monitoring integration

🏆 Key Achievements

Production-grade AI control plane
Full auditability and governance
Zero hardcoded logic
Enterprise-ready automation framework

🧮 High-Level Architecture

┌──────────────────┐
│  Human / System  │
└───────┬──────────┘
        ↓
┌────────────────────────┐
│   Custom GPT Control   │
│   (Intent → JSON)      │
└───────┬────────────────┘
        ↓
┌────────────────────────┐
│ OpenAPI + JSON Schema  │
│ (Contract Enforcement)│
└───────┬────────────────┘
        ↓
┌────────────────────────┐
│     n8n Control Plane  │
│  (Workflow Execution) │
└───────┬────────────────┘
        ↓
┌────────────────────────────────┐
│ Ingest → Clean → Analyze →      │
│ Report (Stateless AI Agents)    │
└───────┬────────────────────────┘
        ↓
┌────────────────────────────────┐
│ Google Drive (RAW/CLEAN/GOLD)   │
│ Google Sheets (Logs & KPIs)    │
└────────────────────────────────┘

This architecture guarantees governed, deterministic, and auditable AI execution, making ANIS suitable for enterprise analytics, compliance-driven workflows, and production-grade AI operations.

🗂️ Folder Structure (Tree)

ANIS-PERSONAL-AI-FACTORY-CONTROLLER/
│
├── diagrams/
│   ├── high-level-architecture.png
│   ├── gpt-execution-flow.png
│   ├── scheduled-execution-flow.png
│   └── data-lake-layout.png
│
├── gpt/
│   ├── action-schema.yaml
│   ├── instructions.md
│   ├── description.md
│   ├── conversation-starters.md
│   └── name.md
│
├── schemas/
│   ├── webhook-request.schema.json
│   ├── webhook-response.schema.json
│   └── control-sheet.schema.md
│
├── screenshots/
│   ├── google-drive/
│   ├── google-sheets/
│   │   ├── data-catalog/
│   │   ├── event-log/
│   │   └── tasks-inbox/
│   ├── gpt-controller/
│   └── workflows/
│       ├── interactive/
│       └── scheduled/
│
├── serverless/
│   └── ocr-pdf-text-extraction-service/
│
├── workflows/
│   ├── agents/
│   │   ├── ingest_agent.json
│   │   ├── clean_agent.json
│   │   ├── analyze_agent.json
│   │   └── report_agent.json
│   │
│   ├── interactive/
│   │   └── ANIS_HUB_gpt_webhook.json
│   │
│   └── scheduled/
│       ├── ANIS_DAILY_CRON.json
│       ├── analyze_agent_sub_workflow.json
│       └── report_agent_sub_workflow.json
│
├── .env.example
├── .gitignore
└── README.md

🧭 How to Demonstrate Live (Exact Commands)

This section provides a fully explicit, end-to-end live demonstration guide for the ANIS Personal AI Factory Controller. It is intentionally verbose and operationally precise to enable live demos, technical interviews, architecture walkthroughs, and stakeholder reviews without ambiguity.

1. Demonstration Entry Points

Primary (Recommended): Custom GPT → OpenAPI Action → n8n Webhook
Secondary: Direct API/Webhook invocation (Postman / curl)
Automated: Scheduled execution via cron workflows

2. GPT Prompt → Webhook Dispatch Flow

Example GPT Prompt:

Ingest Gmail attachments from the last 7 days, clean and normalize the data,
analyze the results, and generate a report.

Internal Execution Flow:

Custom GPT interprets user intent
Prompt is validated against the OpenAPI action schema
GPT generates a single, schema-compliant JSON command
Command is dispatched to the ANIS webhook
n8n orchestrates agent-based workflows
Outputs are written to Google Drive and Google Sheets
Structured results are returned to GPT

3. Direct Webhook API Demonstration

Endpoint

POST /webhook/anis

Headers

Content-Type: application/json

4. Ingest Agent – API Call

{
  "agent": "ingest",
  "source": {
    "gmailQuery": "has:attachment",
    "days": 7
  },
  "options": {
    "attachmentsOnly": true,
    "fileTypes": ["pdf", "csv", "xlsx"]
  },
  "return": "summary"
}

Expected Results:

Attachments fetched from Gmail
Files uploaded to Google Drive (RAW zone)
Metadata recorded in DATA_CATALOG
Execution logged in EVENT_LOG

5. Clean Agent – API Call

{
  "agent": "clean",
  "return": "log"
}

Expected Results:

RAW files normalized and converted
CLEAN datasets generated (CSV / JSON / TXT)
Schema-aligned data structures enforced
Transformation events logged

6. Analyze Agent – API Call

{
  "agent": "analyze",
  "return": "kpis"
}

Expected Results:

CLEAN datasets analyzed
KPIs computed and validated
GOLD datasets produced
Analysis outputs appended to DATA_CATALOG

7. Report Agent – API Call

{
  "agent": "report",
  "return": "files"
}

Expected Results:

Final reports generated
Summaries and KPIs consolidated
Reports uploaded to Google Drive
Shareable links returned in response

8. Scheduled Execution Demonstration

Enable the ANIS_DAILY_CRON workflow in n8n to demonstrate:

Autonomous ingestion
Automatic cleaning and normalization
Scheduled analysis and reporting
Zero manual intervention

9. Where to Observe Outputs

Component	Location
RAW Files	Google Drive → RAW
CLEAN Data	Google Drive → CLEAN
GOLD Outputs	Google Drive → GOLD
Event Logs	Google Sheets → EVENT_LOG
KPIs	Google Sheets → DATA_CATALOG
Reports	Google Drive → REPORT

💡 Summary, Closure & Compliance

ANIS represents a mature, enterprise-grade AI automation control plane designed with explicit emphasis on governance, determinism, auditability, and production readiness.

Architectural Maturity

Agent-based workflows enforce strict separation of concerns
Each agent operates with a single, clearly defined responsibility
Schema-driven execution eliminates ambiguity and non-determinism
Stateless orchestration enables safe retries and fault tolerance

Schema-Driven & Deterministic Execution

All inputs validated against OpenAPI and JSON schemas
Controlled data normalization and conversion pipelines
Predictable outputs across environments
No implicit or hidden execution paths

Auditability & Traceability

Every action logged with timestamps and agent identity
RAW → CLEAN → GOLD data lineage enforced
Event logs provide full execution history
Outputs are reproducible and reviewable

Security & Secret Management

No credentials committed to source control
Environment-based secret injection
OAuth scopes isolated per service
Webhook contracts enforced via schemas

Operational Reliability

Supports both interactive and scheduled execution
Designed for non-technical operators
Failure isolation at agent level
Production-safe by default

Final Closure

ANIS is not a prototype or experimental build. It is a well-engineered, enterprise-ready automation system that demonstrates how AI-driven intent, workflow orchestration, and governed data pipelines can be unified into a single, compliant, extensible platform.

The project stands as a reference implementation for modern, schema-driven, agent-based automation systems suitable for real-world production environments.

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
diagrams		diagrams
gpt		gpt
schemas		schemas
screenshots		screenshots
serverless		serverless
workflows		workflows
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

🏷️ Project Title

ANIS – Personal AI Factory Controller

🧾 Executive Summary

📑 Table of Contents

🧩 Project Overview

🧠 System Philosophy & Design Principles

🎯 Objectives & Goals

✅ Acceptance Criteria

💻 Prerequisites

⚙️ Installation & Setup

🔗 API Documentation

🧠 Custom GPT Configuration

🖥️ UI / Frontend: Pages, Components, State Flow

🔢 Status Codes

🚀 Features

1. Core Capability Domains

2. Feature Execution Flow

🧱 Tech Stack & Architecture

1. Technology Layers

2. Control Plane Architecture

🛠️ Workflow & Implementation

1. End-to-End Execution Pipeline

2. Agent Workflow Topology

3. Reliability & Determinism

🧠 Agent Responsibilities

🗄️ Data Lake Design

🧪 Testing & Validation

🔍 Validation Summary

🧰 Verification Tools

🧯 Troubleshooting

🔒 Security & Secrets

☁️ Deployment (Vercel)

⚡ Quick-Start Cheat Sheet

🧾 Usage Notes

🧠 Performance & Optimization

🌟 Enhancements

🧩 Maintenance & Future Work

🏆 Key Achievements

🧮 High-Level Architecture

🗂️ Folder Structure (Tree)

🧭 How to Demonstrate Live (Exact Commands)

1. Demonstration Entry Points

2. GPT Prompt → Webhook Dispatch Flow

3. Direct Webhook API Demonstration

Endpoint

Headers

4. Ingest Agent – API Call

5. Clean Agent – API Call

6. Analyze Agent – API Call

7. Report Agent – API Call

8. Scheduled Execution Demonstration

9. Where to Observe Outputs

💡 Summary, Closure & Compliance

Architectural Maturity

Schema-Driven & Deterministic Execution

Auditability & Traceability

Security & Secret Management

Operational Reliability

Final Closure

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Packages