Permea Core

Open execution layer for sequence-first biological delivery engineering.

Benchmark-first infrastructure for reproducible, computational delivery evidence.

Overview

Permea Core is an open technical foundation for making biological delivery more benchmarkable, reproducible, and evidence-backed. It organizes delivery-related datasets, benchmark tasks, run manifests, output cards, and contribution workflows so researchers can compare sequence-first delivery hypotheses before wet-lab validation.

Permea is not another single predictor. Permea Core is the public execution layer for benchmark-first delivery engineering: shared specifications, reusable artifacts, and reproducible workflows for computational evidence before experimental follow-up.

Quickstart

Run the first-user demo from the repository root:

python3 scripts/permea_demo.py

The demo discovers public example packages, runs local validation, links evidence and claim-boundary surfaces, and prints next recommended commands. See Quickstart, Public review packet, Evidence index, Benchmark registry, Benchmark execution model, Dataset registry, Research package registry, and Claim registry.

Public Review Packet

Run the guided public review packet:

python3 scripts/permea_review.py

The reviewer path is Quickstart -> Review Packet -> Research -> Datasets -> Benchmarks -> Evidence -> Claims -> Lineage -> validation commands.

For navigation across current architecture and implementation reports, use Architecture Index and Reports Index.

Review public artifact consistency with:

python3 scripts/permea_artifacts.py

Generate reviewer-facing evidence packets for public artifact systems with:

python3 scripts/permea_review_packet.py

Generated packets currently cover evidence surface navigation, reproducibility, evaluation, public review packet guidance, and artifact consistency. They link reviewed scripts, modules, docs, tests, reports, validation commands, claim boundaries, and limitations.

Evidence And Claims

After the quickstart, review the evidence path:

python3 scripts/permea_evidence.py

Start with Evidence map, then review Claim-to-evidence matrix, Evidence maturity model, Evidence timeline, Public review packet, Benchmark registry, Dataset registry, Research package registry, Claim registry, and Validation.

Benchmarks

Review the benchmark framework:

python3 scripts/permea_benchmarks.py

The benchmark path is Quickstart -> Evidence -> Benchmarks -> Claims -> validation commands.

Benchmark Execution

Review the benchmark execution framework:

python3 scripts/permea_benchmark_run.py

The benchmark execution path is Quickstart -> Review Packet -> Evidence -> Benchmarks -> Benchmark Execution -> Datasets -> Research -> Signal Integration -> Claims -> validation commands.

Reviewer path: README -> QUICKSTART -> REVIEW PACKET -> RESEARCH -> DATASETS -> BENCHMARKS -> EVIDENCE -> CLAIMS -> LINEAGE -> VALIDATION.

Benchmark execution path token: README -> QUICKSTART -> REVIEW PACKET -> EVIDENCE -> BENCHMARKS -> BENCHMARK EXECUTION -> DATASETS -> RESEARCH -> CLAIMS -> VALIDATION.

Datasets

Review the dataset framework:

python3 scripts/permea_datasets.py

The public review path is Quickstart -> Evidence -> Benchmarks -> Benchmark Execution -> Datasets -> Signal Integration -> Claims -> validation commands.

Research Packages

Review the research package framework:

python3 scripts/permea_research.py

The package review path is Quickstart -> Evidence -> Benchmarks -> Benchmark Execution -> Datasets -> Research -> Signal Integration -> Claims -> validation commands.

Signal Integration

Review the external evidence package integration layer:

python3 scripts/permea_signal.py

The signal integration path is Quickstart -> Review Packet -> Evidence -> Benchmarks -> Datasets -> Research -> Signal Integration -> Claims -> Lineage -> validation commands.

Evidence Lineage

Review the lineage and provenance framework:

python3 scripts/permea_lineage.py

The lineage path is Quickstart -> Review Packet -> Research -> Datasets -> Benchmarks -> Evidence -> Claims -> Lineage -> validation commands.

Lineage path token: README -> QUICKSTART -> REVIEW PACKET -> RESEARCH -> DATASETS -> BENCHMARKS -> EVIDENCE -> CLAIMS -> LINEAGE -> VALIDATION.

