Skip to content

API Surface

The stable public API of this repository is deliberately small. Most users should treat the CLI, Python import surface, and checked-in evidence files as the main public contract. The HTTP-facing surface is frozen as a checked-in OpenAPI bundle, not as a live server promise.

Use this page when the question is about integration boundaries. Use the surface selection guide when the question is which public surface should own the work in the first place.

The Main Public Surfaces

  • the bijux-phylogenetics and phylogenetic console scripts
  • stable Python imports under bijux_phylogenetics
  • checked-in evidence studies under evidence-book/studies/
  • the frozen public API contract under apis/bijux-phylogenetics/v1/

Python Workflow Entry Points

For notebook, script, and pipeline use, the stable workflow-oriented Python surface lives under bijux_phylogenetics.api.

The named entry points are:

  • run_fasta_validation_workflow
  • run_alignment_workflow
  • run_trimming_workflow
  • run_tree_inference_workflow
  • run_support_workflow
  • run_sequence_to_tree_workflow
  • run_tree_comparison_workflow
  • run_comparative_model_workflow
  • run_ancestral_reconstruction_workflow
  • render_report_workflow
  • run_configured_phylo_workflow

These functions return typed workflow result objects:

  • FastaValidationResult
  • AlignmentWorkflowResult
  • TrimmingWorkflowResult
  • InferenceWorkflowResult
  • SupportWorkflowResult
  • SequenceToTreeWorkflowResult
  • TreeComparisonWorkflowResult
  • ComparativeModelWorkflowResult
  • AncestralReconstructionWorkflowResult
  • ReportWorkflowResult
  • ConfiguredPhyloWorkflowResult

Each result object delegates the underlying CLI-grade runtime report through a report field and attribute passthrough, adds stable write_json(...) serialization, and provides write_tsv(...) for workflow summaries where a tabular export is meaningful.

Native Runtime Entry Points

The public Python contract is no longer only workflow-shaped.

The native runtime also exposes named import families for:

  • likelihood and tree-inference surfaces under bijux_phylogenetics.phylo.likelihood
  • Bayesian priors, proposal schedules, diagnostics, and public inference entry points under bijux_phylogenetics.bayesian
  • benchmark contracts under bijux_phylogenetics.benchmark

Those are still narrower than the full internal module tree. If you need the native public contract, stay with the named surfaces that the public docs call out directly rather than assuming every helper in those packages is stable.

Frozen HTTP Contract

The checked-in OpenAPI bundle describes a future-compatible read surface for:

  • repository health and release identity
  • runtime package ownership summaries
  • evidence-study catalog access
  • evidence-study detail summaries for the governed PCM1 and PCM2 studies

The freeze bundle lives here:

  • apis/bijux-phylogenetics/v1/schema.yaml
  • apis/bijux-phylogenetics/v1/pinned_openapi.json
  • apis/bijux-phylogenetics/v1/schema.hash

Practical Rule

If you need an integration contract, start from the CLI, the named Python surface, or the frozen OpenAPI bundle. If an internal module or helper is not named in those surfaces, assume it can move.

Matching Practical Guides