BitTrace API v3 Source

BitTrace is a source-available Python package and CLI for generating, verifying, and packaging BitTrace artifacts through a stable packed-bit modeling framework.

BitTrace is source-available, not OSI open source.

• Evaluation use is allowed.
• Commercial or production use requires a separate written commercial license.

Reference Lane vs BitTrace Core

BitTrace core is the packed-bit training, search, artifact, freeze/export, and verification framework surfaced through the public bittrace CLI and bittrace import namespace.

The repo currently ships one supported stable commercial reference lane:

• frontend: temporal_threshold_36
• backend: Lean-Lean

That frozen reference lane is the supported path for stable commercial behavior. It is not the whole BitTrace modeling surface.

BitTrace API is not just a frontend identity. The fact that the supported lane is frozen around temporal_threshold_36 + Lean-Lean does not mean every conceivable BitTrace project must use that exact front gate in every context.

Developers and integrators may still own project-specific work such as:

• staging and adapter logic
• feature definition and thresholding posture
• label mapping and split discipline
• target-specific deployment constraints

Custom front gates, adapters, and task-specific modeling work may exist, but they are project-specific work outside the supported stable lane unless the repo and docs explicitly document them as supported.

Canonical Reference

Technical truth lives in docs/HANDBOOK.md.

If another repo document conflicts with the handbook, the handbook wins. The other docs are intentionally shorter and role-specific.

Public Surface

• import namespace: bittrace
• CLI: bittrace
• module fallback: python -m bittrace
• installed distribution name: bittrace-api-v3-source

Supported stable workflows:

• bittrace campaign
• bittrace verify
• bittrace deployment-candidate
• bittrace persistence

Experimental workflows remain under bittrace experimental ... and are outside the supported commercial lane.

Versioning

BitTrace API v3 names the frozen repository and product generation.

The Python distribution bittrace-api-v3-source follows its own semver release line inside that v3 generation. A package release such as 0.3.1 is still the same BitTrace API v3 public surface unless the supported bittrace import or CLI contract changes.

Documentation

Use Case	Document
Fastest repo-native setup and smoke validation	docs/QUICKSTART.md
Canonical technical reference	docs/HANDBOOK.md
Command, YAML, and direct-runtime cheat sheet	docs/USER_GUIDE.md
Supported public surface	SUPPORTED_SCOPE.md
Deployment ownership boundary	DEPLOYMENT_BOUNDARY.md
Working effectively with an AI assistant	docs/AI_ASSISTANT_GUIDE.md
Release-facing checks and packaging	docs/RELEASE_WORKFLOW.md
Release checklist and cut prep	docs/releases/RELEASE_CHECKLIST.md
Change history	CHANGELOG.md
Current limitations	KNOWN_ISSUES.md
Evaluation and commercial terms	LICENSE.md
Patent notice wording	NOTICE_PATENT_PENDING.md

Start with docs/README_DOC_MAP.md if you want the reading order first.

Boundary Reminder

Use SUPPORTED_SCOPE.md and DEPLOYMENT_BOUNDARY.md for support and ownership questions. Use the handbook for workflow, contract, artifact, and troubleshooting detail.