IntelFactor Closed-Loop Backend

Bounded, read-only intelligence layer for manufacturing defect root cause analysis.

Overview

This repository contains the backend API for IntelFactor's closed-loop defect analysis system. It provides AI-powered root cause analysis without mutating production systems.

Key Principles

• Intelligence, not automation - Provides insights; humans make decisions
• Read-only - No writes to production tables or equipment control
• Bounded queries - Time windows (1-30 days), row limits (10K events max)
• Evidence-first - All hypotheses backed by data citations

Architecture

IntelBase (React) → Lambda/API Gateway → Bedrock + DynamoDB (read-only)
                                      ↓
                                  S3 (PDF reports)

Full architecture: docs/architecture/MASTER_TECHNICAL_ARCHITECTURE.md

Quick Start

Prerequisites

• Python 3.11+
• AWS CLI configured
• Virtual environment

Setup

# Clone repository
git clone git@github.com:tonesgainz/intelfactor-closedloop.git
cd intelfactor-closedloop

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r backend/requirements.txt
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env with your settings

# Run locally
./scripts/run_local.sh

Test

# Run tests
./scripts/test.sh

# Test API
curl http://localhost:8000/health

Full guide: docs/runbooks/LOCAL_DEV.md

Repository Structure

.
├── backend/                    # FastAPI backend
│   ├── app/                    # Application package
│   │   ├── main.py             # FastAPI entry point
│   │   ├── lambda_handler.py   # Lambda adapter
│   │   ├── api/                # API routes
│   │   ├── closed_loop/        # Core logic (notifier, PDF, providers, trigger)
│   │   ├── streaming/          # Kafka library code
│   │   └── local/              # Mock providers for dev
│   ├── tests/                  # Unit tests
│   └── requirements.txt        # Python dependencies
├── intelfactor/                # Agent implementations
│   └── closed_loop/            # Agents, manager, providers
├── docs/                       # Documentation
│   ├── architecture/           # System design docs
│   └── runbooks/               # Operational guides
├── scripts/                    # Utility scripts
│   ├── run_local.sh            # Run backend locally
│   ├── test.sh                 # Run tests
│   ├── format.sh               # Format code
│   ├── deploy-staging.sh       # Deploy to AWS Lambda
│   └── test-staging.sh         # Test staging deployment
├── infrastructure/             # AWS SAM template
│   └── template.yaml           # Lambda + Function URL
└── README.md                   # This file

API Endpoints

POST /api/v1/closed-loop/defect-rca

Analyze defects and provide root cause analysis.

Request:

{
  "workspace_id": "factory-1",
  "start_time": "2026-02-10T00:00:00Z",
  "end_time": "2026-02-11T00:00:00Z",
  "defect_type": "scratch"
}

Response:

{
  "executive_summary": "Analysis of 47 scratch defects...",
  "hypotheses": [
    {
      "title": "Material Quality Issue - Batch MB-2026-0211",
      "confidence": 0.87,
      "why": ["85% of scratches occurred on units from batch MB-2026-0211"],
      "evidence_uris": ["s3://evidence/..."],
      "tests_to_confirm": ["Visual inspection of remaining batch material"]
    }
  ],
  "action_plan": {
    "immediate": ["Hold batch MB-2026-0211 for QA review"],
    "short_term": ["Contact supplier about material specification"],
    "preventive": ["Add automated surface roughness measurement"]
  },
  "pdf_url": "https://d123.cloudfront.net/reports/...",
  "requires_human_review": true,
  "metadata": { ... }
}

GET /health

Health check endpoint.

Full API docs: http://localhost:8000/docs (when running locally)

Deployment

Staging (Lambda + Function URL)

./scripts/deploy-staging.sh

Deploys to us-east-1 with mock provider (no production data).

Guide: docs/runbooks/STAGING_BACKEND.md

Production

Production deployment uses API Gateway + Lambda in us-west-2 with real DynamoDB access.

Note: Production deployment is NOT part of this repo cleanup. See separate IaC repository.

Integration

IntelBase Frontend

IntelBase (React) consumes this API via feature flag:

const CLOSED_LOOP_API_BASE = import.meta.env.VITE_CLOSED_LOOP_API_BASE;

Guide: docs/runbooks/INTEGRATION_WITH_INTELBASE.md

Development

Run Locally

./scripts/run_local.sh

Run Tests

./scripts/test.sh

Format Code

./scripts/format.sh

Verify Imports

python -m compileall backend/app

Documentation

• Architecture

  • Master Technical Architecture
  • Confluent Kafka Reference
  • Edge Runtime Details
  • Technical Story

• Runbooks

  • Local Development
  • Integration with IntelBase
  • Staging Backend Deployment
  • Demo Runbook
  • Quickstart

Security

Read-Only Principle

• No writes to production tables (Inspections, Defects, Evidence)
• No mutations of edge runtime configuration
• No direct equipment control

Bounded Queries

• Time windows: 1-30 days max
• Row limits: 10,000 events max per query
• No full table scans

Credentials

• Bedrock: IAM role with bedrock:InvokeModel only
• DynamoDB: IAM role with dynamodb:Query and dynamodb:GetItem only
• S3: IAM role with s3:PutObject for reports bucket only

Non-Goals

This system does NOT:

• ❌ Control equipment directly
• ❌ Modify production data
• ❌ Replace human decision-making
• ❌ Provide real-time alerts
• ❌ Store sensitive PII

Contributing

Code Style

• Format: black + ruff
• Type hints: Required for public APIs
• Docstrings: Google style

Testing

• Unit tests: pytest
• Coverage: > 80%
• Integration tests: Mock providers only

Commits

• Conventional commits: feat:, fix:, docs:, etc.
• Sign commits: git commit -S

License

MIT-0 (see LICENSE)

Support

• Issues: GitHub Issues
• Docs: docs/
• Slack: #intelfactor-closed-loop (internal)

---

Built with ❤️ for Manufacturing Excellence