source/README.md

metadata

title: Ouroboros
emoji: 🧬
colorFrom: yellow
colorTo: red
sdk: docker
app_port: 7860
pinned: false
short_description: Dual learning, protein structures, and live generation

Ouroboros

Ouroboros Atlas

The Atlas adds /atlas and a lightweight homepage preview using the paper's frozen million-sequence ESM-2 / PCA / UMAP projection, its 34 Leiden community colors and its −45° display rotation. The interactive page displays 12,000 points; the homepage loads a separate 4,000-point subset. Both samples retain all eight featured proteins, with verified AlphaFold DB structures and small structure thumbnails. Sampling retains small communities and all paper cases; displayed proportions are not corpus estimates. Full ID lookup still covers 51,321,839 short-sequence records independently of the display sample. The coverage strip uses the full-corpus exact-match count, 151,479, against Swiss-Prot 2024_01.

The map supports community/coverage layers, drag and keyboard pan, cursor-centered zoom, touch pinch, and separated numbered markers with lines back to the actual coordinates. Case cards and marker buttons open the archived paper cases without a network dataset lookup; arbitrary record IDs continue to use the full-release API. Case links survive refresh and browser history. Structure colors switch between N-to-C spectrum and pLDDT confidence.

Set OUROBOROS_ATLAS_REVISION to the verified 40-character dataset commit SHA to enable full ID lookup. OUROBOROS_ATLAS_REPO defaults to REXWind/Ouroboros-Atlas. Unconfigured or incomplete releases return an explicit unavailable state, never a sample-only substitute. OUROBOROS_ATLAS_CACHE defaults to /tmp/ouroboros-atlas-cache; its cache is capped at 1 GiB with at most two simultaneous downloads. Atlas reads do not load the inference model.

API: GET /api/atlas/manifest, GET /api/atlas/proteins/{id}. Full UniRef50_... IDs and the corresponding suffixes are accepted, with whitespace/case normalization. Arbitrary cluster-member mapping and sequence-fragment search are outside this release. A 404 denotes a missing record; upstream/network errors produce distinct 429/503/504 responses. Atlas uses FIX large, while the live playground retains original large-v5.

The full corpus and intermediate processing files remain on OSS; only compact map/case assets are shipped in the Space. The release builder and its provenance checks live in the sibling Ouroboros_Atlas/scripts/publish_atlas.py. Regenerate the small website assets with python scripts/export_atlas.py in the research environment (NumPy and Pillow), not in the deployed Space. This reads verified local paper archives and does not download or refit the full dataset. Export checksums and source paths are in public/data/atlas-provenance.json. Both map assets are served locally with precompression; the old OUROBOROS_ATLAS_MAP_URL redirect is retired so stale deployment variables cannot load the old map.

An interactive research showcase for the original large-v5 protein–text model. Dual learning leads the page, followed by dataset annotation statistics, a wet-lab PETase case study and structure explorer, archived benchmark comparisons, and a two-direction inference playground.

Website presentation

The homepage presents the framework, annotation dataset, Atlas, PETase explorer and archived interactive benchmarks. Manuscript layouts inform the visual design; no manuscript figures, SVG/PDF originals or manuscript downloads are shipped. Featured proteins are independent structure illustrations without fixed figure numbers. All eight cases retain their verified coordinates and structures.

Benchmark scope and Atlas coverage

The benchmark display and public/data/evidence.json now contain only the Swiss-Prot time-cutoff dataset: 500 temporally held-out protein–text pairs. All 63 retained metric rows preserve their archived scores and sample counts; keyword recovery uses the 476 pairs with valid reference keywords. The 100-pair cohort is excluded from the public export and selector. Raw source split IDs hard1 / hard remain provenance only; the public split is swissprot_time_cutoff. Export scripts apply this scope on regeneration.

The Atlas opens its homepage map on Swiss-Prot overlap. Ouroboros descriptions reveals model-described sequences beyond the reference; Sequence communities retains the original colors and coordinates. The reveal respects page motion, reduced motion and offscreen stopping. Reference views show only matched or explicitly selected landmark markers, so featured examples do not imply reference coverage.

The coverage panel uses the full-corpus audit, separately from map sampling: 151,479 / 51,321,839 representatives exactly match Swiss-Prot 2024_01 (0.295%); 51,170,360 are beyond that exact reference. These counts do not establish absence of annotations elsewhere. Ouroboros descriptions are functional hypotheses. public/data/atlas-coverage.json records the source audit checksum. Regenerate with python scripts/export_atlas_coverage.py or the complete Atlas exporter.

Latest previews, before-edit backups and reports are in artifacts/refinements-20261110/. Run scripts/check_showcase_refinements.py with CHROMIUM_PATH and optional PREVIEW_URL for focused checks, and scripts/check_showcase_motion.py for the whole-site regression. Record the updated animations using scripts/record_showcase_refinements.py.

