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.

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.