Week 1: Python & LLM Fundamentals

Neural Foundation Workbench

Integrated production console for foundational generative AI and agent engineering. This project unifies four core engineering domains into a single deployable system with a unified dashboard, REST API, and Docker packaging.

What this project covers

This workbench is the capstone integration for the Python & LLM Fundamentals track. It combines concepts and patterns from four standalone reference implementations into one cohesive platform:

Dashboard tabs

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    React Dashboard (:3200)                   │
│  Overview │ Gateway │ Attention │ Registry                   │
└──────────────────────────┬──────────────────────────────────┘
                           │ REST / WebSocket proxy
┌──────────────────────────▼──────────────────────────────────┐
│                   FastAPI Backend (:8200)                    │
│  runtime/ │ gateway/ │ attention/ │ registry/                 │
└─────────────────────────────────────────────────────────────┘

Stack: Python 3.12 · FastAPI · Pydantic v2 · NumPy · Vite · React 19 · Recharts · Docker (nginx + slim images)

Prerequisites

• Python 3.12+

• Node.js 20+ and npm

• Docker Desktop (optional)

Implementation Guide

GitHub Link

https://github.com/sysdr/vertical-ai-agent-p/tree/main/week1/neural-foundation-workbench

This document describes how the integrated workbench is built, how the four engineering domains connect, and how to extend or operate the system in production.

Project root: neural-foundation-workbench/

1. Integration overview

The workbench merges four foundational reference implementations into one repository:

Reference domain          →  Workbench module          →  Dashboard tab
─────────────────────────────────────────────────────────────────────
Python environment setup  →  backend/app/runtime/      →  Platform Overview
Advanced Python patterns  →  backend/app/gateway/    →  Inference Gateway
Transformer deep dive     →  backend/app/attention/    →  Attention Engine
LLM parameter analysis    →  backend/app/registry/     →  Model Registry

Each module is independently testable. The FastAPI main.py file is a thin orchestration layer that mounts routes and shares configuration via app/config.py.

2. Backend modules

2.1 Runtime (backend/app/runtime/)

Purpose: Validate the Python execution environment before any AI workload runs.

Key file: validator.py

Design decisions:

• Uses importlib rather than shelling out to pip list for speed and portability.

• Exposes /api/runtime/status for dashboard dependency matrix rendering.

• Fails soft: /health returns degraded when packages are missing rather than crashing.

Extension point: Add packages to REQUIRED_PACKAGES when new backend dependencies become critical path.

2.2 Gateway (backend/app/gateway/)

Purpose: Demonstrate production-grade async agent request handling with type-safe contracts.

Key files:

Request flow:

POST /api/gateway/process
    │
    ▼
GatewayRequest validation (agent_id pattern, prompt limits)
    │
    ▼
process_prompts_with_cache_flag()
    ├── @with_cache (120s TTL, in-memory)
    ├── @with_performance_tracking (latency + counters)
    └── per-prompt _infer_single() with @with_retry
    │
    ▼
GatewayResponse (results, latency_ms, cached flag, timestamp)

Agent ID contract: ^agent-[a-z0-9]{8}$ — enforced at the Pydantic layer before any processing.

Inference mode: Simulated async responses by default. Set GEMINI_API_KEY in .env to enable live provider integration (extend processor.py).

Metrics: Global dict in decorators.py powers /api/gateway/metrics and the Overview history chart.

2.3 Attention (backend/app/attention/)

Purpose: Conceptual transformer encoder — not trained, but mechanically correct for education and visualization.

Key file: transformer.py

Request flow:

POST /api/attention/transform  { "text": "..." }
    │
    ▼
SimpleTokenizer.tokenize()
    │
    ▼
create_embeddings() → np.ndarray [1, seq_len, d_model]
    │
    ▼
TransformerEncoder.forward()  (async per-layer)
    │
    ▼
Response: tokens, attention_weights[], layer_outputs_shape, latency_ms

Configuration (via .env or Settings):

SettingDefaultConstraintD_MODEL128Must be divisible by NUM_HEADSNUM_HEADS4—NUM_LAYERS2—

WebSocket: /ws/attention streams token and per-layer attention events for real-time clients.

2.4 Registry (backend/app/registry/)

Purpose: Model selection economics — parameters, context windows, pricing, and comparative analytics.

Key files:

Cost model:

per_request_cost =
    cached_input_tokens  × cache_hit_rate  × cached_price/1M
  + uncached_input_tokens × (1-cache_hit) × input_price/1M
  + output_tokens × output_price/1M

Context analysis: Computes p50/p95/p99 token distribution and recommends a context limit covering 99% of samples.

Dashboard charts: RegistryPanel.jsx renders Recharts bar (monthly cost) and line (latency) charts from /api/registry/compare.

3. Frontend architecture

3.1 Structure

