agentic-proteins 0.2.3

Deterministic, artifact-first protein design runtime and CLI

Agentic Proteins

A deterministic, artifact-first protein design runtime and CLI — strict invariants, reproducible runs, and traceable outputs. Build reliable design workflows that are audit-ready and repeatable.

At a glance: deterministic execution • artifact immutability • invariant enforcement • reproducible runs • API + CLI surfaces • structured telemetry
Quality: coverage floors enforced per module, benchmark regression gate active, docs linted and built in CI, no telemetry.

---

Table of Contents

• Why Agentic Proteins?
• Try It in 20 Seconds
• Key Features
• Installation
• Quick Start
• Artifacts & Reproducibility
• API Surface
• Built-in Commands
• Tests & Quality
• Project Tree
• Docs & Resources
• Contributing
• License

---

Why Agentic Proteins?

Most protein design tooling prioritizes iteration speed. Agentic Proteins prioritizes repeatability, traceability, and audit-ready artifacts:

• Determinism first for reliable experiments and CI validation.
• Artifact immutability with hash-checked outputs.
• Invariant enforcement for predictable execution paths.
• Clear boundaries between deterministic execution and stochastic components.

---

Try It in 20 Seconds

pipx install agentic-proteins  # Or: pip install agentic-proteins
agentic-proteins --version
agentic-proteins run --sequence "ACDEFGHIKLMNPQRSTVWY"
agentic-proteins inspect-candidate <candidate_id>

---

Key Features

• Deterministic execution — reproducible runs with seeded randomness.
• Artifact-first workflow — immutable artifacts with stable hashes.
• Invariant enforcement — fail-fast checks across runtime boundaries.
• Dual surface — CLI and API share the same contracts.
• Structured telemetry — correlation IDs and traceable logs.

---

Installation

Requires Python 3.11+.

# Isolated install (recommended)
pipx install agentic-proteins

# Standard
pip install agentic-proteins

Upgrade: pipx upgrade agentic-proteins or pip install --upgrade agentic-proteins.

---

Quick Start

# Discover commands/flags
agentic-proteins --help

# Run a deterministic design cycle
agentic-proteins run --sequence "ACDEFGHIKLMNPQRSTVWY" --seed 7

# Inspect artifacts
agentic-proteins inspect-candidate <candidate_id>

---

Artifacts & Reproducibility

Artifacts are immutable and hash-addressed. Reproducing a run verifies hashes before returning outputs.

agentic-proteins reproduce <run_id>

Docs: Execution Lifecycle · Invariants

---

API Surface

The HTTP API exposes the same contracts as the CLI.

Docs: API Overview · Schema

---

Built-in Commands

Command	Description	Example
run	Execute a design run	agentic-proteins run --sequence ...
inspect-candidate	Inspect a candidate artifact	agentic-proteins inspect-candidate <id>
reproduce	Replay a run with hash checks	agentic-proteins reproduce <run_id>
api	Start the API server	agentic-proteins api --host 0.0.0.0

Full surface: CLI Surface

---

Tests & Quality

• Coverage floors: enforced per module in CI.
• Benchmarks: regression gate on critical path.
• Docs: linted and built in CI.

Quick commands:

make test
make lint
make quality

Artifacts: Generated in CI; see GitHub Actions for logs and reports.

---

Project Tree

api/            # OpenAPI schemas
config/         # Lint/type/security configs
docs/           # MkDocs site
makefiles/      # Task modules (docs, test, lint, etc.)
scripts/        # Helper scripts
src/agentic_proteins/  # Runtime + CLI implementation
tests/          # unit / integration / e2e

---

Docs & Resources

• Site: https://bijux.github.io/agentic-proteins/
• Changelog: https://github.com/bijux/agentic-proteins/blob/main/CHANGELOG.md
• Repository: https://github.com/bijux/agentic-proteins
• Issues: https://github.com/bijux/agentic-proteins/issues
• Security (private reports): https://github.com/bijux/agentic-proteins/security/advisories/new
• Artifacts: https://bijux.github.io/agentic-proteins/artifacts/

---

Contributing

Welcome. See CONTRIBUTING.md for setup and test guidance.

---

License

Apache-2.0 — see LICENSE. © 2025 Bijan Mousavi.

Changelog

All notable changes to agentic-proteins are documented here.
This project adheres to Semantic Versioning and the
Keep a Changelog format.

[Unreleased]

Added

• (add new entries via fragments in changelog.d/)

Changed

• (add here)

Fixed

• (add here)

---

[0.2.3]

Added

• Expanded provider test coverage for ColabFold, OpenProtein, and local ESMFold utilities.
• Runtime capability validation tests and candidate filter unit coverage.
• Stability marking test for module annotations.

Changed

• Hardened local ESMFold utility tests to exercise error and success branches.

Fixed

• Reliability checks and helper tests to keep coverage and gating stable.

[0.2.2]

Added

• Release alignment for docs, gates, and CI structure.

Changed

• Consistent documentation build and validation wiring.

Fixed

• Minor release hygiene issues discovered in CI.

[0.2.1]

Added

• Expanded unit and integration coverage with new invariants, API, and docs gates.
• Additional tests for provider isolation, reproducibility, and abuse-case blocking.
• Fancy PyPI readme fragments for README + changelog publishing.

Changed

• Refactored tests/unit into a structured layout for clearer ownership.

Fixed

• Coverage floors and CI gates stabilized around new test layout.

[0.2.0]

Added

• Architecture invariants, threat model skeleton, and design debt ledger.
• Reproducible runs via agentic-proteins reproduce <run_id> with hash checks.
• Determinism tests, artifact immutability tests, and invariant regression coverage.
• Provider isolation checks and chaos failure test for mid-run provider loss.
• Benchmark regression gate and per-module coverage floors in CI.
• Documentation system contracts, lint gates, and CLI surface audit coverage.
• API error taxonomy enforcement, correlation ID logging test, and OpenAPI drift guard.
• Dependency allowlist enforcement for SBOM changes.

[0.1.0]

Added

• Deterministic, artifact-first execution engine with explicit run directories and state snapshots.
• Agent-based architecture covering planning, analysis, execution, verification, and reporting.
• End-to-end design loop with failure handling, stagnation detection, and human-in-the-loop gating.
• CLI for running, resuming, inspecting, comparing, and exporting protein design runs.
• Local and remote provider abstractions with explicit capability and requirement checks.
• Structured reporting system with machine-readable artifacts and human-readable summaries.
• Integrated evaluation pipeline supporting structure-based metrics and ground-truth comparison.
• Reproducibility controls, observability hooks, and execution telemetry.
• Example datasets and reference runs for local experimentation and validation.
• Comprehensive test suite covering unit, integration, regression, and execution boundaries.