Signal integration path token: README -> QUICKSTART -> REVIEW PACKET -> EVIDENCE -> BENCHMARKS -> DATASETS -> RESEARCH -> SIGNAL INTEGRATION -> CLAIMS -> VALIDATION.

Why This Exists

Delivery is one of the bottlenecks for next-generation therapeutics. Peptides, RNA systems, mRNA designs, protein therapeutics, gene-editing payloads, and targeted biologics all depend on reaching the right biological context, but delivery evidence is still fragmented across datasets, papers, predictors, assays, and internal pipelines.

That fragmentation makes results hard to compare:

• dataset sources and label definitions are often unclear
• benchmark tasks, split policies, and metrics differ across projects
• assays and biological contexts are not always comparable
• candidate rankings can be difficult to audit
• dry-lab evidence is rarely packaged for reuse before experimental follow-up

Permea Core exists to create public technical defaults for this problem: dataset cards, benchmark cards, evidence cards, run manifests, output formats, and contribution workflows that make delivery-related computational evidence easier to inspect and reproduce.

What Permea Core Provides

Permea Core is early-stage public infrastructure. Some components are present as specifications and documentation, while others are roadmap surfaces that will grow as benchmark contracts stabilize.

The intended execution stack includes:

• Benchmark Registry: task definitions, dataset references, label schemas, metrics, baseline requirements, output artifacts, versions, and claim boundaries.
• Dataset Assembly: loading, validation, schema normalization, feature-extraction inputs, label checks, and source attribution.
• Baseline Runner: reproducible baseline configurations for transparent benchmark execution.
• Evaluation Engine: aggregate metrics, ranking behavior, sensitivity summaries, and limitation notes.
• Provenance Tracking: run identifiers, benchmark versions, dataset versions, code versions, configuration hashes, feature sets, and artifact lists.
• Output Formatter: standard benchmark packages for review, reproduction, and publication-safe summaries.
• Dataset Cards: public records for dataset source, labels, readiness, limitations, and provenance.
• Benchmark Cards: scoped benchmark definitions with inputs, metrics, splits, baselines, and claim boundaries.
• Evidence Cards: structured literature or computational evidence with uncertainty and review status.
• Run Manifests: reproducibility records for how a result was produced.
• Contribution Workflows: review paths for dataset cards, benchmark tasks, evidence cards, feature descriptors, baselines, reproduction reports, and documentation improvements.

What Permea Core Is Not

Permea Core is not another single BBB predictor.

It does not claim that delivery is solved. It does not claim wet-lab validation. It does not make clinical or therapeutic effect claims. It does not claim universal delivery prediction. It does not claim state-of-the-art status.

Core Architecture

Permea Core is organized around an execution stack:

1. Benchmark Registry: task definitions, dataset references, label schemas, metrics, baseline requirements, output artifacts, versions, and claim boundaries.
2. Dataset Assembly: loading, validation, schema normalization, feature-extraction inputs, label checks, and source attribution.
3. Baseline Runner: reproducible baseline configurations for transparent benchmark execution.
4. Evaluation Engine: aggregate metrics, ranking behavior, sensitivity summaries, and limitation notes.
5. Provenance Tracking: run identifiers, benchmark versions, dataset versions, code versions, configuration hashes, feature sets, and artifact lists.
6. Output Formatter: standard benchmark packages for review, reproduction, and publication-safe summaries.
7. API / Tool Layer Foundation: stable contracts that future CLI, API, web, and model-assisted interfaces can call.
8. DryLab Surface: a future user-facing workflow for candidate prioritization before experimental follow-up.

Existing technical docs:

• Specification
• Architecture Design
• Benchmark Contract
• Result Artifact Schema
• Run Manifest Schema
• Run Manifest Walkthrough

Dry-Lab Workflow

A Permea dry-lab run should be explicit and reproducible:

1. Define the benchmark task.
2. Assemble the dataset.
3. Extract sequence features.
4. Run baselines or models.
5. Evaluate metrics.
6. Rank candidates where the task supports ranking.
7. Generate evidence cards.
8. Export a reviewable package.

This workflow supports candidate prioritization before experimental work. It does not establish biological transport, mechanism, safety, or therapeutic performance.

Standard Output Artifacts

Permea benchmark runs should produce structured outputs such as:

• metrics.json
• ranking.csv
• manifest.yaml
• benchmark_card.md
• evidence_cards.json
• figures or summary reports where applicable

These artifacts should separate aggregate public summaries from review-required row-level artifacts, candidate-specific reports, and provenance records.

Current Benchmark Roadmap

Permea starts with sequence-first delivery benchmarks and expands carefully across task families. Not every roadmap item is complete yet.

Current and planned directions:

• BBB peptide benchmark
• CPP / membrane penetration benchmark
• localization / targeting proxy tasks
• RNA and delivery-adjacent benchmark surfaces
• literature evidence graph for structured claims, sources, and evidence cards

Each task should remain bounded by its data source, label policy, split policy, metric set, limitations, and release posture.

Current Scope

Permea Core is an early-stage public foundation. Current work focuses on delivery-related sequence features, benchmark surfaces, run specifications, and candidate prioritization before wet-lab.

The first public computational evidence package is permea-signal-ml. Permea Core provides the benchmark/specification/execution-layer foundation that future evidence packages can reuse.

Wet-lab validation is a future or external validation path, not a current claim of this repository.

Relationship to permea-signal-ml

• permea-core: benchmark, specification, and execution-layer foundation.
• permea-signal-ml: first computational evidence package for a reproducible benchmark-oriented demonstration.

permea-signal-ml shows how bounded sequence-derived delivery-related signal can be packaged for reproduction and review. permea-core defines the reusable infrastructure that should support many future benchmark tasks and contribution objects.

Related Repositories

• permea-core: open execution layer, benchmark contracts, public movement entry point, and contribution specs.
• permea-signal-ml: first evidence package and BBB benchmark support repository.

permea-signal-ml is a first concrete evidence package. permea-core is the reusable infrastructure layer that should support many future benchmark tasks and contribution objects.

Documentation Map

Core project documents:

• Open This First
• Review Hub
• Architecture Index
• Artifact Consistency
• Reports Index
• Evidence Layer
• Evidence Map
• Claim-to-Evidence Matrix
• Evidence Maturity Model
• Evidence Timeline
• Benchmark Layer
• Benchmark Registry
• Benchmark Lifecycle
• Benchmark Card Template
• Benchmark Execution Model
• Benchmark Run Template
• Benchmark Governance
• Signal Integration
• Evidence Lineage
• Permea Signal ML Integration
• External Evidence Package Template
• External Evidence Package Governance
• Claim Registry
• External Examples
• Decision Records
• Manifesto
• Delivery Taxonomy
• Evidence Ladder
• Claim Boundary
• Roadmap
• ADR-0001: Open-Source-First
• ADR-0002: Benchmark-First
• ADR-001: Project Breadcrumb and Review Hub Standard

Scientific governance:

• Claim Registry
• Dataset Policy
• Public-Safe Artifact Policy
• Reproducibility Guide
• Paper Alignment Policy

Open-source operating docs:

• Project Documentation Operating Standard
• P-DOC-001 Project Operating System Adoption Report
• OSS Operating Docs Map
• OSS Operating PR Summary
• Release Review Process
• Public Release Checklist
• Release Ownership Matrix
• Versioning Policy
• Archive and Deprecation Policy
• Attribution Policy

Artifact specs:

• Public Artifact Specifications
• Dataset Card Spec
• Benchmark Task Spec
• Evidence Card Spec
• Run Manifest Spec

Benchmark registry and examples:

• Benchmark Registry
• Online Data Source Registry
• Acquisition and Fallback Plan
• Examples README
• Example Output Package

Validate the benchmark registry scaffold:

python3 scripts/validate_benchmark_registry.py

Validate the source registry scaffold:

python3 scripts/validate_source_registry.py

Validate all current local registry and artifact layers:

python3 scripts/validate_permea_artifacts.py

Reproduce all public artifact surfaces:

python3 scripts/permea_reproduce.py

Validate the public reproducibility bundle:

python3 scripts/permea_validate.py

Check public artifact examples against the current Permea artifact standards:

python3 scripts/permea_check.py

Run the first-user quickstart demo:

python3 scripts/permea_demo.py

Copyable external examples are available at External Examples.

Run the deterministic benchmark dry-run:

python3 scripts/run_permea_dry_run.py

Review the benchmark execution framework:

python3 scripts/permea_benchmark_run.py

Review the signal integration layer:

python3 scripts/permea_signal.py

Generate the public artifact index:

python3 scripts/generate_artifact_index.py

Validate run manifest examples:

python3 scripts/validate_run_manifests.py

Generate public-safe benchmark card examples from the registry scaffold:

python3 scripts/generate_benchmark_card.py

Generate all current deterministic artifact examples:

python3 scripts/generate_permea_artifacts.py

Generate the public demo packet:

python3 scripts/generate_demo_packet.py

Generate the public evidence matrix:

python3 scripts/generate_evidence_matrix.py

Generate the public evaluation packet:

python3 scripts/permea_evaluate.py

Inspect the public artifact specification registry:

python3 scripts/permea_specs.py

Inspect public artifact consistency:

python3 scripts/permea_artifacts.py

Current generated artifacts are indexed at Public Artifact Index.

Generated benchmark dry-run reports are available under Generated Benchmark Dry-Run Reports.

The generated public demo packet is available at Public Demo Packet.

The generated public evidence matrix is available at Public Evidence Matrix.

Quick local setup starts at Quickstart. The reproducibility contract is documented in Reproducibility. The generated reproducibility report is available at Public Reproducibility Report.

The public evaluation pattern is documented in Evaluation Bundle. The generated evaluation packet is available at Public Evaluation Packet.

Generate run manifest examples:

python3 scripts/generate_run_manifests.py

Contributor and community docs:

• Contribution Objects
• Community Roadmap
• Contributor Levels
• Authorship Policy
• Dry-Lab Contribution Policy
• Wet-Lab Collaboration Policy
• Community Governance
• Maintainer Guide
• Reviewer Workflow
• Reviewer Credit Policy

Planned public docs:

• Permea Manifesto
• Scientific Thesis
• Delivery Dataset Commons
• Benchmark Execution Layer
• Research Intelligence Layer
• Frontier Model Tool Layer
• Open Movement and Community

These planned docs are not linked here until they exist in the repository.

How to Contribute

Permea needs contributions that make delivery evidence easier to inspect, compare, reproduce, and extend.

Useful contribution paths include:

• Dataset Card: describe a dataset source, labels, provenance, readiness, and limitations.
• Benchmark Task: define inputs, labels, metrics, split policy, baselines, and expected outputs.
• Evidence Card: structure literature or computational evidence with uncertainty and review status.
• Feature Descriptor: document a sequence-derived descriptor, computation method, limitations, and references.
• Baseline Model: add a comparable model or configuration with reproducible evaluation.
• Reproduction Report: report whether a benchmark run or evidence package reproduces as documented.
• Documentation improvement: clarify specs, contribution paths, limitations, or release guidance.

Start with CONTRIBUTING.md. Community standards are in CODE_OF_CONDUCT.md, security reporting is in SECURITY.md, and support guidance is in SUPPORT.md.

For public contribution surfaces, see Contribution Objects, Claim Boundary, and Community Roadmap.

Claim Boundaries

Permea public materials should preserve clear evidence levels:

• computational evidence only unless otherwise stated
• candidate prioritization before wet-lab
• no wet-lab validation claim
• no clinical or therapeutic effect claim
• no universal delivery prediction claim
• no state-of-the-art claim
• no delivery-is-solved claim

Benchmark metrics summarize behavior under a defined computational task. They do not prove transport, mechanism, safety, therapeutic effect, or generalization beyond the benchmark scope.

Status

Permea Core is active early-stage open infrastructure. The first evidence package exists in permea-signal-ml, and benchmark, dataset, and community documentation are being expanded.

This README does not make any public submission or readiness claim. Public releases, papers, and external postings should follow the repository's release and claim-review policies.

License, Citation, and Contact

• License: LICENSE
• Citation metadata: CITATION.cff
• Contact: a.kim@permea.us