frontend/src/
├── App.jsx              # Shell, tab navigation, health polling
├── App.css              # Design tokens, layout, chart panels
├── api/client.js        # fetch wrappers (relative URLs for nginx proxy)
└── components/
    ├── OverviewPanel.jsx    # Runtime + gateway metrics history (Recharts)
    ├── GatewayPanel.jsx     # Async batch form
    ├── AttentionPanel.jsx   # Encoder run + heatmap grid
    └── RegistryPanel.jsx    # Comparison charts + cost projection

3.2 API client

api/client.js uses relative paths ("" base) so the same code works in:

• Local dev — Vite proxy forwards /api → localhost:8200

• Docker — nginx proxies /api → backend:8200

3.3 Chart rendering

All ResponsiveContainer instances use explicit height={280} to prevent zero-height blank charts in production builds.

4. Configuration

File: neural-foundation-workbench/backend/app/config.py

Uses pydantic-settings with .env file loading:

class Settings(BaseSettings):
    gemini_api_key: str = ""
    host: str = "0.0.0.0"
    port: int = 8200
    d_model: int = 128
    num_heads: int = 4
    num_layers: int = 2

Copy neural-foundation-workbench/.env.example → .env on first run (start.sh does this automatically).

5. Scripts reference

All scripts live in neural-foundation-workbench/scripts/:

Independence: No script requires a parent setup.sh. Clone the repo, cd neural-foundation-workbench, run build.sh, then start.sh.

6. Docker architecture

neural-foundation-workbench/docker-compose.yml
├── backend   python:3.12-slim-bookworm  →  :8200
└── frontend  node:22 (build) + nginx:1.27-alpine  →  :3200

nginx.conf proxies:

• /api/* → http://backend:8200

• /health → backend

• /ws/* → backend (WebSocket upgrade)

Build context: neural-foundation-workbench/ — Dockerfiles copy backend/ and frontend/ respectively.

7. Testing strategy

Location: neural-foundation-workbench/backend/tests/ — 20 tests across five files.

Run:

cd neural-foundation-workbench
./scripts/test.sh

Async tests: pytest.ini sets asyncio_mode = auto.

8. Security notes

• No API keys are committed. .env is gitignored.

• GEMINI_API_KEY defaults to empty string; gateway simulates responses.

• CORS is open (*) for local development — restrict origins in production.

• Pydantic validates all inbound gateway and registry payloads before processing.

9. Extension patterns

Add a new model to the registry

Edit backend/app/registry/catalog.py → MODEL_CATALOG dict. Analytics functions pick it up automatically.

Wire live LLM inference in the gateway

In backend/app/gateway/processor.py, replace _simulate_inference with an httpx/aiohttp call to your provider, reading settings.gemini_api_key.

Add a dashboard tab

1. Create frontend/src/components/NewPanel.jsx

2. Register tab in App.jsx TABS array

3. Add backend routes in main.py under a new app/ subpackage

Scale attention model

Increase D_MODEL, NUM_HEADS, NUM_LAYERS in .env. Ensure d_model % num_heads == 0.

10. Troubleshooting

11. Dependency versions

12. Operational checklist

First-time setup:

cd neural-foundation-workbench
cp .env.example .env
./scripts/build.sh
./scripts/test.sh
./scripts/start.sh

Before git push:

cd neural-foundation-workbench
./scripts/cleanup.sh

Production Docker deploy:

cd neural-foundation-workbench
docker compose up --build -d
curl http://localhost:8200/health
curl http://localhost:3200

Quick start

cd neural-foundation-workbench
./scripts/build.sh    # venv, pip install, npm install, frontend build
./scripts/start.sh    # backend :8200 + dev dashboard :3200
./scripts/demo.sh     # API smoke test (requires running backend)
./scripts/test.sh     # pytest suite (20 tests)
./scripts/stop.sh     # stop local processes

Open

http://localhost:3200

· API docs at http://localhost:8200/docs

Docker deployment

cd neural-foundation-workbench
docker compose up --build -d
docker compose down

ServiceURLDashboard:

http://localhost:3200

API:

http://localhost:8200

Environment configuration

cd neural-foundation-workbench
cp .env.example .env

API surface

Project layout

week1/
├── README.md
├── IMPLEMENTATION_GUIDE.md
├── setup.sh
└── neural-foundation-workbench/
    ├── backend/
    │   ├── app/
    │   │   ├── runtime/       # Environment validation
    │   │   ├── gateway/       # Async processing, decorators, schemas
    │   │   ├── attention/     # Transformer encoder implementation
    │   │   └── registry/      # Model catalog & analytics
    │   └── tests/             # 20 pytest cases
    ├── frontend/
    │   └── src/components/    # Dashboard panels per domain
    ├── docker/                # Dockerfile.backend, Dockerfile.frontend, nginx.conf
    ├── scripts/               # build, start, stop, test, demo, cleanup
    ├── requirements.txt       # Python runtime deps
    ├── requirements-dev.txt   # pytest & dev tools
    └── docker-compose.yml

Requirements files

Cleanup

cd neural-foundation-workbench
./scripts/cleanup.sh

Youtube demo link: