📄 Paper API

Build and download scientific papers from evolution results via the VEOX API.

Pro Feature

This is a Pro feature requiring an active VEOX Pro license.

Prerequisites

VEOX Server: Start the local VEOX server (requires Docker):

docker run -d \
  --name veox-enclave-server \
  -p 8090:8090 \
  714044927654.dkr.ecr.us-east-2.amazonaws.com/doug/single_enclave/veox-enclave-server:latest

See the Quick Start for detailed server setup, health checks, and Docker Compose instructions.

Python SDK: Install the veox package via PyPI:
```
pip install veox
```

PDF Creation Inside the Enclave via API

All PDF creation runs entirely inside the VEOX enclave. Your client only sends HTTP requests; no LaTeX or PDF tooling is required on your machine.

┌─────────────────────────────────────────────────────────────────────────┐
│  Your client (Python / curl)                                             │
│    POST /api/v1/evolution/jobs/{id}/build_paper  →  Trigger build        │
│    GET  /api/v1/evolution/jobs/{id}/status        →  Poll progress         │
│    GET  /api/v1/evolution/jobs/{id}/paper_pdf   →  Download PDF          │
│    GET  /api/v1/evolution/jobs/{id}/paper_log   →  Download build log   │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│  VEOX Enclave (Docker container :8090)                                    │
│  • PaperKit runs inside the container (LaTeX, figures, compilation)       │
│  • PDF is written to container filesystem, then served via FileResponse   │
│  • No data or code leaves the enclave until you request the PDF           │
└─────────────────────────────────────────────────────────────────────────┘

Step	Where it runs	Description
1. Evolution	Enclave	Job produces artifacts (champions, tables, figures).
2. Build request	Client → Enclave	`POST .../build_paper` starts a background build in the enclave.
3. LaTeX + PDF	Enclave	PaperKit 18-step pipeline runs inside the container; PDF is created in `/tmp/paper_exports/{job_id}/paper.pdf`.
4. Download	Enclave → Client	`GET .../paper_pdf` streams the generated PDF to your machine.

What It Does

The Paper API integrates PaperKit — the VEOX autonomous scientific publishing system. After an evolution run produces results, PaperKit builds a complete research paper:

Evolution Results → LaTeX Generation → Figure Rendering → PDF Compilation

The 18-step build pipeline produces publication-ready PDFs with: - Abstract, introduction, and methodology sections - Results tables comparing evolved pipelines to baselines - Convergence plots and fitness visualizations - Full bibliography and appendices

Quick Start (SDK)

from veox import VeoxEvolver

evolver = VeoxEvolver("binary")
evolver.fit(max_generations=3, population_size=15, num_islands=1, max_poll_time=120)
evolver.build_paper(test_mode=True)         # 💎 PRO FEATURE: build_paper()
evolver.download_paper("my_paper.pdf")      # 💎 PRO FEATURE: download_paper()

Full Example (SDK)

from veox import VeoxEvolver
from sklearn.datasets import make_classification
import pandas as pd

# 1. Generate dataset
X, y = make_classification(n_samples=500, n_features=20, n_informative=10, random_state=42)
df = pd.DataFrame(X, columns=[f"f{i}" for i in range(20)])
df["target"] = y

# 2. Connect & verify
evolver = VeoxEvolver("binary", api_url="http://127.0.0.1:8090")
evolver.health_check()

# 3. Run evolution
evolver.fit(
    data=df,
    target_column="target",
    max_generations=5,
    population_size=20,
    num_islands=2,
    timeout_per_eval=30,
    max_poll_time=300,
)

print(f"Best AUC:    {evolver.best_fitness_:.4f}")
print(f"Pipeline:    {evolver.best_pipeline_}")

# 4. Build the paper
status = evolver.build_paper(test_mode=True, timeout=300)      # 💎 PRO FEATURE: build_paper()
print(f"Paper build: {status}")

# 5. Download artifacts
if status == "completed":
    pdf_path = evolver.download_paper("evolution_paper.pdf")   # 💎 PRO FEATURE: download_paper()
    log_path = evolver.download_log("build.log")
    print(f"PDF: {pdf_path}")
    print(f"Log: {log_path}")

Full Example (Raw HTTP)

