{"id":50715175,"url":"https://github.com/nshkrdotcom/trinity_framework","last_synced_at":"2026-06-09T18:32:10.206Z","repository":{"id":356853113,"uuid":"1234313961","full_name":"nshkrdotcom/trinity_framework","owner":"nshkrdotcom","description":"Reusable TRINITY router and coordination framework for deterministic agent routing, provider pool contracts, typed coordination patterns, and local-first AI infrastructure.","archived":false,"fork":false,"pushed_at":"2026-05-22T19:42:04.000Z","size":41,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-22T22:28:48.754Z","etag":null,"topics":["agent-coordination","agentic-systems","ai-infrastructure","beam","contracts","deterministic-runtime","elixir","governance","local-first","mix","nshkr-ai-infra","nshkrdotcom","otp","provider-pools","router","trinity","trinity-framework","typed-contracts","weld","workflow"],"latest_commit_sha":null,"homepage":null,"language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nshkrdotcom.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-10T02:48:37.000Z","updated_at":"2026-05-22T19:42:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nshkrdotcom/trinity_framework","commit_stats":null,"previous_names":["nshkrdotcom/trinity_framework"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nshkrdotcom/trinity_framework","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nshkrdotcom%2Ftrinity_framework","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nshkrdotcom%2Ftrinity_framework/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nshkrdotcom%2Ftrinity_framework/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nshkrdotcom%2Ftrinity_framework/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nshkrdotcom","download_url":"https://codeload.github.com/nshkrdotcom/trinity_framework/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nshkrdotcom%2Ftrinity_framework/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34121021,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-coordination","agentic-systems","ai-infrastructure","beam","contracts","deterministic-runtime","elixir","governance","local-first","mix","nshkr-ai-infra","nshkrdotcom","otp","provider-pools","router","trinity","trinity-framework","typed-contracts","weld","workflow"],"created_at":"2026-06-09T18:32:10.124Z","updated_at":"2026-06-09T18:32:10.189Z","avatar_url":"https://github.com/nshkrdotcom.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/trinity_framework.svg\" alt=\"TRINITY Framework\" width=\"220\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/nshkrdotcom/trinity_framework\"\u003e\u003cimg alt=\"GitHub\" src=\"https://img.shields.io/badge/github-nshkrdotcom%2Ftrinity__framework-24292f?logo=github\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://huggingface.co/datasets/nshkrdotcom/trinity-coordinator-adapted-qwen3-0.6b\"\u003e\u003cimg alt=\"HuggingFace Dataset\" src=\"https://img.shields.io/badge/huggingface-adapted--qwen3--0.6b-ffd21e\" /\u003e\u003c/a\u003e\n  \u003cimg alt=\"Elixir\" src=\"https://img.shields.io/badge/elixir-1.18%2B-4b275f?logo=elixir\" /\u003e\n  \u003cimg alt=\"License\" src=\"https://img.shields.io/badge/license-MIT-0f766e\" /\u003e\n\u003c/p\u003e\n\n# TRINITY Framework\n\n`trinity_framework` is the new source-of-truth TRINITY repository. The root\nMix project is the assembled framework distribution: it wires the\ndeconstructed contracts, coordinator behavior, Sakana artifact pipeline, bridge\npackages, single-node runtime, operator command surface, and eval example into\none standalone checkout.\n\nThe completion target for this repo is exact and testable: all framework\nruntime, operator, bridge, eval, and Crucible assembly behavior is owned here\nthrough the deconstructed package architecture. There is no alternate old route\nmode in this repository.\n\n## Status\n\nThe root project owns the operator-facing assembly:\n\n- `core/trinity_contracts` defines the reusable router, role, provider,\n  verifier, trace, session, artifact, and coordination contracts.\n- `core/trinity_coordinator_core` owns the coordinator behavior extracted from\n  the former monolith.\n- `core/trinity_sakana_contracts` and `core/trinity_sakana_pipeline` own the\n  adapted-Qwen/Sakana artifact contracts, export, import, parity, and trace\n  surfaces.\n- `bridges/trinity_bridge_inference`,\n  `bridges/trinity_bridge_self_hosted_inference`, and\n  `bridges/trinity_bridge_trace` connect TRINITY to inference and trace\n  packages without moving ownership into the root facade.\n- `apps/trinity_single_node` is the standalone runtime app.\n- `tools/trinity_ops` owns every `mix trinity.*` operator command.\n- `examples/qwen_router_prompt_eval` owns the 37-case Qwen router prompt eval.\n- `examples/crucible_route` shows the reusable Crucible route path.\n\nThis repo is also the integration point for the nshkr stack. It must be able to\nrun standalone and sit inside larger product, governance, execution, and testing\nflows through explicit package contracts and governed provider boundaries.\n\n## Mezzanine Router Adapter\n\n`Trinity.MezzanineRouterAdapter` in `core/trinity_coordinator_core` implements\n`Mezzanine.AIExecution.RouterAdapter` for the NSHKR router fabric. It returns\nroute decision refs and bounded route receipts to Mezzanine; it does not\nexecute models, grant authority, or mutate product projections.\n\nThe adapter maps abstract model class refs to concrete model profile refs\nthrough an explicit class-profile policy map. A route request that names a\nmodel class without an allowed profile mapping fails closed with a bounded\nroute failure code instead of reusing the class ref as a runtime profile.\n\n## Quickstart\n\n```bash\ngit clone https://github.com/nshkrdotcom/trinity_framework\ncd trinity_framework\nmix deps.get\nmix test\nmix ci\n```\n\n`mix test` must run root aggregate tests. If it reports that there are no tests\nto run, the root project is not complete.\n\nFor CUDA routes:\n\n```bash\nXLA_TARGET=cuda12 mix trinity.env.check\n```\n\n`XLA_TARGET=cuda12` is the supported CUDA target. CPU/mock documentation and\nsmoke work can use the `mock_tiny` runtime profile where a command exposes\n`--runtime-profile`.\n\n## Fetch The Adapted Bundle\n\nThe generated adapted-Qwen3 safetensors bundle is not committed to git. The\npin file is committed at `priv/sakana_trinity/artifact_pin.json`, and the\ndefault published dataset remains:\n\n```text\nnshkrdotcom/trinity-coordinator-adapted-qwen3-0.6b\n```\n\nFetch and verify the bundle:\n\n```bash\nmix trinity.artifact.fetch\n```\n\nOffline cache-only fetch:\n\n```bash\nHF_HUB_OFFLINE=1 mix trinity.artifact.fetch --offline\n```\n\nCustom destination or pin:\n\n```bash\nmix trinity.artifact.fetch --dest priv/sakana_trinity/my_bundle\nmix trinity.artifact.fetch --pin priv/forks/my_pin.json\n```\n\nThe default runtime bundle lands at:\n\n```text\npriv/sakana_trinity/adapted_qwen3_0_6b_layer26\n```\n\n## Run The Runtime\n\nSafe mock-provider smoke checks:\n\n```bash\nmix trinity.gates\nmix trinity.route.demo \\\n  --mock-provider \\\n  --runtime-profile mock_tiny \\\n  --max-turns 1 \\\n  --trace-out tmp/trinity_route_demo.jsonl\n\nmix trinity.hitl.mock_loop \\\n  --runtime-profile mock_tiny \\\n  --max-turns 1 \\\n  --trace-out tmp/trinity_mock_loop.jsonl\n\nmix trinity.crucible.inspect --runtime-profile mock_tiny\nmix trinity.crucible.matrix_eval --runtime-profile mock_tiny\n```\n\nCUDA/adapted bundle checks:\n\n```bash\nXLA_TARGET=cuda12 mix trinity.hitl.gpu\nXLA_TARGET=cuda12 mix trinity.hitl.vector\nXLA_TARGET=cuda12 mix trinity.hitl.head_route\nXLA_TARGET=cuda12 mix trinity.hitl.base_qwen\nXLA_TARGET=cuda12 mix trinity.hitl.adapted\n```\n\nGated live provider route demo:\n\n```bash\nXLA_TARGET=cuda12 mix trinity.route.demo \\\n  --allow-live \\\n  --provider-pool governed \\\n  --governed-provider openai \\\n  --governed-model gpt-4.1-mini \\\n  --governed-api-key \"$OPENAI_API_KEY\" \\\n  --trace-out tmp/trinity_live_route_demo.jsonl\n```\n\nLive provider commands must stay opt-in. The default path should not spend\nprovider budget.\n\n## Run The Eval\n\nThe main route-decision proof is the 37-case Qwen router prompt eval:\n\n```bash\ncd examples/qwen_router_prompt_eval\nXLA_TARGET=cuda12 mix run lib/qwen_router_prompt_eval.exs -- \\\n  --snapshot fixtures/qwen_router_prompt_eval_logits.json \\\n  --determinism-runs 2\n```\n\nUseful eval variants:\n\n```bash\nmix run lib/qwen_router_prompt_eval.exs -- --list-cases\n\nXLA_TARGET=cuda12 mix run lib/qwen_router_prompt_eval.exs -- \\\n  --case planner.basic \\\n  --snapshot fixtures/qwen_router_prompt_eval_logits.json\n\nXLA_TARGET=cuda12 mix run lib/qwen_router_prompt_eval.exs -- \\\n  --snapshot-out tmp/qwen_router_prompt_eval_logits.json \\\n  --determinism-runs 2\n```\n\nThe eval asserts route decisions, margins, stable transcript fields, and\ndeterminism.\n\nThe root eval wrapper runs the Crucible route-decision path:\n\n```bash\nmix trinity.eval qwen_router_prompt_eval\n```\n\nThe Crucible path evaluates route-decision contract strictness, expected-role\ndiagnostics, confidence bands, trajectory margins, and trace-derived evidence\nover the 37-case route suite. It does not compare generated text.\n\n## Generate Safetensors\n\nThe adapted bundle can be regenerated from the Sakana vector and Qwen base\nmodel:\n\n```bash\nXLA_TARGET=cuda12 mix trinity.sakana.export_adapted \\\n  --out priv/sakana_trinity/adapted_qwen3_0_6b_layer26 \\\n  --source-vector priv/sakana_trinity/artifacts/trinity_router_es_vector.safetensors \\\n  --force\n```\n\nDry-run the export plan without writing the bundle:\n\n```bash\nmix trinity.sakana.export_adapted --dry-run --json\n```\n\nRun one tensor slice while debugging:\n\n```bash\nXLA_TARGET=cuda12 mix trinity.sakana.export_adapted \\\n  --out tmp/adapted_qwen3_probe \\\n  --only-index 1 \\\n  --force\n```\n\nPython semantic imports and parity checks:\n\n```bash\nmix trinity.sakana.import_python \\\n  --source-dir priv/sakana_trinity/python_export \\\n  --manifest priv/sakana_trinity/reference/sakana_python_reference_manifest.json \\\n  --out priv/sakana_trinity/adapted_qwen3_0_6b_layer26 \\\n  --json\n\nmix trinity.sakana.parity_sample \\\n  --python-report priv/sakana_trinity/reference/sakana_python_reference_manifest.json \\\n  --semantic-only \\\n  --no-cuda \\\n  --out tmp/sakana_parity_sample.json\n\nmix trinity.sakana.large_tensor_chunks \\\n  --python-report priv/sakana_trinity/reference/sakana_python_reference_manifest.json \\\n  --chunk-rows 2048 \\\n  --no-cuda \\\n  --out tmp/sakana_large_tensor_chunks.json\n```\n\n## Upload To HuggingFace\n\nPublishing is intentionally not hidden behind an accidental default command.\nUse the `hf_hub` library in an authenticated IEx session after generating and\nreviewing the bundle:\n\n```elixir\nrepo_id = \"nshkrdotcom/trinity-coordinator-adapted-qwen3-0.6b\"\nsource_dir = \"priv/sakana_trinity/adapted_qwen3_0_6b_layer26\"\ntoken = caller_owned_huggingface_token\n\n{:ok, _repo} =\n  HfHub.Repo.create(repo_id,\n    repo_type: :dataset,\n    exist_ok: true,\n    token: token\n  )\n\n{:ok, commit} =\n  HfHub.Commit.upload_folder(\n    source_dir,\n    repo_id,\n    repo_type: :dataset,\n    token: token,\n    commit_message: \"Publish adapted Qwen3 bundle\",\n    ignore_patterns: [\"*.log.jsonl\", \"*.tmp\", \".DS_Store\"]\n  )\n\ncommit\n```\n\nAfter upload, verify the remote tree against `manifest.json`, regenerate or\nupdate `priv/sakana_trinity/artifact_pin.json`, and tag the remote revision that\nfresh clones should consume.\n\n## Command Reference\n\n```text\nmix trinity.artifact.fetch             # Download and SHA-verify the adapted bundle\nmix trinity.demo                       # Compatibility wrapper for the route demo\nmix trinity.env.check                  # Validate build/runtime environment\nmix trinity.gates                      # Run the TRINITY quality gate matrix\nmix trinity.hitl.adapted               # Adapted-Qwen coordinator route check\nmix trinity.hitl.base_qwen             # Base Qwen hidden-state check\nmix trinity.hitl.gpu                   # GPU/EXLA CUDA visibility check\nmix trinity.hitl.head_route            # Hidden-state to Sakana-head route check\nmix trinity.hitl.mock_loop             # Mock orchestrator loop check\nmix trinity.hitl.vector                # Sakana router-vector split check\nmix trinity.parity.check               # Python/Elixir parity comparator wrapper\nmix trinity.route.demo                 # Gated route demo\nmix trinity.sakana.export_adapted      # Export adapted Qwen tensors and router head\nmix trinity.sakana.import_python       # Import Python semantic Sakana artifacts\nmix trinity.sakana.large_tensor_chunks # Replay large tensor stages in chunks\nmix trinity.sakana.parity_sample       # Emit SVD/SVF parity diagnostics\nmix trinity.sakana.router_trace        # Emit fixed-transcript router trace\n```\n\nRun `mix help --search trinity` for the authoritative local task list.\n\n## Quality Gates\n\nThe final root acceptance target is:\n\n```bash\nmix test\nmix ci\nmix help --search trinity\nmix trinity.gates\nmix trinity.artifact.fetch\nXLA_TARGET=cuda12 mix trinity.hitl.gpu\nXLA_TARGET=cuda12 mix trinity.hitl.vector\nXLA_TARGET=cuda12 mix trinity.hitl.head_route\nXLA_TARGET=cuda12 mix trinity.hitl.base_qwen\nXLA_TARGET=cuda12 mix trinity.hitl.adapted\n```\n\n`mix ci` expands to dependency fetch, formatting, warning-as-error compile,\ntests, Credo strict, Dialyzer, docs generation, and Weld projection checks.\nNo framework warnings, test failures, Credo issues, or Dialyzer issues are\nacceptable for sign-off.\n\n## Guides\n\n- [Onboarding](guides/onboarding.md)\n- [Current Direction](guides/current_direction.md)\n- [System Architecture](guides/system_architecture.md)\n- [Service Buildout](guides/service_buildout.md)\n- [Operations And QC](guides/operations_qc.md)\n- [Artifact Distribution](guides/artifact_distribution.md)\n- [Artifacts And Export](guides/artifacts_and_export.md)\n- [Runtime Profiles](guides/runtime_profiles.md)\n- [Evals](guides/evals.md)\n- [Python Parity Reconstruction](guides/python_parity_reconstruction.md)\n- [Python Torch Trace Provider](guides/python_torch_trace_provider.md)\n- [Stage Checks And Tolerances](guides/stage_checks_and_tolerances.md)\n- [SVD Generation Runbook](guides/svd_generation_runbook.md)\n- [Provider Service Hardening](guides/provider_service_hardening.md)\n- [Troubleshooting](guides/troubleshooting.md)\n- [Production Runbook](docs/production_runbook.md)\n- [Provider Smoke Tests](docs/provider_smoke_tests.md)\n- [Sakana Adapted Artifact Plan](docs/sakana_adapted_artifact_plan.md)\n- [Trace Persistence](docs/trace_persistence.md)\n\n## Repository Layout\n\n```text\nassets/                         Logos and static docs assets\nbridges/                        Integration bridge packages\ncore/                           Contracts, coordinator core, Sakana pipeline\napps/trinity_single_node/       Standalone runtime application\ntools/trinity_ops/              mix trinity.* operator commands\nexamples/qwen_router_prompt_eval/ 37-case router prompt eval\npriv/sakana_trinity/            Artifact pins, scripts, references, local bundle\nguides/                         Operator and architecture documentation\ndocs/                           Reference notes and production runbooks\ntest/                           Root aggregate and drift tests\n```\n\n## Requirements\n\n- Elixir/Erlang from `.tool-versions`.\n- CUDA-capable Linux host for CUDA acceptance and adapted-Qwen runtime checks.\n- HuggingFace network access for first-time `mix trinity.artifact.fetch`.\n- `HF_TOKEN` or equivalent HuggingFace auth only when publishing bundles.\n- Python, PyTorch, Transformers, NumPy, and safetensors only for Python parity\n  reconstruction and original Sakana script workflows.\n\n## References\n\n[1] Jinglue Xu, Qi Sun, Peter Schwendeman, Stefan Nielsen, Edoardo\nCetin, and Yujin Tang. *TRINITY: An Evolved LLM Coordinator*.\narXiv:2512.04695, 2026. \u003chttps://arxiv.org/abs/2512.04695\u003e\n\n## License\n\nMIT.\n\n## V5 Status\n\nStatus: `trinity-v5-live-replay-matrix-python-trace-passing`.\n\nThe Crucible operator tasks support V5 artifact-backed trace replay, native\nhosted runtime live inspect, live matrix eval, role-boundary stability reports,\npolicy/route decision artifact emission, and external Python/PyTorch trace\nproduction for model internals that Bumblebee does not expose:\n\n```bash\nmix trinity.crucible.inspect --trace tmp/crucible_v5/traces/native/model_forward_live.trace.jsonl --artifact-root tmp/crucible_v5\nmix trinity.crucible.matrix_eval --trace tmp/crucible_v5/traces/native --artifact-root tmp/crucible_v5\nTRINITY_CRUCIBLE_LIVE=true mix trinity.crucible.inspect --live --model-id gpt2 --backend binary --artifact-root tmp/crucible_v5 --prompt \"Hi\"\nTRINITY_CRUCIBLE_LIVE=true mix trinity.crucible.matrix_eval --live --limit 37 --backend binary --artifact-root tmp/crucible_v5\npython3 tools/python/crucible_torch_trace.py --model-id gpt2 --artifact-root tmp/crucible_v5 --trace-name python_torch_gpt2_phase15\nmix trinity.crucible.inspect --trace tmp/crucible_v5/traces/python/python_torch_gpt2_phase15.trace.jsonl --artifact-root tmp/crucible_v5\n```\n\nSee [Trinity Live Inspect](guides/trinity_live_inspect.md) and\n[Python Torch Trace Provider](guides/python_torch_trace_provider.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnshkrdotcom%2Ftrinity_framework","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnshkrdotcom%2Ftrinity_framework","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnshkrdotcom%2Ftrinity_framework/lists"}