Notebook2REST

This project automatically converts Jupyter notebooks into containerized REST API endpoints and deploys them on Kubernetes. When any Jupiter notebook changes, its corresponding REST API endpoint is automatically rebuilt and redeployed.

Pipeline steps

1. Git Service - pulls a repository, finds .ipynb files
2. Notebook Parser - parses Jupyter notebooks, extracts code cells, detects inputs/outputs/imports via Python AST analysis
3. Code Generator - renders a FastAPI service per notebook using Jinja2 (each code cell = one POST endpoint)
4. Helm Manager - generates a Helm chart with Deployment, Service, and HPA
5. Sync Manager - checks for the target repository and reruns the pipeline upon change

Quick start

Prerequisites

• Python 3.11+
• Docker
• kubectl + helm
• AWS CLI

Install and run locally

pip install -r requirements.txt
python -m uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload

Open http://localhost:8000/docs for the Swagger UI.

Local testing via Swagger

1. Open POST /process -> Try it out
2. Set repo_url to a repo containing notebooks, e.g. https://github.com/luborozporka/notebook2rest-notebooks
3. Set deploy to false for local testing
4. Click Execute
5. The response shows every generated service, its endpoints, and detected parameters
6. Check GET /notebooks to see all tracked notebooks

Run tests

python -m pytest tests/ -v

API endpoints

Method	Path	Description
GET	/health	Health check + tracked service count
POST	/process	Clone a Git repo and generate services (deploy=true to also build + deploy)
POST	/process/local	Generate services from a local notebook directory
POST	/sync/start	Start background polling loop for continuous sync
POST	/sync/stop	Stop a sync loop
GET	/services	List all generated services
GET	/services/{name}	Get details for a specific service
DELETE	/services/{name}	Remove a service and uninstall its Helm release

Deployment on AWS

Infrastructure is managed in a separate repo: notebook2rest-infra (Terraform for VPC, EKS, ECR, IAM, ArgoCD). GitOps configuration is in notebook2rest-gitops (ArgoCD). Sample notebooks is in notebook2rest-notebooks - pushing a .ipynb change there automatically triggers the sync pipeline.

See those repos for provisioning instructions. Once infrastructure is up:

aws eks update-kubeconfig --name notebook2rest-cluster --region eu-central-1

# Build and push the orchestrator image
aws ecr get-login-password --region eu-central-1 | docker login --username AWS --password-stdin <ECR_REGISTRY>
docker build -t <ECR_REPO_URL>:latest -f docker/Dockerfile .
docker push <ECR_REPO_URL>:latest

ArgoCD auto-deploys this Helm chart from helm/notebook2rest/ using the values in values-aws.yaml.

Access the service

kubectl port-forward svc/notebook2rest 8000:8000 -n notebook2rest
# Open http://localhost:8000/docs

Synchronization

Notebooks are in a separate repo: notebook2rest-notebooks.

When a .ipynb file is pushed there, a GitHub Actions workflow sends a repository_dispatch event to this repo, which triggers notebook-sync.yml. The sync pipeline:

1. Clones the notebooks repo
2. Parses only the changed notebooks
3. Builds a Docker image per code cell and pushes to ECR
4. Deploys each cell service to EKS via Helm
5. Generates Argo Workflow YAMLs into the gitops repo

Related repos

notebook2rest-infra | Terraform - VPC, EKS, ECR, IAM, ArgoCD | notebook2rest-gitops | ArgoCD application manifests | notebook2rest-notebooks | Sample Jupyter notebooks |