For users who want lower-level control without the SDK:

import requests
import time

BASE = "http://127.0.0.1:8090"
API  = f"{BASE}/api/v1/evolution"

# 1. Health check
r = requests.get(f"{BASE}/health", timeout=5)
print(f"Health: {r.json()}")

# 2. Trigger a test paper build
r = requests.post(f"{API}/jobs/test_run/build_paper", params={"test": "true"}, timeout=30)
assert r.status_code == 202, f"Failed: {r.status_code}"
job_id = r.json().get("job_id", "test_run")
print(f"Build started: {job_id}")

# 3. Poll progress
t0 = time.time()
while time.time() - t0 < 300:
    time.sleep(3)
    sr = requests.get(f"{API}/jobs/{job_id}/status", timeout=10)
    data = sr.json()
    paper_status = data.get("paper_status", "pending")
    progress = data.get("paper_progress", 0.0)
    step = data.get("paper_step", "")
    print(f"  [{int(progress*100):3d}%] {step}")

    if paper_status == "completed":
        print("✅ Build completed!")
        break
    elif paper_status == "failed":
        print(f"❌ Build failed: {data.get('paper_error', 'unknown')}")
        break

# 4. Download PDF
r = requests.get(f"{API}/jobs/{job_id}/paper_pdf", timeout=30)
if r.status_code == 200:
    with open("paper.pdf", "wb") as f:
        f.write(r.content)
    print(f"PDF saved ({len(r.content)/1024:.0f} KB)")

# 5. Download build log
r = requests.get(f"{API}/jobs/{job_id}/paper_log", timeout=10)
if r.status_code == 200:
    with open("build.log", "w") as f:
        f.write(r.text)
    print(f"Log saved ({r.text.count(chr(10))} lines)")

SDK Methods Reference

Method	Description
`build_paper(test_mode=False)`	Trigger paper build, poll until done. Returns `"completed"` or `"failed"`
`download_paper(path)`	Download generated PDF. Returns absolute path
`download_log(path)`	Download build log. Returns absolute path

API Endpoints Reference

Endpoint	Method	Description
`/api/v1/evolution/jobs/{id}/build_paper`	POST	Trigger paper build (`?test=true` for test mode)
`/api/v1/evolution/jobs/{id}/status`	GET	Poll progress (`paper_status`, `paper_progress`, `paper_step`)
`/api/v1/evolution/jobs/{id}/paper_pdf`	GET	Download generated PDF
`/api/v1/evolution/jobs/{id}/paper_log`	GET	Download build log

Build Progress Fields

When polling /status, the paper build fields are:

Field	Type	Description
`paper_status`	`str`	`"pending"`, `"building"`, `"completed"`, `"failed"`
`paper_progress`	`float`	0.0 to 1.0 (percentage complete)
`paper_step`	`str`	Current step description (e.g., "STEP 14/18: Compiling LaTeX")
`paper_error`	`str`	Error message if status is `"failed"`

💎 VEOX Pro Activation

To unlock VIP Evaluators and Pro Algorithms (like PaperKit and Generative routines), you must authenticate your local node with a VEOX License Token.

from veox import VeoxEvolver

evolver = VeoxEvolver("binary", api_url="http://127.0.0.1:8090")

# 1. Fetch your unique Hardware Fingerprint
fingerprint = evolver.get_system_fingerprint()
print(f"My VEOX Node Fingerprint: {fingerprint}")
# Example Output: My VEOX Node Fingerprint: 476ad03474b31e3c84d07df9088d93f0

# 2. Provide this fingerprint to your VEOX Admin to receive a JWT Token
jwt_token = "eyJ0b2tlbiI6ICJVRExK...EXPIRES"  # Replace with your token

# 3. Activate the Enclave
if evolver.activate_license(jwt_token):
    print("VIP Features Unlocked!")
    # evolver.fit(...) will now utilize full Pro capabilities

Tips

Test mode: Use test_mode=True to build with baked-in mock artifacts — no evolution run needed.
Timeout: Paper builds typically take 30–120 seconds. Set timeout=300 for safety.
Build log: The log contains all 18 PaperKit steps — check it if the build fails.
PDF size: A healthy paper PDF is typically 200–800 KB. Under 10 KB indicates a problem.