Metadata-Version: 2.4
Name: agentic-proteins
Version: 0.2.2
Summary: Deterministic, artifact-first protein design runtime and CLI
Project-URL: Documentation, https://bijux.github.io/agentic-proteins/
Project-URL: Repository, https://github.com/bijux/agentic-proteins
Project-URL: Issues, https://github.com/bijux/agentic-proteins/issues
Project-URL: Changelog, https://github.com/bijux/agentic-proteins/blob/main/CHANGELOG.md
Author-email: Bijan Mousavi <mousavi.bijan@gmail.com>
License: Apache-2.0
License-File: LICENSE
Keywords: auditability,bioinformatics,cli,computational-biology,esmfold,fastapi,laboratory,pipelines,protein-design,protein-structure,reproducible-science,rosettafold
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS
Classifier: Operating System :: OS Independent
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: biopython>=1.83
Requires-Dist: boto3>=1.34
Requires-Dist: click>=8.1
Requires-Dist: fastapi>=0.115
Requires-Dist: loguru>=0.7
Requires-Dist: numpy<2.0,>=1.26
Requires-Dist: pydantic>=2.0.2
Requires-Dist: requests>=2.31
Requires-Dist: slowapi>=0.1
Requires-Dist: uvicorn>=0.30
Provides-Extra: api
Requires-Dist: openprotein-python>=0.8.8; extra == 'api'
Provides-Extra: dev
Requires-Dist: arq[redis]>=0.18; extra == 'dev'
Requires-Dist: bandit<2.0,>=1.7.10; extra == 'dev'
Requires-Dist: build<2.0,>=1.0.3; extra == 'dev'
Requires-Dist: codespell<3.0,>=2.3.0; extra == 'dev'
Requires-Dist: deptry<1.0,>=0.10.0; extra == 'dev'
Requires-Dist: httpx<1.0,>=0.27.0; extra == 'dev'
Requires-Dist: hypothesis-jsonschema<1.0,>=0.23.0; extra == 'dev'
Requires-Dist: hypothesis<7.0,>=6.103.0; extra == 'dev'
Requires-Dist: interrogate<2.0,>=1.7.0; extra == 'dev'
Requires-Dist: mkdocs-material<10.0,>=9.5.39; extra == 'dev'
Requires-Dist: mkdocs<2.0,>=1.6.1; extra == 'dev'
Requires-Dist: mypy<2.0,>=1.11.2; extra == 'dev'
Requires-Dist: pexpect<5.0,>=4.8.0; extra == 'dev'
Requires-Dist: pip-audit<3.0,>=2.7.3; extra == 'dev'
Requires-Dist: pydocstyle<7.0,>=6.2.1; extra == 'dev'
Requires-Dist: pyfakefs>=5.9.0; extra == 'dev'
Requires-Dist: pyright<2.0,>=1.1.320; extra == 'dev'
Requires-Dist: pytest-asyncio<2.0,>=1.0.0; extra == 'dev'
Requires-Dist: pytest-benchmark<5.0,>=4.0.0; extra == 'dev'
Requires-Dist: pytest-cov<7.0,>=6.2.1; extra == 'dev'
Requires-Dist: pytest-mock<4.0,>=3.14.1; extra == 'dev'
Requires-Dist: pytest-rerunfailures<14.0,>=13.0; extra == 'dev'
Requires-Dist: pytest-timeout<3.0,>=2.4.0; extra == 'dev'
Requires-Dist: pytest<9.0,>=8.4.1; extra == 'dev'
Requires-Dist: pytype>=2024.10.11; extra == 'dev'
Requires-Dist: pyyaml<7.0,>=6.0; extra == 'dev'
Requires-Dist: radon>=6.0.0; extra == 'dev'
Requires-Dist: reuse<6.0.0,>=4.0.0; extra == 'dev'
Requires-Dist: ruff<1.0,>=0.6.8; extra == 'dev'
Requires-Dist: types-colorama<1.0,>=0.0.14; extra == 'dev'
Requires-Dist: types-orjson<4.0,>=3.6.0; extra == 'dev'
Requires-Dist: types-pexpect<5.0,>=4.9.0; extra == 'dev'
Requires-Dist: types-psutil<7.0,>=6.0.0; extra == 'dev'
Requires-Dist: types-pyyaml<7.0,>=6.0.12; extra == 'dev'
Requires-Dist: typing-extensions<5.0,>=4.5.0; extra == 'dev'
Requires-Dist: vulture<3.0,>=2.7; extra == 'dev'
Provides-Extra: local-esmfold
Requires-Dist: einops>=0.7; extra == 'local-esmfold'
Requires-Dist: tokenizers>=0.14; extra == 'local-esmfold'
Requires-Dist: torch>=2.8; extra == 'local-esmfold'
Requires-Dist: transformers>=4.53.2; extra == 'local-esmfold'
Provides-Extra: local-rosettafold
Requires-Dist: torch>=2.8; extra == 'local-rosettafold'
Provides-Extra: nl
Requires-Dist: langchain-community>=0.2; extra == 'nl'
Requires-Dist: langchain-core>=0.2; extra == 'nl'
Requires-Dist: langchain-huggingface>=0.3.1; extra == 'nl'
Description-Content-Type: text/markdown

