# 🧬 Junction Foundry: Master Documentation

Junction Foundry is a high-performance AI orchestration platform architected for the **Biotech** and **Agriculture** industries. Leveraging the **Llama Stack Distribution** on AWS, it provides a unified interface for agentic reasoning, document intelligence, and secure memory banks.

## 🌟 Core Value Proposition

Junction Foundry solves the "Sovereignty vs. Scalability" paradox by providing a single codebase that can be deployed as a hardened, air-gapped fortress for Biotech R&D or as a hyper-scale SaaS platform for global Agriculture operations.

### 🏛️ Deployment Tiers

| Tier | Target Industry | AWS Infrastructure | Security Posture |
| :--- | :--- | :--- | :--- |
| **Sovereign** | Biotech / Pharma | **AWS Outposts + Nitro** | **Air-Gapped:** 100% on-premise data residency |
| **Private** | Enterprise Agri | **VPC / EKS** | **Isolated:** Dedicated private cluster with no public ingress |
| **Agile** | Field-Ops / SaaS | **SaaS / FaaS (Amazon Bedrock)** | **Hyper-Scale:** Global reach with pay-per-token efficiency |

### 🏗️ Technical Foundation

- **API Standard:** [Llama Stack](https://github.com/meta-llama/llama-stack) — Acts as the "Kubernetes for AI," abstracting the transition from local development to production clusters.
- **Document Intelligence:** [Docling](https://github.com/DS4SD/docling)
- **Inference Engines:** Support for **Ollama** (Local/Foundry), **vLLM** (Private/EKS), and **Amazon Bedrock** (Agile/SaaS).

---

## 🛠️ Development & Lab Setup (Internal Foundry)

This section defines the **Internal Lab** environment. We use this local "Foundry" on Apple Silicon (M3 Max) to prototype and validate the Llama Stack before shipping to customer AWS environments.

### 🏗️ 1. Environment Initialization (M3 Max)

We use the `krunkit` driver for native Metal GPU passthrough and `calico` to simulate the network isolation required for Biotech audits.

```bash
# Optimized for M3 Max with 32GB+ RAM
minikube start \
  --driver=krunkit \
  --cpus=max \
  --memory=32768 \
  --disk-size=100g \
  --network-plugin=cni \
  --cni=calico 

# Install the Llama Stack Operator
kubectl apply -f https://raw.githubusercontent.com/llamastack/llama-stack-k8s-operator/main/release/operator.yaml

```

### 💾 2. Sovereign Model Ingestion (Resilient Pipeline)

We use MinIO as a local object storage solution within the Minikube cluster to host our model files.

#### Step 1: Install MinIO in Minikube

```bash
helm repo add minio https://charts.min.io/
helm repo update
helm pull minio/minio --untar
```

#### Step 2: Download Models Locally

Download models using the `hf` CLI tool:

* **Coder:** Qwen 2.5 32B (Q4_K_M)
* **Reasoner:** DeepSeek R1 32B (Q4_K_M)

#### Step 3: Mount & Upload

1. **Mount:** `minikube mount ~/.hf-cache:/hf-cache`
2. **Upload:** Use the `mc` tool to move files into the `minio/models` bucket.

---

## 🛡️ Security Enhancements

### Persistent Volume Claims (PVCs)

Ensure data persistence by creating PVCs for MinIO:

```bash
kubectl apply -f - <<EOF
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: minio-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 50Gi
EOF
```

### Access Policies

Secure your MinIO deployment by setting up bucket policies:

```bash
# Example policy to restrict access to the models bucket
mc policy set private minio/models
```

This ensures that only authenticated users with proper permissions can access the models.

---

## 🔬 Biotech & Sovereignty Specification

This "Biotech Spec" focuses on the hardened requirements for **GxP (Good Practice)** compliance and clinical research environments.

### 🧪 Infrastructure & Local Simulation Matrix

| Tier Name | Target Market | AWS Infrastructure | **Local Simulation (Macbook)** | Llama Stack Provider |
| --- | --- | --- | --- | --- |
| **Sovereign** | Biotech R&D | **AWS Outposts** | **Minikube + Calico** (Egress Blocked) | `remote::ollama` (Local) |
| **Private** | Ent. Agriculture | **VPC / EKS** | **Minikube** (Internal DNS only) | `remote::vllm` (Local) |
| **Agile** | Field / SaaS | **SaaS / FaaS** | **Docker Compose** (Internet Open) | `remote::together` (API) |

### 🛠️ Simulating the "Sovereign Tier"

In this mode, we use **Calico** to physically block the Llama Stack from reaching the internet. This ensures your **Docling** parsers and weights are 100% self-contained.

* **Setup:** `minikube start --network-plugin=cni --cni=calico`
* **Enforce Isolation:** Apply an egress lockdown policy to deny all traffic except internal requirements.
* **Success Criteria:** The agent analyzes sensitive research files while any `curl` to an external API fails.

---

## 🌾 Agile Tier: Agriculture & Field-Ops Specification

The Agile Tier is designed for rapid scaling across distributed geographic locations. It focuses on **utility-scale AI** and **global availability**.

### ☁️ Infrastructure: AWS Cloud-Native

* **Orchestration:** **Amazon EKS** using Fargate for serverless scaling.
* **Inference:** **Amazon Bedrock**. We utilize Llama 3 and Claude models via managed APIs to avoid fixed hardware costs.
* **Scaling:** Automated horizontal scaling based on request volume (SQS/Lambda).

### 🛰️ Data Flow & Connectivity

* **Standard:** Encrypted Transit (TLS 1.3) from field devices to AWS Regions.
* **Edge Processing:** Use of **Llama Stack "Shields"** to redact sensitive PII/Location data at the edge.

---

## 🚀 AWS Provisioning & Readiness Checklist

Essential AWS configurations required to move from the local Foundry to production infrastructure.

### 🏁 Step 1: Service Quota Requests (Region-Specific)

Request these in the **Service Quotas Console** under "Amazon EC2":

| Quota Name | Quota Code | Target Value | Reason |
| --- | --- | --- | --- |
| **Running On-Demand G and VT instances** | `L-38197617` | **32 vCPUs** | G5 instances for 32B models. |
| **Running On-Demand P instances** | `L-411A8248` | **32 vCPUs** | P4/P5 for high-perf training. |
| **Standard (A, C, D, H, I, M, R, T, Z)** | `L-1216C47A` | **64 vCPUs** | EKS Control Plane/Support nodes. |

### 🛠️ Step 2: Essential AWS Services

1. **Amazon ECR:** Create a private repository named `junction-foundry`.
2. **Amazon EKS:** Deploy a cluster with at least 2 nodes.
3. **Amazon Bedrock:** Manually "Request Access" to Meta (Llama 3) and Anthropic (Claude) models.
4. **AWS PrivateLink:** Enable interface endpoints for `bedrock-runtime` and `ecr.api`.

### 📝 Step 3: Verification

Run this CLI command to verify GPU quotas:

```bash
aws service-quotas get-service-quota \
  --service-code ec2 \
  --quota-code L-38197617 \
  --query "Quota.Value"

```