Interactive presentation and motion

The showcase uses locally bundled Space Grotesk headings and DM Sans body text, with IBM Plex Mono technical labels. Blue consistently identifies functional language; orange/red identifies protein sequences, structures and PETase designs. The CellPack presentation source informed the typography, visual hierarchy and explanatory animation: docs/cellpack/.vitepress/theme/{style.css,components/HeroScene.vue,home/ScrollScene.vue} at CladeTeam/CellPack revision 4ef3d7867d4ee1fd09112bee09e9480682b10a58. Ouroboros components are implemented locally in React, SVG and Canvas.

• The identity is a continuous blue-to-red infinity loop, shared by the header, hero, Atlas, footer and favicon. SVG mark/avatar assets, a transparent PNG mark and a 512 px PNG avatar are in public/brand/. Regenerate the SVGs and shared React geometry with python scripts/generate_brand.py.
• The architecture follows the actual large-v5 configuration: 24 T5-style blocks per encoder/decoder and hidden size 1,024. Self-attention, decoder cross-attention and feed-forward layers are shown separately, with independent linear projections between modalities. Decoder outputs use real archived residue/word excerpts; word chips are not claimed to be T5 subword boundaries. The first 72 generated residues use compact 26×28 tiles in three numbered rows; complete reference inputs and predictions are available in the expandable archive below the scene.
• The hero lets visitors select joint learning, design and description. Directional packets and sequence highlights are illustrative, not inference telemetry.
• Dual Learning is a six-beat sticky scroll story: reference description → text encoder → hidden-state projection → residue output; then an independent reference protein → protein encoder/projection → text output; finally a wider view of both tasks and within-modality self-attention sharing. All positions, highlights, emissions and copy share a deterministic progress value. There is no timer-driven tour. Scroll back, select a chapter, or use the keyboard slider.
• src/dualStory.ts owns beat boundaries and easing; src/useScrollStory.ts measures scroll and schedules frames only while visible and settling; src/DualScene.tsx renders the SVG from progress; src/DualLearning.tsx owns accessible copy, controls, reading layout and archived records. This borrows CellPack's scene/progress organization, not its Vue runtime or Canvas renderer.
• The joint overview sequentially highlights text and protein self-attention sharing. The Text weights / Protein weights / Both controls inspect each pair on the same reversible timeline. Cross-attention and projection weights are not presented as shared.
• At widths ≤1,100 px, short viewports (≤640 px high), or reduced motion, the scene becomes six ordinary reading steps with separately composed diagrams. Desktop readers can select “Read all steps” at any time. Pause freezes scroll animation; explicit chapter/range controls still permit manual inspection.
• A lazy-loaded DE2 backbone illustration interpolates sequence order into the actual ESMFold-v1 Cα coordinates. Play/pause, a keyboard-accessible slider and pointer rotation expose the transition. This is not a folding simulation or a new structural prediction. The full molecular explorer remains below it.
• Motion on/off controls ambient animation, the scroll story, molecular rotation and the backbone transition. It persists for the browser session and remains available on /atlas. System reduced-motion preferences stop automatic movement and expose all six explanatory steps. Offscreen animations and hidden-tab playback stop; full source values and diagrams remain readable.
• Responsive navigation includes active-section tracking, reading progress, Escape dismissal and outside-click dismissal. Charts animate on first entry.

Run CHROMIUM_PATH=/path/to/chrome-headless-shell .venv/bin/python scripts/check_showcase_motion.py against the production preview (PREVIEW_URL optional). This checks scroll starts/midpoints/ends, exact rewind, pause, keyboard controls, reduced motion, archived data, the backbone, existing research controls and desktop/mobile layouts without submitting inference jobs. Current results and screenshots from that initial refactor are in artifacts/scroll-story-20261110/; the current revision is in artifacts/refinements-20261110/. Record the progression and rewind using scripts/record_scroll_story.py with the same environment variables (and PLAYWRIGHT_BROWSERS_PATH if ffmpeg is installed outside the default cache). scripts/check_scroll_story_layout.py adds short/large viewport containment and visibility-state checks. The previous presentation artifacts under artifacts/motion-refresh-20261110/ are historical and do not show the current Dual Learning experience.

PETase wet-lab designs

The explorer presents DE1–DE9 and the natural IsPETase reference. After computational screening of model-generated candidates, 12 selected designs were submitted for wet-lab testing: nine showed PETase activity and three did not. The nine active designs have individual sequence and structure views.

DE2 is featured at 1,514.1531 μM TPA + MHET, versus 1,074.8149 μM for IsPETase: 1.41× the total product concentration (40.9% higher). The other eight active designs were below this reference. This is the reported product concentration comparison; kinetics, replicate variability and statistical significance are not established by the supplied data.

