API Guide

Buffalo Core is intentionally small. Its public API is organized around four modules.

buffalo_core.typing

Use buffalo_core.typing for shared NumPy-oriented type aliases. These aliases keep signatures consistent across Buffalo projects without forcing each project to redefine the same typing vocabulary.

Reference: Module documentation

Use this module when:

  • a public API should accept NumPy scalar values as well as Python scalars,

  • a public API should clearly distinguish normalized arrays from flexible inputs,

  • or two Buffalo projects should share the same signature conventions.

buffalo_core.numeric

Use buffalo_core.numeric for function-boundary normalization helpers. These helpers turn flexible numeric inputs into stable NumPy arrays or native Python scalars.

Reference: Module documentation

Use this module when:

  • a public function accepts FloatInput or IntInput,

  • downstream vectorized code expects normalized arrays,

  • or a third-party boundary requires a Python float or int.

buffalo_core.schema

Use buffalo_core.schema for dataclass-attached field metadata that downstream GUIs or editors can inspect uniformly. This module provides a shared builder for field metadata, structured choice labels, conditional UI rules, and a dataclass accessor for reading the stored contract back out.

Reference: Module documentation

Use this module when:

  • a schema dataclass should remain the source of truth while still carrying machine-readable GUI hints,

  • enum-like choices need separate serialized values and display labels,

  • a workflow needs one small nested dataclass tree for editor or inspection tooling,

  • or two Buffalo projects should share the same metadata vocabulary for editors or tree builders.

buffalo_core.diagnostics

Use buffalo_core.diagnostics for structured diagnostics and diagnostics-aware workflow results. This module provides stable, machine-readable primitives for reporting errors, warnings, and informational results without inventing a local diagnostics model in each Buffalo project.

Reference: Module documentation

Use this module when:

  • a workflow should return a value together with warnings or informational messages,

  • validation code should return structured issues instead of only raising,

  • or diagnostics should be inspectable by tests, CLI tools, or future GUIs.

What Does Not Belong Here

Buffalo Core should remain domain-light. It should not absorb aerodynamic formulations, geometry-family logic, or project-specific runtime abstractions from Buffalo Wings or Buffalo Panel.

For the complete generated reference tree, see Module Reference.