Add Optional CrapsSim Engine API (External Control + Full Test Parity)

[nova-rey]

This PR introduces a small, self-contained “CrapsSim Engine API” module that exposes the engine through a clean action-based interface. The goal is to support external orchestration layers (e.g., simulation runners, strategy controllers, or automated tests) without impacting the core engine or changing behavior for existing users.

A few important points up front:

The API is entirely optional.
Core users who want the standard library experience won’t notice anything new. No dependencies were added, and nothing in the engine imports the API.

It lives in its own directory (crapssim_api/) and can be installed independently if desired. If someone doesn’t need it, it stays out of the way.

No engine logic was touched.
All behavior remains defined by CrapsSim itself. The API simply exposes verbs that map cleanly to existing bet types and actions.

Full deterministic parity was validated.
The API was tested against the engine using a roll-by-roll scenario harness plus a larger surface test suite. All sequences matched: bankroll, bets, error codes, and resolution order. Parity reports are included.

The end result is an optional integration layer that allows higher-level tooling to interact with CrapsSim predictably, while keeping the engine itself pure, stable, and focused. If the API ever needs maintenance, I’m happy to keep it aligned with upstream changes so the core project doesn’t have to take on that burden.

If you’re open to including it, I think it gives CrapsSim a clean extension path without adding weight to the core package.

[nova-rey]

Following up on your earlier notes and the recent v0.4.0 changes.

The PR briefly disappeared from my view when I adjusted my fork’s default branch during some CI troubleshooting; once reverted, GitHub correctly reconnected me to this original PR. Nothing on your side was affected, but I wanted to mention it in case the activity log looked odd.

Everything you flagged in your initial feedback has now been addressed:

• Engine v0.4.0 updates
The API has been updated to match all of the bet surface and rule changes introduced in v0.4.x. This includes the new bet types, updated odds behavior, vig handling, and Don’t Come push-on-12 behavior. The verb mappings were reviewed and brought into complete alignment with the engine’s current constructors and semantics.

• Python compatibility (3.10–3.13)
The missing httpx dependency has been added to the [api] extra, resolving the collection failures affecting 3.11–3.13. The suite now installs and collects cleanly across the 3.10–3.13 range. The packaging metadata was also updated to reflect this support.

• setup.cfg restoration
setup.cfg has been restored and cleaned up. Extras, classifiers, and version metadata are now consistent with the rest of the package.

• Maintenance model
The API remains fully isolated within crapssim_api/, and no changes to the core engine were required to support these updates. This allows core development to continue without constraint, with API updates applied afterward as needed. Documentation for maintainers clarifies the intended model going forward.

• Documentation and structure
The documentation has been consolidated and reorganized to remove duplication, separate public-facing material from maintainer material, and bring all references up to date with the current behavior of the API. This includes updated installation guidelines, verb references, determinism notes, session/tape descriptions, and compatibility information.

• Behavioral parity verification
A full sequence and stress gauntlet was run against both the engine API and the vanilla engine after the compatibility fixes. All scenarios matched across both sides. CI now includes API tests across the supported Python versions.

If anything needs clarification or refinement, I’m happy to adjust it. Thanks again for taking the time to look at this, I appreciate your willingness to include the API layer and I’m committed to maintaining it as the engine continues to evolve.