All nine FASTAs exactly match original LoRA generation records. Full-length ESMFold-v1 predictions were generated by a single-GPU idle job in ailab-dnacoding; every PDB is checked against its FASTA and checksum. The UI uses CA-residue mean pLDDT, which measures prediction confidence, not activity. The IsPETase reference retains the same verified ESMFold method.

Rebuild data with python scripts/export_wetlab.py in the research workspace. It reads the supplied table, archived FASTAs, generation audit and completed fold manifest from Ouroboros_Showcase_Research/wetlab_20261110. Public downloads are data/petase-assay.csv and data/wetlab.json. Table precision is preserved; the 0.0001 μM DE7 sum difference is recorded as supplied rounding. No new assay date is inferred from the date on which the update was received.

Run locally

Requires Node 22.12+ and Python 3.10. The frontend and API share port 7860 in production.

npm ci
npm run build
python3.10 -m venv .venv
.venv/bin/pip install --upgrade pip
.venv/bin/pip install torch==2.7.1+cpu --extra-index-url https://download.pytorch.org/whl/cpu
.venv/bin/pip install -r requirements.txt
.venv/bin/uvicorn server:app --host 0.0.0.0 --port 7860 --workers 1

The model loads on the first submitted job. CPU generation can take several minutes; jobs run serially with a bounded queue. Keep one worker to avoid duplicate model copies. For frontend development, run npm run dev with the API running on port 7860.

The playground defaults to the original dual_t5 sampling settings: temperature 1.0, top-k 40, top-p 0.9, four beams, one returned sequence, and maximum length 512. Greedy decoding remains available in advanced settings. The archived Large hard1 sampling file does not record its exact seed or full decoding provenance, so a live result can differ from a saved example.

Set OUROBOROS_INFERENCE=disabled for a fast exhibition-only preview. The recorded Core Idea demonstration, structures, downloads, and charts remain available; the playground explicitly labels live inference as unavailable and never substitutes saved outputs.

Environment variable	Purpose
CHECKPOINT_PATH	Optional local dual_model.pt; otherwise download from the model repository
OUROBOROS_MODEL_REPO	Defaults to REXWind/ouroboros-weights
PROTEIN_TOKENIZER_PATH	Optional local ProtT5 tokenizer directory
TEXT_TOKENIZER_PATH	Optional local T5-base tokenizer directory
OUROBOROS_DEVICE	Defaults to cpu; use cuda only with a compatible GPU PyTorch installation
OUROBOROS_CPU_THREADS	Defaults to 4
OUROBOROS_INFERENCE	Set to disabled to disable live jobs
HF_HOME	Hugging Face download cache

Hugging Face Spaces

This folder is a self-contained Docker Space. Use this README metadata and Dockerfile in the Space repository. The existing Gradio Space must switch to sdk: docker. Its model weights stay in the model repository; do not upload local checkpoints, virtual environments, browser installations, or node_modules.

docker build -t ouroboros-showcase .
docker run --rm -p 7860:7860 ouroboros-showcase

The Dockerfile builds the frontend, bundles fonts and 3Dmol locally, and runs the API as an unprivileged user. It downloads the original model and tokenizers at first inference unless local paths are supplied. Team deployment target: CladeTeam/ouroboros. This version uses the Docker SDK. The original personal Space and its Gradio history remain at REXWind/ouroboros; the team Space loads the same public model weights and Atlas dataset.

Static team hosting

When the organization cannot host a free Docker Space, the same presentation can run as a Hugging Face Static Space with the existing personal Docker Space as its inference and Atlas lookup service. Static HTML declares <meta name="ouroboros-api-base" content="https://rexwind-ouroboros.hf.space"/>. Only /api/ requests use that base; research assets remain on the team Space. Without the meta tag, Docker hosting keeps same-origin API requests.

The static package includes /atlas.html for direct links and refreshes. Static hosting does not provide compute: live inference and full-corpus queries depend on the existing backend being available. The backend already permits the cross-origin health, Atlas and job requests; model weights are not copied.

Structured prompt builder

Text-to-protein exposes similarity and function directly. All 29 original annotation keys can be added individually. Six named presets and a random picker reuse annotated entries from the original demo’s 100sample.json (A5IKJ0, B9LSR7, Q1CJV7, A9MXA7, Q9REQ9, Q3B3L6). Presets populate the editable fields and prompt; after manual field edits, use Build prompt to apply them. Assembly preserves the original field order and concatenation. Presets and the example selector populate inputs only. Every playground output comes from a newly submitted inference job.

Dataset annotation explorer