# Agentic Proteins
<a id="top"></a>

**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.

[![PyPI - Version](https://img.shields.io/pypi/v/agentic-proteins.svg)](https://pypi.org/project/agentic-proteins/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://pypi.org/project/agentic-proteins/)
[![Typing: typed (PEP 561)](https://img.shields.io/badge/typing-typed-4F8CC9.svg)](https://peps.python.org/pep-0561/)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-green.svg)](https://github.com/bijux/agentic-proteins/blob/main/LICENSE)
[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-brightgreen)](https://bijux.github.io/agentic-proteins/)
[![CI Status](https://github.com/bijux/agentic-proteins/actions/workflows/ci.yml/badge.svg)](https://github.com/bijux/agentic-proteins/actions)

> **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?](#why-agentic-proteins)
* [Try It in 20 Seconds](#try-it-in-20-seconds)
* [Key Features](#key-features)
* [Installation](#installation)
* [Quick Start](#quick-start)
* [Artifacts & Reproducibility](#artifacts--reproducibility)
* [API Surface](#api-surface)
* [Built-in Commands](#built-in-commands)
* [Tests & Quality](#tests--quality)
* [Project Tree](#project-tree)
* [Docs & Resources](#docs--resources)
* [Contributing](#contributing)
* [License](#license)



---

<a id="why-agentic-proteins"></a>
## 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.



---

<a id="try-it-in-20-seconds"></a>
## Try It in 20 Seconds

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



---

<a id="key-features"></a>
## 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.



---

<a id="installation"></a>
## Installation

Requires **Python 3.11+**.

```bash
# Isolated install (recommended)
pipx install agentic-proteins

# Standard
pip install agentic-proteins
```

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



---

<a id="quick-start"></a>
## Quick Start

```bash
# 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>
```



---

<a id="artifacts--reproducibility"></a>
## Artifacts & Reproducibility

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

```bash
agentic-proteins reproduce <run_id>
```

Docs: [Execution Lifecycle](https://bijux.github.io/agentic-proteins/architecture/execution_lifecycle/) · [Invariants](https://bijux.github.io/agentic-proteins/architecture/invariants/)



---

<a id="api-surface"></a>
## API Surface

The HTTP API exposes the same contracts as the CLI.

Docs: [API Overview](https://bijux.github.io/agentic-proteins/api/overview/) · [Schema](https://bijux.github.io/agentic-proteins/api/schema/)



---

<a id="built-in-commands"></a>
## 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](https://bijux.github.io/agentic-proteins/interface/cli_surface/)



---

<a id="tests--quality"></a>
## Tests & Quality

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

Quick commands:

```bash
make test
make lint
make quality
```

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



---

<a id="project-tree"></a>
## 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
```



---

<a id="docs--resources"></a>
## 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/



---

<a id="contributing"></a>
## Contributing

Welcome. See **[CONTRIBUTING.md](https://github.com/bijux/agentic-proteins/blob/main/CONTRIBUTING.md)** for setup and test guidance.



---

<a id="license"></a>
## License

Apache-2.0 — see **[LICENSE](https://github.com/bijux/agentic-proteins/blob/main/LICENSE)**.
© 2025 Bijan Mousavi.

# Changelog  
<a id="top"></a>  

All notable changes to **agentic-proteins** are documented here.  
This project adheres to [Semantic Versioning](https://semver.org) and the  
[Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format.  

<a id="unreleased"></a>  
## [Unreleased]  

<!-- unreleased start -->
### Added
* (add new entries via fragments in `changelog.d/`)

### Changed
* (add here)

### Fixed
* (add here)
<!-- unreleased end -->  

  

---  

<!-- release start -->  
<a id="v0-2-0"></a>  

## [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.  

<a id="v0-1-0"></a>  

## [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.
<!-- release end -->
