Package overview

agentic-proteins is a migration bridge, not a second runtime. Its source tree mirrors historical module families so existing imports keep resolving while their objects are supplied by canonical modules.

flowchart LR
    consumer["legacy consumer"]
    inventory["observed imports, commands, and HTTP routes"]
    bridge["agentic_proteins compatibility surface"]
    canonical["canonical core or runtime owner"]
    parity["behavior and artifact comparison"]
    closure["consumer migrated; bridge use absent"]
    consumer --> inventory --> bridge --> canonical --> parity --> closure

The unit of migration is a consumer, not a module file. A wrapper can be technically correct while an application still depends on legacy CLI names, HTTP schemas, provider behavior, serialized types, or exception semantics.

Preserved surfaces

Surface	Compatibility behavior	Canonical owner
Python execution and orchestration imports	re-export run, execution, agent, tool, and state objects	bijux-proteomics-runtime
provider imports	re-export provider contracts and local, remote, or heuristic implementations	bijux-proteomics-runtime
CLI	expose the canonical Click command group under agentic-proteins	bijux-proteomics-runtime
HTTP application and v1 routes	forward application, route, schema, and error imports	bijux-proteomics-runtime
structure reports	forward report behavior to the scientific owner	bijux-proteomics-core

The bridge may depend only on core and runtime. It must not acquire direct dependencies on foundation, knowledge, intelligence, lab, development tooling, or alias distributions.

Migration lifecycle

stateDiagram-v2
    [*] --> Inventoried: legacy path detected
    Inventoried --> Wrapped: canonical target declared
    Wrapped --> Migrated: callers use canonical import
    Migrated --> Retired: compatibility evidence permits removal
    Inventoried --> Removed: dead namespace has no supported caller

The generated compatibility inventory classifies every module. A wrapper must remain behavior-free beyond adaptation needed to preserve its contract. A dead module has no canonical behavior and should not gain any. A canonical or duplicate classification inside this package is a boundary violation.

Classification	Permitted content	Evidence needed before change
wrapper	import forwarding or the minimum declared adaptation	canonical target, parity tests, affected consumers
dead	no supported behavior	proof that no governed consumer or public route relies on the namespace
canonical	none in this package	move ownership to the canonical package and reclassify the bridge
duplicate	none	select one canonical owner and remove independent behavior

Retirement requires more than a passing import inventory. It requires caller migration, behavior parity on preserved surfaces, absence of legacy artifacts in supported applications, and a release decision that names the compatibility promise being removed.

Safe use

1. Pin the compatibility package and canonical runtime to compatible releases.
2. Identify imported agentic_proteins modules and invoked legacy commands.
3. Map each import through the migration guide.
4. Move application tests to canonical imports.
5. Remove the compatibility dependency after all preserved surfaces disappear from the application.

Do not add new application code against this package. The canonical runtime handbook documents the maintained execution surface.

Migration is complete when application imports, command invocations, HTTP clients, persisted schema references, and provider configuration all name the canonical owner, and the application tests pass without installing the bridge.