The supplied key-count CSV contains 29 types and 2,078,270 record–key pairs. A compact horizontal rail exposes all 29 keys with touch scrolling, arrow controls and search. Selecting a key shows its coverage and a sourced annotation example. Counts and percentages are preserved exactly. Records may have multiple keys, so coverage percentages do not sum to 100%. The page describes annotation breadth; it does not claim sequence/species diversity or superiority to other datasets. All 29 record counts were verified against the supplied 545,334-record type_with_data_clean.json; training-split membership remains unconfirmed. All displayed cases are verbatim annotations from that file, with record indices and source checksums in the export. The full dataset remains in OSS and is not uploaded into the Space. scripts/export_annotation_examples.py extracts the 29 small case records before regenerating statistics. scripts/export_annotation_stats.py regenerates JSON and provenance from the bundled original CSV.

Evidence and scientific scope

• The Core Idea uses an archived reference pair to illustrate input/target roles, with a scroll narrative across two inference directions and joint learning. The displayed pair is held out; it is not presented as training data or a round trip.
• The architecture describes joint teacher-forced training in both directions, with shared self-attention within each modality. It does not claim a cycle-reconstruction objective.
• The featured wet-lab design is de2, 279 aa. Its submitted FASTA exactly matches petase_lora_2891, prediction index 2890 (zero-based) in the lora_petase_3epoch generation archive. Its original generation prompt is shown. Earlier confidence-ranked cases are preserved in public/data/petase-archive.json.
• The 2026-09-27 workbook reports TPA and MHET concentrations for four designs and three WT references. The visible comparison and structure tabs focus on de2 and IsPETase; the complete original source data remain downloadable. de2 has the highest sum among the four reported designs (1514.1531 μM); LCC and BhrPETase have higher reported values. Missing results for the other eight submitted designs are not zero. Assay conditions and replication were not supplied, so no normalized activity or significance claim is made.
• de2 and the supplied IsPETase, LCC, and BhrPETase FASTAs were folded with ESMFold-v1 in job ouroboros-wetlab-de2-1009b. Every structure was checked against its input sequence. The active petase.json contains de2 and IsPETase; all four predicted structures remain archived in petase-wetlab-structures.json. The viewer shows computational predictions; mean pLDDT is calculated from residue CA B factors, and is not enzyme activity.
• scripts/export_wetlab.py exports the cases from the source workbook, sequence audit, and completed folding manifest. It requires xlrd==2.0.2 in the research environment; production serving does not need it. CSV and JSON downloads preserve the exact reported values.
• Ten saved playground examples come from hard1 rows 385, 313, 232, 490, 476, 479, 497, 496, 259, and 272. Their archived text BLEU-4 scores are at least 0.57, and sequence recovery is at least 0.79. Their generated sequences were checked for long single-residue repeats. Labels use hard_####_function, with the function taken from the reference annotation. They preserve the two independent evaluation directions. A live generated sequence can be sent to the annotation direction as an optional inference experiment.
• The large-v5 inference implementation preserves historical checkpoint behavior. It does not silently substitute the later FIX architecture.

public/data/provenance.json records the source paths, checksums, and interpretation limits. scripts/export_assets.py regenerates archived examples and benchmark assets without overwriting the active wet-lab case. Run scripts/export_wetlab.py for the current PETase assets. The deployed Space needs only the already exported files.

Validation

npm run build
.venv/bin/pip install pytest httpx playwright
.venv/bin/python -m pytest tests -q
PLAYWRIGHT_BROWSERS_PATH="$PWD/.browsers" .venv/bin/playwright install chromium
PLAYWRIGHT_BROWSERS_PATH="$PWD/.browsers" .venv/bin/python scripts/browser_check.py

The browser check expects the production app on http://127.0.0.1:7860; override with PREVIEW_URL. Some shared filesystems cannot memory-map Chromium's ICU data; set CHROMIUM_PATH to a browser executable copied to local storage if needed. Browser captures are saved in artifacts/ and excluded from deployment.

Result animation

The Core Idea replays the archived large-v5 HSP20 case hard1-0151 through a scroll-controlled architecture illustration. Each direction starts from its own reference input, not a round trip. The final overview explains teacher-forced training; the archived inference outputs are not a training trace. Complete source strings remain available beneath the scene. The playground still submits real inference requests and displays completed results directly, without saved outputs standing in for a live result. The CPU Basic deployment uses two CPU threads and a bounded serial queue; first use downloads and loads the checkpoint.

Atlas refresh validation

Build and run the API with a verified Atlas revision, then run:

.venv/bin/python -m pytest tests -q
CHROMIUM_PATH=/path/to/chrome-headless-shell .venv/bin/python scripts/check_atlas_refresh.py

The browser check exercises real full-corpus lookup outside the display sample, all eight structures, map controls, links/history and responsive layouts. PREVIEW_URL defaults to http://127.0.0.1:7860. Screenshots and the validation report are saved under artifacts/atlas-refresh-20261110/.