@teevee98/synapse-hub 0.0.0-stage → 3.8.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agents/agents/api-engineer.md +67 -0
- package/.agents/agents/failure-analyst.md +75 -0
- package/.agents/agents/live-explorer.md +70 -0
- package/.agents/agents/orchestrator.md +104 -0
- package/.agents/agents/perf-engineer.md +74 -0
- package/.agents/agents/pom-crafter.md +112 -0
- package/.agents/agents/quality-gatekeeper.md +87 -0
- package/.agents/agents/test-designer.md +73 -0
- package/.agents/agents/test-runner.md +67 -0
- package/.agents/rules/author-integrity-guard.md +33 -0
- package/.agents/rules/communication-style.md +18 -0
- package/.agents/rules/context-engineering.md +37 -0
- package/.agents/rules/git-push-protocol.md +33 -0
- package/.agents/rules/graphify.md +14 -0
- package/.agents/rules/lessons-learned.md +25 -0
- package/.agents/rules/mandatory-playwright-live.md +25 -0
- package/.agents/rules/mobile_appium_rules.md +43 -0
- package/.agents/rules/performance_testing_rules.md +35 -0
- package/.agents/rules/skill-precedence.md +29 -0
- package/.agents/rules/systematic-debugging.md +36 -0
- package/.agents/skills/actor-qa-swarm/SKILL.md +77 -0
- package/.agents/skills/actor-qa-swarm/examples/broker_sharding_sample.json +12 -0
- package/.agents/skills/agent-orchestration-multi-agent-optimize/SKILL.md +88 -0
- package/.agents/skills/agent-orchestration-multi-agent-optimize/examples/swarm_workload_config.json +15 -0
- package/.agents/skills/agentless-qa-repair/SKILL.md +69 -0
- package/.agents/skills/agentless-qa-repair/examples/healing_report_sample.json +17 -0
- package/.agents/skills/agentless-qa-repair/examples/three_phase_repair_workflow.md +40 -0
- package/.agents/skills/antigravity-test-sentinel/SKILL.md +63 -0
- package/.agents/skills/antigravity-test-sentinel/examples/dod_gate_policy.json +11 -0
- package/.agents/skills/antigravity-test-sentinel/examples/sprint_dod_enforcement.md +47 -0
- package/.agents/skills/api-network-mocking-interception/SKILL.md +142 -0
- package/.agents/skills/api-network-mocking-interception/examples/network_route_stub.json +9 -0
- package/.agents/skills/api-spec-to-e2e-matrix/SKILL.md +80 -0
- package/.agents/skills/api-spec-to-e2e-matrix/examples/sample_openapi.json +19 -0
- package/.agents/skills/architecture-decision-records/SKILL.md +64 -0
- package/.agents/skills/architecture-decision-records/examples/0001-record-architecture-decisions.md +12 -0
- package/.agents/skills/auth-session-and-cookie-manager/SKILL.md +75 -0
- package/.agents/skills/auth-session-and-cookie-manager/examples/multi_role_auth_matrix.md +70 -0
- package/.agents/skills/auth-session-and-cookie-manager/examples/storage_state_sample.json +11 -0
- package/.agents/skills/backend-load-and-stress-patterns/SKILL.md +85 -0
- package/.agents/skills/backend-load-and-stress-patterns/examples/k6_load_test_sample.js +13 -0
- package/.agents/skills/backend-load-and-stress-patterns/references/k6_load_template.js +82 -0
- package/.agents/skills/bats-testing-patterns/SKILL.md +100 -0
- package/.agents/skills/bats-testing-patterns/examples/cli_runner_test.bats +6 -0
- package/.agents/skills/bats-testing-patterns/resources/implementation-playbook.md +614 -0
- package/.agents/skills/clean-pom-crafter/SKILL.md +110 -0
- package/.agents/skills/clean-pom-crafter/examples/standard_test_case.groovy +28 -0
- package/.agents/skills/clean-pom-crafter/references/pom_patterns.groovy +138 -0
- package/.agents/skills/code-refactoring-refactor-clean/SKILL.md +64 -0
- package/.agents/skills/code-refactoring-refactor-clean/examples/refactored_page_sample.groovy +9 -0
- package/.agents/skills/code-refactoring-refactor-clean/examples/refactored_playwright_pom.ts +52 -0
- package/.agents/skills/code-refactoring-refactor-clean/resources/implementation-playbook.md +881 -0
- package/.agents/skills/consumer-driven-contract-testing/SKILL.md +147 -0
- package/.agents/skills/consumer-driven-contract-testing/examples/order_service_pact.json +45 -0
- package/.agents/skills/db-state-verifier-and-seeder/SKILL.md +123 -0
- package/.agents/skills/db-state-verifier-and-seeder/examples/db_fixture_seed.json +12 -0
- package/.agents/skills/e2e-testing-patterns/SKILL.md +103 -0
- package/.agents/skills/e2e-testing-patterns/examples/playwright_sharded_config.ts +12 -0
- package/.agents/skills/e2e-testing-patterns/resources/implementation-playbook.md +522 -0
- package/.agents/skills/event-stream-qa-orchestrator/SKILL.md +79 -0
- package/.agents/skills/event-stream-qa-orchestrator/examples/timeline_sample.jsonl +2 -0
- package/.agents/skills/failure-autopsy-and-healing/SKILL.md +66 -0
- package/.agents/skills/failure-autopsy-and-healing/examples/closed_loop_healing_walkthrough.md +48 -0
- package/.agents/skills/failure-autopsy-and-healing/examples/sample_junit_failure.xml +8 -0
- package/.agents/skills/failure-autopsy-and-healing/references/healing_matrix.md +64 -0
- package/.agents/skills/failure-autopsy-and-healing/references/qa_investigation_protocol.md +56 -0
- package/.agents/skills/failure-autopsy-and-healing/scripts/triage_failures.sh +83 -0
- package/.agents/skills/file-and-report-validator/SKILL.md +90 -0
- package/.agents/skills/file-and-report-validator/examples/sample_export_schema.json +14 -0
- package/.agents/skills/flaky-test-sentinel-and-quarantine/SKILL.md +114 -0
- package/.agents/skills/flaky-test-sentinel-and-quarantine/examples/quarantine_registry.json +11 -0
- package/.agents/skills/gherkin-to-suite/SKILL.md +103 -0
- package/.agents/skills/gherkin-to-suite/examples/checkout.feature +39 -0
- package/.agents/skills/gherkin-to-suite/examples/suite_report_sample.json +334 -0
- package/.agents/skills/github-actions-templates/SKILL.md +77 -0
- package/.agents/skills/github-actions-templates/examples/matrix_test_pipeline.yml +8 -0
- package/.agents/skills/graphify-impact-analyzer/SKILL.md +76 -0
- package/.agents/skills/graphify-impact-analyzer/examples/dependency_blast_radius.json +8 -0
- package/.agents/skills/katalon-cli-runner/SKILL.md +76 -0
- package/.agents/skills/katalon-cli-runner/examples/headless_kre_exec.sh +3 -0
- package/.agents/skills/katalon-cli-runner/references/groovy-patterns.md +209 -0
- package/.agents/skills/katalon-cli-runner/references/katalon-api.md +155 -0
- package/.agents/skills/katalon-cli-runner/references/runner_commands.md +67 -0
- package/.agents/skills/lam-script-generator/SKILL.md +123 -0
- package/.agents/skills/lam-script-generator/examples/user_story_sample.md +8 -0
- package/.agents/skills/lean-code-ladder/SKILL.md +94 -0
- package/.agents/skills/lean-code-ladder/examples/ladder_walkthrough.md +37 -0
- package/.agents/skills/lean-impact-scoreboard/SKILL.md +48 -0
- package/.agents/skills/lean-impact-scoreboard/examples/sample_benchmark_gain.md +20 -0
- package/.agents/skills/lean-impact-scoreboard/examples/sample_scoreboard.md +15 -0
- package/.agents/skills/meta-prompt-crafter/SKILL.md +107 -0
- package/.agents/skills/meta-prompt-crafter/examples/qa_prompt_template.md +35 -0
- package/.agents/skills/mipro-prompt-compiler/SKILL.md +59 -0
- package/.agents/skills/mipro-prompt-compiler/examples/compiled_module_sample.json +22 -0
- package/.agents/skills/mipro-prompt-compiler/examples/dspy_assertion_optimizer_case.md +46 -0
- package/.agents/skills/mobile-appium-som/SKILL.md +88 -0
- package/.agents/skills/mobile-appium-som/examples/BaseScreen.java +88 -0
- package/.agents/skills/mobile-appium-som/examples/LoginScreen.java +46 -0
- package/.agents/skills/mobile-appium-som/examples/TC_MobileLogin.java +43 -0
- package/.agents/skills/persistent-planning-files/SKILL.md +108 -0
- package/.agents/skills/persistent-planning-files/examples/task_plan_example.md +56 -0
- package/.agents/skills/playwright-live-interaction/SKILL.md +131 -0
- package/.agents/skills/playwright-live-interaction/examples/live_probe_script.js +5 -0
- package/.agents/skills/playwright-live-interaction/references/advanced_superpowers.md +160 -0
- package/.agents/skills/playwright-live-interaction/references/compact_accessibility_snapshots.md +75 -0
- package/.agents/skills/playwright-live-interaction/references/recipes.md +388 -0
- package/.agents/skills/playwright-live-interaction/references/swarm_orchestration.md +134 -0
- package/.agents/skills/playwright-webapp-testing/SKILL.md +93 -0
- package/.agents/skills/playwright-webapp-testing/examples/server_lifecycle_playwright.py +63 -0
- package/.agents/skills/qa-aci-interface/SKILL.md +67 -0
- package/.agents/skills/qa-aci-interface/examples/surgical_code_window_walkthrough.md +40 -0
- package/.agents/skills/qa-aci-interface/examples/surgical_edit_sample.json +12 -0
- package/.agents/skills/qa-memory-os/SKILL.md +80 -0
- package/.agents/skills/qa-memory-os/examples/archival_memory_sample.json +21 -0
- package/.agents/skills/rbt-manual-testing/SKILL.md +137 -0
- package/.agents/skills/rbt-manual-testing/examples/checkout_rbt_manual_suite.md +25 -0
- package/.agents/skills/rbt-manual-testing/references/field_validation_checklist.md +29 -0
- package/.agents/skills/repo-quality-audit/SKILL.md +68 -0
- package/.agents/skills/repo-quality-audit/examples/sample_audit_walkthrough.md +15 -0
- package/.agents/skills/repo-quality-audit/examples/sample_repo_audit.md +33 -0
- package/.agents/skills/review-spec/SKILL.md +60 -0
- package/.agents/skills/review-spec/examples/pocock_grilling_decision_rubric.md +40 -0
- package/.agents/skills/review-spec/examples/sample_spec_review.md +33 -0
- package/.agents/skills/security-dast-sentinel/SKILL.md +119 -0
- package/.agents/skills/security-dast-sentinel/examples/dast_scan_config.json +10 -0
- package/.agents/skills/security-dast-sentinel/references/AI-AND-LLM.md +113 -0
- package/.agents/skills/security-dast-sentinel/references/ATTACK-CLASSES.md +89 -0
- package/.agents/skills/security-dast-sentinel/references/dast_recipes.ts +33 -0
- package/.agents/skills/self-healing-locator/SKILL.md +86 -0
- package/.agents/skills/self-healing-locator/examples/aom_diff_sample.json +16 -0
- package/.agents/skills/senior-code-review/SKILL.md +108 -0
- package/.agents/skills/senior-code-review/examples/sample_review_walkthrough.md +29 -0
- package/.agents/skills/skillspector-security-guard/SKILL.md +57 -0
- package/.agents/skills/skillspector-security-guard/examples/audit_threat_vectors_report.json +35 -0
- package/.agents/skills/skillspector-security-guard/examples/safe_mcp_config.json +12 -0
- package/.agents/skills/surgical-coding-principles/SKILL.md +89 -0
- package/.agents/skills/surgical-coding-principles/examples/surgical_vs_scope_creep.md +46 -0
- package/.agents/skills/synthetic-test-data-generator/SKILL.md +135 -0
- package/.agents/skills/synthetic-test-data-generator/examples/idempotent_data_recipe.json +9 -0
- package/.agents/skills/systematic-debugging/SKILL.md +100 -0
- package/.agents/skills/systematic-debugging/examples/four_phase_case.md +44 -0
- package/.agents/skills/technical-debt-harvester/SKILL.md +70 -0
- package/.agents/skills/technical-debt-harvester/examples/sample_debt_ledger.md +25 -0
- package/.agents/skills/technical-debt-harvester/examples/sample_ledger_output.md +20 -0
- package/.agents/skills/test-driven-development/SKILL.md +114 -0
- package/.agents/skills/test-driven-development/examples/red_green_refactor_qa.md +78 -0
- package/.agents/skills/token-and-context-optimizer/SKILL.md +70 -0
- package/.agents/skills/token-and-context-optimizer/examples/distilled_log_sample.txt +3 -0
- package/.agents/skills/token-and-context-optimizer/references/context_engineering_guide.md +49 -0
- package/.agents/skills/tot-exploratory-testing/SKILL.md +59 -0
- package/.agents/skills/tot-exploratory-testing/examples/payment_gateway_tot_tree.json +62 -0
- package/.agents/skills/tot-exploratory-testing/examples/tot_graph_sample.json +35 -0
- package/.agents/skills/verification-before-completion/SKILL.md +100 -0
- package/.agents/skills/verification-before-completion/examples/evidence_log_example.md +46 -0
- package/.agents/skills/visual-regression-sentinel/SKILL.md +82 -0
- package/.agents/skills/visual-regression-sentinel/examples/visual_mask_rules.json +9 -0
- package/.agents/skills/wcag-audit-patterns/SKILL.md +77 -0
- package/.agents/skills/wcag-audit-patterns/examples/wcag_compliance_checklist.json +10 -0
- package/.agents/skills/wcag-audit-patterns/resources/implementation-playbook.md +541 -0
- package/.agents/skills/web-agent-gym-benchmarking/SKILL.md +62 -0
- package/.agents/skills/web-agent-gym-benchmarking/examples/benchmark_report_sample.json +22 -0
- package/.agents/skills/web-agent-gym-benchmarking/examples/enterprise_tasks_suite.json +38 -0
- package/.agents/skills/web-vitals-and-performance-profiler/SKILL.md +65 -0
- package/.agents/skills/web-vitals-and-performance-profiler/examples/cwv_budget_policy.json +6 -0
- package/.agents/skills/web-vitals-and-performance-profiler/examples/playwright_cwv_profiler_fixture.ts +118 -0
- package/.agents/templates/completion_report.md +57 -0
- package/.agents/workflows/analyze_requirement_document.md +18 -0
- package/.agents/workflows/export_testcases_excel.md +32 -0
- package/.agents/workflows/generate_combinatorial_test_data.md +28 -0
- package/.agents/workflows/generate_cross_module_test_plan.md +37 -0
- package/.agents/workflows/generate_manual_testcases_rbt.md +56 -0
- package/.agents/workflows/generate_requirements_from_website.md +25 -0
- package/.agents/workflows/generate_testcases_from_requirements.md +21 -0
- package/.agents/workflows/graphify.md +10 -0
- package/.agents/workflows/test-impact.md +15 -0
- package/.agents/workflows/verify.md +34 -0
- package/.cursor/rules/agents.mdc +16 -0
- package/.cursor/rules/language.mdc +7 -0
- package/.cursor/rules/synapse-qa.mdc +24 -0
- package/.cursorrules +27 -0
- package/.dockerignore +53 -0
- package/.pre-commit-hooks.yaml +14 -0
- package/.windsurfrules +26 -0
- package/AGENTS.md +86 -0
- package/CLAUDE.md +54 -0
- package/Dockerfile +81 -0
- package/LICENSE +52 -0
- package/NOTICE +264 -0
- package/README.en.md +171 -0
- package/README.md +170 -2
- package/action.yml +51 -0
- package/agentskills.json +16 -0
- package/bin/agent-qa.js +138 -0
- package/docker-compose.yml +74 -0
- package/docs/ARCHITECTURE.en.md +198 -0
- package/docs/ARCHITECTURE.md +199 -0
- package/docs/CI_CD_INTEGRATION.en.md +170 -0
- package/docs/CI_CD_INTEGRATION.md +170 -0
- package/docs/CLI_REFERENCE.en.md +174 -0
- package/docs/CLI_REFERENCE.md +176 -0
- package/docs/CONTRIBUTING.en.md +49 -0
- package/docs/CONTRIBUTING.md +49 -0
- package/docs/PERFORMANCE_AUDIT_REPORT.md +783 -0
- package/docs/PLUGIN_DEVELOPMENT_GUIDE.md +127 -0
- package/docs/QUALITY_GATES.en.md +118 -0
- package/docs/QUALITY_GATES.md +118 -0
- package/docs/TOKEN_QUOTA_PLAYBOOK.md +41 -0
- package/docs/TOOL_CATALOG.md +129 -0
- package/docs/adopted-ecosystem-tools.md +96 -0
- package/docs/research/EXTERNAL_AGENT_SKILLS_SURVEY.md +1062 -0
- package/docs/research/agent_skill_training_analysis.md +1358 -0
- package/docs/schemas/synapse.config.schema.json +86 -0
- package/package.json +94 -4
- package/plugin.json +31 -0
- package/scripts/generate_skill_examples.py +244 -0
- package/scripts/install.ps1 +112 -0
- package/scripts/install_global_plugin.ps1 +94 -0
- package/scripts/install_global_plugin.sh +49 -0
- package/scripts/lint_skills.ps1 +57 -0
- package/scripts/package_dist.py +337 -0
- package/scripts/setup.sh +59 -0
- package/scripts/update_hub.ps1 +19 -0
- package/scripts/update_hub.sh +15 -0
- package/skills_manifest.json +854 -0
- package/synapse.config.json +31 -0
- package/templates/PROJECT_AI_GUIDE_TEMPLATE.md +111 -0
- package/templates/PROJECT_STATE_TEMPLATE.md +20 -0
- package/templates/ai_bridges/CLAUDE.md +54 -0
- package/templates/ai_bridges/copilot-instructions.md +20 -0
- package/templates/ai_bridges/cursor_synapse_qa.mdc +24 -0
- package/templates/ai_bridges/windsurfrules +26 -0
- package/templates/ci/github-actions-synapse.yml +95 -0
- package/templates/ci/gitlab-ci-synapse.yml +16 -0
- package/templates/ui/index.html +1069 -0
- package/templates/welcome.html.tmpl +2074 -0
- package/tools/.infer_baseline.json +30 -0
- package/tools/TOOLS_RUNBOOK.md +1553 -0
- package/tools/TOOL_CATALOG.json +1769 -0
- package/tools/__init__.py +43 -0
- package/tools/_openapi_parser.py +158 -0
- package/tools/agent_canary.py +525 -0
- package/tools/agentless_patcher.py +417 -0
- package/tools/analyze_project.py +262 -0
- package/tools/api_drift_sentinel.py +208 -0
- package/tools/api_fuzzer.py +762 -0
- package/tools/author_integrity.py +190 -0
- package/tools/auto_heal.py +271 -0
- package/tools/auto_heal_reflexion.py +532 -0
- package/tools/autogen_qa_broker.py +844 -0
- package/tools/benchmark_swarm_context.py +394 -0
- package/tools/browser_helpers.js +746 -0
- package/tools/browsergym_eval.py +236 -0
- package/tools/bug_reporter.py +252 -0
- package/tools/bump_version.py +423 -0
- package/tools/cache_resolver.py +1214 -0
- package/tools/check_env.py +426 -0
- package/tools/check_version_sync.py +256 -0
- package/tools/ci_healing_hook.py +126 -0
- package/tools/cli.py +1598 -0
- package/tools/config_decoupler.py +253 -0
- package/tools/contract_validator.py +141 -0
- package/tools/core/__init__.py +70 -0
- package/tools/core/adapters.py +431 -0
- package/tools/core/circuit_breaker.py +263 -0
- package/tools/core/cli_runtime.py +66 -0
- package/tools/core/file_lock.py +159 -0
- package/tools/core/i18n.py +394 -0
- package/tools/core/memory_bus.py +905 -0
- package/tools/core/process_supervisor.py +332 -0
- package/tools/core/telemetry.py +329 -0
- package/tools/count_tokens.py +1267 -0
- package/tools/create_mock_docx.py +104 -0
- package/tools/dashboard_generator.py +2403 -0
- package/tools/db_sandbox.py +675 -0
- package/tools/debt_harvester.py +237 -0
- package/tools/distill_log.py +161 -0
- package/tools/dspy_qa_signatures.py +356 -0
- package/tools/e2e_flow_prober.py +132 -0
- package/tools/export_postman_collection.py +945 -0
- package/tools/flaky_detector.py +389 -0
- package/tools/fsm_enforcer.py +450 -0
- package/tools/fsm_middleware.py +401 -0
- package/tools/fuzz_payloads.py +197 -0
- package/tools/generate_allure_report.py +88 -0
- package/tools/generate_api_matrix.py +193 -0
- package/tools/generate_jmx_plan.py +1322 -0
- package/tools/generate_sbom.py +252 -0
- package/tools/generate_tc_from_story.py +203 -0
- package/tools/generate_test_reports.py +133 -0
- package/tools/generate_tool_catalog.py +482 -0
- package/tools/gherkin_suite.py +758 -0
- package/tools/git_pre_commit_guard.py +298 -0
- package/tools/goldfish_review.py +366 -0
- package/tools/heal/__init__.py +28 -0
- package/tools/heal_pr_automator.py +220 -0
- package/tools/heuristic_locator_matcher.py +351 -0
- package/tools/hub_publisher.py +623 -0
- package/tools/humanize_linter.py +438 -0
- package/tools/infer_linter.py +977 -0
- package/tools/init_config.py +306 -0
- package/tools/interview_story.py +116 -0
- package/tools/jira_sync.py +566 -0
- package/tools/jtl_analyzer.py +474 -0
- package/tools/lint/__init__.py +30 -0
- package/tools/lint_ai_docs.py +374 -0
- package/tools/lookup_tc.py +165 -0
- package/tools/lookup_xpath.py +167 -0
- package/tools/matrix_sharder.py +148 -0
- package/tools/mcp/__init__.py +18 -0
- package/tools/mcp_docx_server.ps1 +13 -0
- package/tools/mcp_docx_server.py +851 -0
- package/tools/mcp_excel_server.ps1 +13 -0
- package/tools/mcp_excel_server.py +441 -0
- package/tools/mcp_server.py +725 -0
- package/tools/md_to_xlsx.py +327 -0
- package/tools/micro_mutator.py +887 -0
- package/tools/mipro_assertion_tuner.py +210 -0
- package/tools/network_mock_shield.py +311 -0
- package/tools/newman_analyzer.py +384 -0
- package/tools/omni_emitter.py +579 -0
- package/tools/omni_parser.py +450 -0
- package/tools/omni_transpiler.py +168 -0
- package/tools/openxml_guard.py +438 -0
- package/tools/output_formatter.py +182 -0
- package/tools/package_release.py +325 -0
- package/tools/perf/__init__.py +24 -0
- package/tools/pinpoint_failure.py +190 -0
- package/tools/project_state.py +171 -0
- package/tools/qa_event_stream.py +358 -0
- package/tools/repo_map.py +346 -0
- package/tools/report/__init__.py +32 -0
- package/tools/reversible_sandbox.py +344 -0
- package/tools/safety_firewall.py +437 -0
- package/tools/security_coverage_ledger.py +538 -0
- package/tools/security_scanner.py +229 -0
- package/tools/senior_code_review.py +393 -0
- package/tools/setup_project.py +770 -0
- package/tools/skill_collision_guard.py +304 -0
- package/tools/skill_profiles.py +217 -0
- package/tools/skill_vault.py +481 -0
- package/tools/skillspector.py +1278 -0
- package/tools/smart_visual_masker.py +132 -0
- package/tools/spec_drift_sentinel.py +438 -0
- package/tools/swe_qa_aci.py +369 -0
- package/tools/synapse_observer.py +485 -0
- package/tools/synapse_qa_bench.py +190 -0
- package/tools/sync_agent_rules.py +274 -0
- package/tools/telemetry_correlator.py +397 -0
- package/tools/template_excel_exporter.py +514 -0
- package/tools/templates/jmeter-distributed/README.md +54 -0
- package/tools/templates/jmeter-distributed/docker-compose.yml +83 -0
- package/tools/test_impact.py +419 -0
- package/tools/test_memory_os.py +462 -0
- package/tools/textgrad_mutation_optimizer.py +237 -0
- package/tools/tms_sync_bridge.py +834 -0
- package/tools/tot_exploratory_tester.py +239 -0
- package/tools/trace_data_flow.py +240 -0
- package/tools/traffic_session_converter.py +256 -0
- package/tools/trend_analytics.py +314 -0
- package/tools/ui_server.py +401 -0
- package/tools/universal_ir.py +488 -0
- package/tools/update_sentinel.py +383 -0
- package/tools/validate_groovy_scripts.py +173 -0
- package/tools/verify_all.py +1271 -0
- package/tools/visual_diff_canvas.py +143 -0
- package/tools/visual_som_helper.py +550 -0
- package/tools/watch_mode.py +308 -0
- package/tools/wcag_audit.py +239 -0
- package/tools/welcome_page.py +290 -0
|
@@ -0,0 +1,431 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
# SPDX-FileCopyrightText: Copyright (c) 2026 Thế Vị (@TeeVee98). All rights reserved.
|
|
3
|
+
# SPDX-License-Identifier: MIT
|
|
4
|
+
# Project: Synapse-Hub (https://github.com/TeeVee98/Synapse-Hub)
|
|
5
|
+
|
|
6
|
+
"""
|
|
7
|
+
tools/core/adapters.py — Unified Memory Bus Bridges & Adapters
|
|
8
|
+
--------------------------------------------------------------
|
|
9
|
+
Provides bidirectional adapter bridges connecting specialized QA operating tools
|
|
10
|
+
(autogen_qa_broker, qa_event_stream, test_memory_os) directly to the unified SQLite
|
|
11
|
+
WAL-backed engine in tools/core/memory_bus.py:
|
|
12
|
+
|
|
13
|
+
1. BrokerMemoryBusAdapter:
|
|
14
|
+
Adapts ActorQaBroker messaging & pub/sub to Partition 2 (actor_mailbox) & Partition 1 (blocks).
|
|
15
|
+
2. EventStreamMemoryBusAdapter:
|
|
16
|
+
Adapts QaEventStream timeline logging, SHA-256 hash chaining & checkpoints to Partition 5 (event_stream).
|
|
17
|
+
3. TestMemoryOSAdapter:
|
|
18
|
+
Adapts 3-tier TestMemoryOS (Core, Recall, Archival) to Partition 1 (blocks) & Partition 5 (event_stream).
|
|
19
|
+
"""
|
|
20
|
+
|
|
21
|
+
import os
|
|
22
|
+
import sys
|
|
23
|
+
import json
|
|
24
|
+
import uuid
|
|
25
|
+
from datetime import datetime, timezone
|
|
26
|
+
from typing import Dict, Any, List, Optional
|
|
27
|
+
|
|
28
|
+
SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
|
|
29
|
+
TOOLS_DIR = os.path.dirname(SCRIPT_DIR)
|
|
30
|
+
for p in (SCRIPT_DIR, TOOLS_DIR):
|
|
31
|
+
if p not in sys.path:
|
|
32
|
+
sys.path.insert(0, p)
|
|
33
|
+
|
|
34
|
+
from memory_bus import UnifiedMemoryBus, get_memory_bus
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
class BrokerMemoryBusAdapter:
|
|
38
|
+
"""Adapts ActorQaBroker interface to UnifiedMemoryBus (Partition 2 & 1)."""
|
|
39
|
+
|
|
40
|
+
def __init__(self, bus: Optional[UnifiedMemoryBus] = None):
|
|
41
|
+
self.bus = bus or get_memory_bus()
|
|
42
|
+
|
|
43
|
+
def send_message(
|
|
44
|
+
self,
|
|
45
|
+
from_actor: str,
|
|
46
|
+
to_actor: str,
|
|
47
|
+
topic: str,
|
|
48
|
+
payload: Any,
|
|
49
|
+
session_id: Optional[str] = None
|
|
50
|
+
) -> Dict[str, Any]:
|
|
51
|
+
"""Routes message directly to UnifiedMemoryBus mailbox partition."""
|
|
52
|
+
msg_id = self.bus.send_message(
|
|
53
|
+
sender=from_actor,
|
|
54
|
+
recipient=to_actor,
|
|
55
|
+
stage=topic,
|
|
56
|
+
payload=payload,
|
|
57
|
+
session_id=session_id
|
|
58
|
+
)
|
|
59
|
+
return {
|
|
60
|
+
"status": "PASS",
|
|
61
|
+
"message_id": msg_id,
|
|
62
|
+
"from": from_actor,
|
|
63
|
+
"to": to_actor,
|
|
64
|
+
"topic": topic,
|
|
65
|
+
"timestamp": datetime.now(timezone.utc).isoformat()
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
def fetch_messages(
|
|
69
|
+
self,
|
|
70
|
+
actor: str,
|
|
71
|
+
topic: Optional[str] = None,
|
|
72
|
+
mark_read: bool = True,
|
|
73
|
+
session_id: Optional[str] = None
|
|
74
|
+
) -> List[Dict[str, Any]]:
|
|
75
|
+
"""Fetches messages for recipient actor from UnifiedMemoryBus mailbox."""
|
|
76
|
+
raw_msgs = self.bus.receive_messages(
|
|
77
|
+
recipient=actor,
|
|
78
|
+
stage=topic,
|
|
79
|
+
mark_read=mark_read,
|
|
80
|
+
session_id=session_id
|
|
81
|
+
)
|
|
82
|
+
formatted = []
|
|
83
|
+
for m in raw_msgs:
|
|
84
|
+
formatted.append({
|
|
85
|
+
"id": m["message_id"],
|
|
86
|
+
"from_actor": m["sender"],
|
|
87
|
+
"to_actor": m["recipient"],
|
|
88
|
+
"topic": m["stage"],
|
|
89
|
+
"payload": m["payload"],
|
|
90
|
+
"timestamp": m["created_at"],
|
|
91
|
+
"read": True if mark_read else (m["status"] == "PROCESSED")
|
|
92
|
+
})
|
|
93
|
+
return formatted
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
def subscribe(self, actor: str, event_topic: str, handler: Optional[str] = None) -> Dict[str, Any]:
|
|
97
|
+
"""Registers a pub/sub topic subscription using UnifiedMemoryBus memory_blocks."""
|
|
98
|
+
now_iso = datetime.now(timezone.utc).isoformat()
|
|
99
|
+
content = {
|
|
100
|
+
"actor": actor,
|
|
101
|
+
"event_topic": event_topic,
|
|
102
|
+
"handler": handler or "default_handler",
|
|
103
|
+
"subscribed_at": now_iso
|
|
104
|
+
}
|
|
105
|
+
self.bus.set_block(
|
|
106
|
+
label=f"{event_topic}:{actor}",
|
|
107
|
+
content=content,
|
|
108
|
+
scope="broker_subscriptions"
|
|
109
|
+
)
|
|
110
|
+
all_subs = self.bus.list_blocks(scope="broker_subscriptions")
|
|
111
|
+
total_topic_subs = sum(
|
|
112
|
+
1 for b in all_subs if b.get("content", {}).get("event_topic") == event_topic
|
|
113
|
+
)
|
|
114
|
+
return {
|
|
115
|
+
"status": "PASS",
|
|
116
|
+
"actor": actor,
|
|
117
|
+
"topic": event_topic,
|
|
118
|
+
"total_subscribers": total_topic_subs
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
def publish(self, event_topic: str, payload: Any, sender: str = "system") -> Dict[str, Any]:
|
|
122
|
+
"""Dispatches an event payload to all subscribed actors via UnifiedMemoryBus."""
|
|
123
|
+
all_subs = self.bus.list_blocks(scope="broker_subscriptions")
|
|
124
|
+
target_actors = [
|
|
125
|
+
b["content"]["actor"]
|
|
126
|
+
for b in all_subs
|
|
127
|
+
if isinstance(b.get("content"), dict) and b["content"].get("event_topic") == event_topic
|
|
128
|
+
]
|
|
129
|
+
delivered_count = 0
|
|
130
|
+
for target in target_actors:
|
|
131
|
+
self.send_message(
|
|
132
|
+
from_actor=sender,
|
|
133
|
+
to_actor=target,
|
|
134
|
+
topic=event_topic,
|
|
135
|
+
payload=payload
|
|
136
|
+
)
|
|
137
|
+
delivered_count += 1
|
|
138
|
+
return {
|
|
139
|
+
"status": "PASS",
|
|
140
|
+
"topic": event_topic,
|
|
141
|
+
"delivered_count": delivered_count,
|
|
142
|
+
"target_actors": target_actors
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
def check_health(self) -> Dict[str, Any]:
|
|
146
|
+
"""Returns health status of the broker backed by UnifiedMemoryBus."""
|
|
147
|
+
stats = self.bus.get_stats()
|
|
148
|
+
return {
|
|
149
|
+
"status": "PASS",
|
|
150
|
+
"backend": "UnifiedMemoryBus",
|
|
151
|
+
"mailbox_count": stats.get("actor_mailbox", 0),
|
|
152
|
+
"healthy": True
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
def get_state(self) -> Dict[str, Any]:
|
|
156
|
+
"""Reconstructs state dictionary from UnifiedMemoryBus mailbox and subscriptions."""
|
|
157
|
+
mailboxes: Dict[str, List[Dict[str, Any]]] = {}
|
|
158
|
+
subscriptions: Dict[str, List[Dict[str, Any]]] = {}
|
|
159
|
+
metadata: Dict[str, Any] = {}
|
|
160
|
+
|
|
161
|
+
cur = self.bus._conn.cursor()
|
|
162
|
+
with self.bus._lock:
|
|
163
|
+
cur.execute("SELECT * FROM actor_mailbox ORDER BY created_at ASC")
|
|
164
|
+
for row in cur.fetchall():
|
|
165
|
+
to_act = row["recipient"]
|
|
166
|
+
if to_act not in mailboxes:
|
|
167
|
+
mailboxes[to_act] = []
|
|
168
|
+
try:
|
|
169
|
+
payload = json.loads(row["payload"])
|
|
170
|
+
except Exception:
|
|
171
|
+
payload = row["payload"]
|
|
172
|
+
mailboxes[to_act].append({
|
|
173
|
+
"id": row["message_id"],
|
|
174
|
+
"from_actor": row["sender"],
|
|
175
|
+
"to_actor": row["recipient"],
|
|
176
|
+
"topic": row["stage"],
|
|
177
|
+
"payload": payload,
|
|
178
|
+
"timestamp": row["created_at"],
|
|
179
|
+
"read": (row["status"] == "PROCESSED")
|
|
180
|
+
})
|
|
181
|
+
|
|
182
|
+
all_subs = self.bus.list_blocks(scope="broker_subscriptions")
|
|
183
|
+
for b in all_subs:
|
|
184
|
+
content = b.get("content", {})
|
|
185
|
+
if isinstance(content, dict):
|
|
186
|
+
ev_topic = content.get("event_topic", "")
|
|
187
|
+
if ev_topic not in subscriptions:
|
|
188
|
+
subscriptions[ev_topic] = []
|
|
189
|
+
subscriptions[ev_topic].append({
|
|
190
|
+
"actor": content.get("actor", ""),
|
|
191
|
+
"handler": content.get("handler", "default_handler"),
|
|
192
|
+
"subscribed_at": content.get("subscribed_at", b.get("updated_at", ""))
|
|
193
|
+
})
|
|
194
|
+
|
|
195
|
+
return {
|
|
196
|
+
"mailboxes": mailboxes,
|
|
197
|
+
"subscriptions": subscriptions,
|
|
198
|
+
"metadata": metadata
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
|
|
202
|
+
class EventStreamMemoryBusAdapter:
|
|
203
|
+
"""Adapts QaEventStream interface to UnifiedMemoryBus (Partition 5: event_stream)."""
|
|
204
|
+
|
|
205
|
+
def __init__(self, bus: Optional[UnifiedMemoryBus] = None, session_id: Optional[str] = None):
|
|
206
|
+
self.bus = bus or get_memory_bus()
|
|
207
|
+
self.default_session_id = session_id or f"sess_{uuid.uuid4().hex[:8]}"
|
|
208
|
+
|
|
209
|
+
def _resolve_session(self, stream_file_or_session: str) -> str:
|
|
210
|
+
base = os.path.basename(stream_file_or_session)
|
|
211
|
+
name, _ = os.path.splitext(base)
|
|
212
|
+
return name if name else self.default_session_id
|
|
213
|
+
|
|
214
|
+
def init_stream(self, session_id: str, out_file: Optional[str] = None) -> Dict[str, Any]:
|
|
215
|
+
"""Initializes a new event stream in the UnifiedMemoryBus."""
|
|
216
|
+
rec = self.bus.record_event(
|
|
217
|
+
session_id=session_id,
|
|
218
|
+
event_type="STREAM_INIT",
|
|
219
|
+
actor="system",
|
|
220
|
+
stage="INIT",
|
|
221
|
+
payload={"session_id": session_id, "initialized_at": datetime.now(timezone.utc).isoformat()}
|
|
222
|
+
)
|
|
223
|
+
return {
|
|
224
|
+
"status": "PASS",
|
|
225
|
+
"session_id": session_id,
|
|
226
|
+
"genesis_hash": rec["event_hash"],
|
|
227
|
+
"event_id": rec["event_id"],
|
|
228
|
+
"backend": "UnifiedMemoryBus"
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
def record_event(
|
|
232
|
+
self,
|
|
233
|
+
stream_file: str,
|
|
234
|
+
event_type: str,
|
|
235
|
+
actor: str,
|
|
236
|
+
payload: Any,
|
|
237
|
+
checkpoint_id: Optional[str] = None
|
|
238
|
+
) -> Dict[str, Any]:
|
|
239
|
+
"""Appends an event to the session stream in UnifiedMemoryBus."""
|
|
240
|
+
session_id = self._resolve_session(stream_file)
|
|
241
|
+
rec = self.bus.record_event(
|
|
242
|
+
session_id=session_id,
|
|
243
|
+
event_type=event_type,
|
|
244
|
+
actor=actor,
|
|
245
|
+
stage="STREAM",
|
|
246
|
+
payload=payload,
|
|
247
|
+
checkpoint_name=checkpoint_id
|
|
248
|
+
)
|
|
249
|
+
return {
|
|
250
|
+
"status": "PASS",
|
|
251
|
+
"session_id": session_id,
|
|
252
|
+
"event_type": event_type,
|
|
253
|
+
"event_hash": rec["event_hash"],
|
|
254
|
+
"sequence": rec["sequence"],
|
|
255
|
+
"checkpoint_name": checkpoint_id
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
def verify_stream(self, stream_file: str) -> Dict[str, Any]:
|
|
259
|
+
"""Verifies cryptographic hash chain integrity in UnifiedMemoryBus."""
|
|
260
|
+
session_id = self._resolve_session(stream_file)
|
|
261
|
+
is_valid, err = self.bus.verify_stream_integrity(session_id)
|
|
262
|
+
events = self.bus.get_events(session_id)
|
|
263
|
+
if not is_valid:
|
|
264
|
+
return {
|
|
265
|
+
"status": "FAIL",
|
|
266
|
+
"valid": False,
|
|
267
|
+
"session_id": session_id,
|
|
268
|
+
"error": err
|
|
269
|
+
}
|
|
270
|
+
return {
|
|
271
|
+
"status": "PASS",
|
|
272
|
+
"valid": True,
|
|
273
|
+
"session_id": session_id,
|
|
274
|
+
"events_verified": len(events),
|
|
275
|
+
"last_hash": events[-1]["event_hash"] if events else None
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
def rollback(self, stream_file: str, to_checkpoint: str) -> Dict[str, Any]:
|
|
279
|
+
"""Rolls back the session stream to the named checkpoint."""
|
|
280
|
+
session_id = self._resolve_session(stream_file)
|
|
281
|
+
rec = self.bus.rollback_to_checkpoint(session_id, to_checkpoint)
|
|
282
|
+
return {
|
|
283
|
+
"status": "PASS",
|
|
284
|
+
"session_id": session_id,
|
|
285
|
+
"rolled_back_to": to_checkpoint,
|
|
286
|
+
"rollback_event": rec
|
|
287
|
+
}
|
|
288
|
+
|
|
289
|
+
def replay_stream(self, stream_file: str, from_index: int = 0) -> List[Dict[str, Any]]:
|
|
290
|
+
"""Replays events from sequence index."""
|
|
291
|
+
session_id = self._resolve_session(stream_file)
|
|
292
|
+
return self.bus.get_events(session_id, since_sequence=from_index)
|
|
293
|
+
|
|
294
|
+
|
|
295
|
+
class TestMemoryOSAdapter:
|
|
296
|
+
"""Adapts TestMemoryOS interface to UnifiedMemoryBus (Partition 1: blocks & Partition 5: event_stream)."""
|
|
297
|
+
__test__ = False
|
|
298
|
+
|
|
299
|
+
def __init__(self, bus: Optional[UnifiedMemoryBus] = None):
|
|
300
|
+
|
|
301
|
+
self.bus = bus or get_memory_bus()
|
|
302
|
+
|
|
303
|
+
def update_core(self, block_key: str, data: Any) -> Dict[str, Any]:
|
|
304
|
+
"""Stores key-value environment state into memory_blocks partition."""
|
|
305
|
+
now_iso = datetime.now(timezone.utc).isoformat()
|
|
306
|
+
res = self.bus.set_block(
|
|
307
|
+
label=block_key,
|
|
308
|
+
content=data,
|
|
309
|
+
scope="core_memory"
|
|
310
|
+
)
|
|
311
|
+
return {
|
|
312
|
+
"status": "PASS",
|
|
313
|
+
"block_key": block_key,
|
|
314
|
+
"updated_at": now_iso
|
|
315
|
+
}
|
|
316
|
+
|
|
317
|
+
def get_core(self, block_key: str) -> Optional[Dict[str, Any]]:
|
|
318
|
+
"""Retrieves core memory block."""
|
|
319
|
+
block = self.bus.get_block(label=block_key, scope="core_memory")
|
|
320
|
+
if not block:
|
|
321
|
+
return None
|
|
322
|
+
return {
|
|
323
|
+
"block_key": block["label"],
|
|
324
|
+
"data": block["content"],
|
|
325
|
+
"updated_at": block["updated_at"]
|
|
326
|
+
}
|
|
327
|
+
|
|
328
|
+
def record_recall_step(
|
|
329
|
+
self,
|
|
330
|
+
session_id: str,
|
|
331
|
+
event_type: str,
|
|
332
|
+
actor: str,
|
|
333
|
+
payload: Any
|
|
334
|
+
) -> Dict[str, Any]:
|
|
335
|
+
"""Records an execution step into event_stream partition."""
|
|
336
|
+
rec = self.bus.record_event(
|
|
337
|
+
session_id=session_id,
|
|
338
|
+
event_type=event_type,
|
|
339
|
+
actor=actor,
|
|
340
|
+
stage="RECALL",
|
|
341
|
+
payload=payload
|
|
342
|
+
)
|
|
343
|
+
return {
|
|
344
|
+
"status": "PASS",
|
|
345
|
+
"session_id": session_id,
|
|
346
|
+
"sequence": rec["sequence"],
|
|
347
|
+
"event_id": rec["event_id"]
|
|
348
|
+
}
|
|
349
|
+
|
|
350
|
+
def get_recall_history(self, session_id: str, limit: int = 50) -> List[Dict[str, Any]]:
|
|
351
|
+
"""Retrieves recent execution steps from event_stream."""
|
|
352
|
+
events = self.bus.get_events(session_id)
|
|
353
|
+
filtered = [
|
|
354
|
+
{
|
|
355
|
+
"id": e["sequence"],
|
|
356
|
+
"session_id": e["session_id"],
|
|
357
|
+
"event_type": e["event_type"],
|
|
358
|
+
"actor": e["actor"],
|
|
359
|
+
"payload": e["payload"],
|
|
360
|
+
"timestamp": e["timestamp"]
|
|
361
|
+
}
|
|
362
|
+
for e in events if e.get("stage") == "RECALL" or e.get("event_type") != "STREAM_INIT"
|
|
363
|
+
]
|
|
364
|
+
return filtered[-limit:]
|
|
365
|
+
|
|
366
|
+
def archival_insert(self, key: str, payload: Any, aut_version: str = "v1.0") -> Dict[str, Any]:
|
|
367
|
+
"""Inserts an archival record scoped by AUT release version."""
|
|
368
|
+
unique_label = f"{aut_version}:{key}:{uuid.uuid4().hex[:6]}"
|
|
369
|
+
self.bus.set_block(
|
|
370
|
+
label=unique_label,
|
|
371
|
+
content=payload,
|
|
372
|
+
scope=f"archival_{aut_version}",
|
|
373
|
+
tags=key
|
|
374
|
+
)
|
|
375
|
+
return {
|
|
376
|
+
"status": "PASS",
|
|
377
|
+
"key": key,
|
|
378
|
+
"aut_version": aut_version,
|
|
379
|
+
"label": unique_label
|
|
380
|
+
}
|
|
381
|
+
|
|
382
|
+
def archival_search(
|
|
383
|
+
self,
|
|
384
|
+
query: str,
|
|
385
|
+
aut_version: Optional[str] = None,
|
|
386
|
+
limit: int = 10
|
|
387
|
+
) -> List[Dict[str, Any]]:
|
|
388
|
+
"""Searches archival records matching query and optional aut_version."""
|
|
389
|
+
scope = f"archival_{aut_version}" if aut_version else None
|
|
390
|
+
blocks = self.bus.list_blocks(scope=scope)
|
|
391
|
+
matches = []
|
|
392
|
+
q_lower = query.lower()
|
|
393
|
+
|
|
394
|
+
for b in blocks:
|
|
395
|
+
text_repr = f"{b['label']} {json.dumps(b['content'], ensure_ascii=False)}".lower()
|
|
396
|
+
if q_lower in text_repr:
|
|
397
|
+
matches.append({
|
|
398
|
+
"key": b["tags"] or b["label"],
|
|
399
|
+
"aut_version": aut_version or b["scope"].replace("archival_", ""),
|
|
400
|
+
"payload": b["content"],
|
|
401
|
+
"updated_at": b["updated_at"]
|
|
402
|
+
})
|
|
403
|
+
if len(matches) >= limit:
|
|
404
|
+
break
|
|
405
|
+
|
|
406
|
+
return matches
|
|
407
|
+
|
|
408
|
+
def list_core(self) -> List[Dict[str, Any]]:
|
|
409
|
+
"""Lists all core memory blocks from UnifiedMemoryBus."""
|
|
410
|
+
blocks = self.bus.list_blocks(scope="core_memory")
|
|
411
|
+
return [
|
|
412
|
+
{
|
|
413
|
+
"block_key": b["label"],
|
|
414
|
+
"data": b["content"],
|
|
415
|
+
"updated_at": b["updated_at"]
|
|
416
|
+
}
|
|
417
|
+
for b in blocks
|
|
418
|
+
]
|
|
419
|
+
|
|
420
|
+
def gc(self, scrub_secrets: bool = True, max_age_days: int = 30) -> Dict[str, Any]:
|
|
421
|
+
"""Executes garbage collection and returns bus status."""
|
|
422
|
+
stats = self.bus.get_stats()
|
|
423
|
+
return {
|
|
424
|
+
"status": "PASS",
|
|
425
|
+
"backend": "UnifiedMemoryBus",
|
|
426
|
+
"db_path": self.bus.db_path,
|
|
427
|
+
"blocks_count": stats.get("memory_blocks", 0),
|
|
428
|
+
"events_count": stats.get("event_stream", 0),
|
|
429
|
+
"secrets_scrubbed": 0
|
|
430
|
+
}
|
|
431
|
+
|
|
@@ -0,0 +1,263 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
# SPDX-FileCopyrightText: Copyright (c) 2026 Thế Vị (@TeeVee98). All rights reserved.
|
|
3
|
+
# SPDX-License-Identifier: MIT
|
|
4
|
+
# Project: Synapse-Hub (https://github.com/TeeVee98/Synapse-Hub)
|
|
5
|
+
|
|
6
|
+
"""
|
|
7
|
+
Synapse Hub — In-Flight Token Circuit Breaker & Model Cascade Engine
|
|
8
|
+
-------------------------------------------------------------------
|
|
9
|
+
Prevents runaway token spend, recursive agent loops, and cascading HTTP 429
|
|
10
|
+
rate limit lockouts across multi-agent executions.
|
|
11
|
+
|
|
12
|
+
Capabilities:
|
|
13
|
+
1. Streaming Token Budget Sentinel:
|
|
14
|
+
- Enforces hard task-level and session-level token spend boundaries.
|
|
15
|
+
2. Rate Limit & 429 Interceptor:
|
|
16
|
+
- Automatically monitors HTTP 429 quota exhaustion events.
|
|
17
|
+
3. Dynamic Fallback Model Cascade:
|
|
18
|
+
- Cascades seamlessly across model tiers upon quota trip:
|
|
19
|
+
Tier 1 (Claude 3.7 Sonnet / Gemini Pro) -> Tier 2 (Gemini Flash) -> Local SLM.
|
|
20
|
+
4. Automatic Half-Open Recovery:
|
|
21
|
+
- Probes downstream provider readiness after cooldown window.
|
|
22
|
+
"""
|
|
23
|
+
|
|
24
|
+
import time
|
|
25
|
+
import threading
|
|
26
|
+
from enum import Enum
|
|
27
|
+
from typing import List, Dict, Any, Optional, Tuple
|
|
28
|
+
from contextlib import contextmanager
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
class CircuitBreakerState(str, Enum):
|
|
32
|
+
CLOSED = "CLOSED" # Normal operation, traffic allowed
|
|
33
|
+
OPEN = "OPEN" # Tripped, traffic blocked
|
|
34
|
+
HALF_OPEN = "HALF_OPEN" # Probing recovery after cooldown
|
|
35
|
+
FALLBACK = "FALLBACK" # Tripped primary, running on secondary fallback model
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
class CircuitBreakerError(Exception):
|
|
39
|
+
"""Base exception for circuit breaker faults."""
|
|
40
|
+
pass
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
class TokenBudgetExceededError(CircuitBreakerError):
|
|
44
|
+
"""Raised when token consumption exceeds maximum allowed budget."""
|
|
45
|
+
pass
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
class RateLimitExceededError(CircuitBreakerError):
|
|
49
|
+
"""Raised when HTTP 429 quota exhaustion locks the circuit breaker."""
|
|
50
|
+
pass
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
DEFAULT_FALLBACK_MODELS = [
|
|
54
|
+
"claude-sonnet",
|
|
55
|
+
"gemini-pro",
|
|
56
|
+
"gemini-flash",
|
|
57
|
+
]
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
class TokenCircuitBreaker:
|
|
61
|
+
"""Enterprise in-flight token circuit breaker and automated model cascade controller."""
|
|
62
|
+
|
|
63
|
+
def __init__(
|
|
64
|
+
self,
|
|
65
|
+
task_token_budget: int = 200_000,
|
|
66
|
+
session_token_budget: int = 1_000_000,
|
|
67
|
+
rate_limit_threshold: int = 2,
|
|
68
|
+
fallback_models: Optional[List[str]] = None,
|
|
69
|
+
cooldown_seconds: float = 30.0,
|
|
70
|
+
):
|
|
71
|
+
self.task_token_budget = task_token_budget
|
|
72
|
+
self.session_token_budget = session_token_budget
|
|
73
|
+
self.rate_limit_threshold = rate_limit_threshold
|
|
74
|
+
self.fallback_models = list(fallback_models or DEFAULT_FALLBACK_MODELS)
|
|
75
|
+
self.cooldown_seconds = cooldown_seconds
|
|
76
|
+
|
|
77
|
+
self.state = CircuitBreakerState.CLOSED
|
|
78
|
+
self.task_tokens = 0
|
|
79
|
+
self.session_tokens = 0
|
|
80
|
+
self.consecutive_429_count = 0
|
|
81
|
+
self.current_model_idx = 0
|
|
82
|
+
self.tripped_timestamp = 0.0
|
|
83
|
+
self.trip_reason = ""
|
|
84
|
+
self._lock = threading.Lock()
|
|
85
|
+
|
|
86
|
+
def get_active_model(self) -> str:
|
|
87
|
+
"""Returns the currently active model from the fallback cascade."""
|
|
88
|
+
with self._lock:
|
|
89
|
+
if self.current_model_idx < len(self.fallback_models):
|
|
90
|
+
return self.fallback_models[self.current_model_idx]
|
|
91
|
+
return self.fallback_models[-1]
|
|
92
|
+
|
|
93
|
+
def can_execute(self) -> Tuple[bool, str]:
|
|
94
|
+
"""
|
|
95
|
+
Evaluates whether an execution attempt is authorized.
|
|
96
|
+
Returns: (is_allowed, active_model_or_rejection_reason)
|
|
97
|
+
"""
|
|
98
|
+
with self._lock:
|
|
99
|
+
if self.state == CircuitBreakerState.OPEN:
|
|
100
|
+
# Check if cooldown has elapsed to attempt HALF_OPEN probe
|
|
101
|
+
elapsed = time.time() - self.tripped_timestamp
|
|
102
|
+
if elapsed >= self.cooldown_seconds:
|
|
103
|
+
self.state = CircuitBreakerState.HALF_OPEN
|
|
104
|
+
return True, self._current_model_unlocked()
|
|
105
|
+
return False, f"Circuit breaker is OPEN ({self.trip_reason}). Cooldown: {int(self.cooldown_seconds - elapsed)}s remaining."
|
|
106
|
+
|
|
107
|
+
return True, self._current_model_unlocked()
|
|
108
|
+
|
|
109
|
+
def _current_model_unlocked(self) -> str:
|
|
110
|
+
if self.current_model_idx < len(self.fallback_models):
|
|
111
|
+
return self.fallback_models[self.current_model_idx]
|
|
112
|
+
return self.fallback_models[-1]
|
|
113
|
+
|
|
114
|
+
def record_tokens(self, count: int, model: Optional[str] = None) -> int:
|
|
115
|
+
"""
|
|
116
|
+
Records consumed tokens and enforces budget limits.
|
|
117
|
+
Triggers model fallback cascade or trips to OPEN if budgets are violated.
|
|
118
|
+
"""
|
|
119
|
+
if count <= 0:
|
|
120
|
+
return self.task_tokens
|
|
121
|
+
|
|
122
|
+
with self._lock:
|
|
123
|
+
if self.state == CircuitBreakerState.OPEN:
|
|
124
|
+
raise CircuitBreakerError(f"Cannot record tokens: Circuit breaker is OPEN ({self.trip_reason})")
|
|
125
|
+
|
|
126
|
+
self.task_tokens += count
|
|
127
|
+
self.session_tokens += count
|
|
128
|
+
|
|
129
|
+
# Enforce hard session-level budget
|
|
130
|
+
if self.session_tokens > self.session_token_budget:
|
|
131
|
+
self._trip_unlocked(f"Session token budget exceeded: {self.session_tokens} > {self.session_token_budget}")
|
|
132
|
+
raise TokenBudgetExceededError(self.trip_reason)
|
|
133
|
+
|
|
134
|
+
# Enforce task-level budget
|
|
135
|
+
if self.task_tokens > self.task_token_budget:
|
|
136
|
+
# Attempt to cascade to fallback model if available
|
|
137
|
+
if self.current_model_idx < len(self.fallback_models) - 1:
|
|
138
|
+
prev_model = self.fallback_models[self.current_model_idx]
|
|
139
|
+
self.current_model_idx += 1
|
|
140
|
+
new_model = self.fallback_models[self.current_model_idx]
|
|
141
|
+
self.state = CircuitBreakerState.FALLBACK
|
|
142
|
+
# Grant additional headroom for fallback model
|
|
143
|
+
self.task_token_budget += count
|
|
144
|
+
return self.task_tokens
|
|
145
|
+
else:
|
|
146
|
+
self._trip_unlocked(f"Task token budget exhausted: {self.task_tokens} > {self.task_token_budget} with no remaining fallback models")
|
|
147
|
+
raise TokenBudgetExceededError(self.trip_reason)
|
|
148
|
+
|
|
149
|
+
if self.state == CircuitBreakerState.HALF_OPEN:
|
|
150
|
+
self.state = CircuitBreakerState.CLOSED
|
|
151
|
+
|
|
152
|
+
return self.task_tokens
|
|
153
|
+
|
|
154
|
+
def record_http_status(self, status_code: int, error_message: str = "") -> Optional[str]:
|
|
155
|
+
"""
|
|
156
|
+
Records HTTP response status code. If HTTP 429 (rate limit) is encountered,
|
|
157
|
+
triggers automated model cascade or trips breaker.
|
|
158
|
+
Returns the active fallback model name if cascade occurred, or None.
|
|
159
|
+
"""
|
|
160
|
+
with self._lock:
|
|
161
|
+
if status_code == 429:
|
|
162
|
+
if self.state == CircuitBreakerState.HALF_OPEN:
|
|
163
|
+
self._trip_unlocked(f"Probe request failed in HALF_OPEN with HTTP 429: {error_message}")
|
|
164
|
+
raise RateLimitExceededError(self.trip_reason)
|
|
165
|
+
|
|
166
|
+
self.consecutive_429_count += 1
|
|
167
|
+
if self.consecutive_429_count >= self.rate_limit_threshold:
|
|
168
|
+
if self.current_model_idx < len(self.fallback_models) - 1:
|
|
169
|
+
self.current_model_idx += 1
|
|
170
|
+
self.consecutive_429_count = 0
|
|
171
|
+
self.state = CircuitBreakerState.FALLBACK
|
|
172
|
+
return self._current_model_unlocked()
|
|
173
|
+
else:
|
|
174
|
+
self._trip_unlocked(f"Rate limit (HTTP 429) threshold exceeded ({self.consecutive_429_count}): {error_message}")
|
|
175
|
+
raise RateLimitExceededError(self.trip_reason)
|
|
176
|
+
elif 200 <= status_code < 300:
|
|
177
|
+
self.consecutive_429_count = 0
|
|
178
|
+
if self.state == CircuitBreakerState.HALF_OPEN:
|
|
179
|
+
self.state = CircuitBreakerState.CLOSED
|
|
180
|
+
elif status_code >= 500 and self.state == CircuitBreakerState.HALF_OPEN:
|
|
181
|
+
self._trip_unlocked(f"Probe request failed in HALF_OPEN with HTTP {status_code}: {error_message}")
|
|
182
|
+
raise RateLimitExceededError(self.trip_reason)
|
|
183
|
+
|
|
184
|
+
return None
|
|
185
|
+
|
|
186
|
+
def trip(self, reason: str):
|
|
187
|
+
"""Manually forces the circuit breaker into OPEN state."""
|
|
188
|
+
with self._lock:
|
|
189
|
+
self._trip_unlocked(reason)
|
|
190
|
+
|
|
191
|
+
def _trip_unlocked(self, reason: str):
|
|
192
|
+
self.state = CircuitBreakerState.OPEN
|
|
193
|
+
self.tripped_timestamp = time.time()
|
|
194
|
+
self.trip_reason = reason
|
|
195
|
+
|
|
196
|
+
def reset(self):
|
|
197
|
+
"""Resets all token counters, error state, and restores CLOSED state."""
|
|
198
|
+
with self._lock:
|
|
199
|
+
self.state = CircuitBreakerState.CLOSED
|
|
200
|
+
self.task_tokens = 0
|
|
201
|
+
self.session_tokens = 0
|
|
202
|
+
self.consecutive_429_count = 0
|
|
203
|
+
self.current_model_idx = 0
|
|
204
|
+
self.tripped_timestamp = 0.0
|
|
205
|
+
self.trip_reason = ""
|
|
206
|
+
|
|
207
|
+
def get_status(self) -> Dict[str, Any]:
|
|
208
|
+
"""Returns structured circuit breaker status."""
|
|
209
|
+
with self._lock:
|
|
210
|
+
return {
|
|
211
|
+
"state": self.state.value,
|
|
212
|
+
"active_model": self._current_model_unlocked(),
|
|
213
|
+
"active_model_index": self.current_model_idx,
|
|
214
|
+
"task_tokens": self.task_tokens,
|
|
215
|
+
"task_token_budget": self.task_token_budget,
|
|
216
|
+
"session_tokens": self.session_tokens,
|
|
217
|
+
"session_token_budget": self.session_token_budget,
|
|
218
|
+
"consecutive_429_count": self.consecutive_429_count,
|
|
219
|
+
"trip_reason": self.trip_reason,
|
|
220
|
+
"tripped_timestamp": self.tripped_timestamp,
|
|
221
|
+
}
|
|
222
|
+
|
|
223
|
+
@contextmanager
|
|
224
|
+
def protect_execution(self, estimated_tokens: int = 0):
|
|
225
|
+
"""
|
|
226
|
+
Context manager that gates execution through circuit breaker and records tokens.
|
|
227
|
+
"""
|
|
228
|
+
allowed, reason = self.can_execute()
|
|
229
|
+
if not allowed:
|
|
230
|
+
raise CircuitBreakerError(reason)
|
|
231
|
+
failed = False
|
|
232
|
+
try:
|
|
233
|
+
yield self.get_active_model()
|
|
234
|
+
except Exception:
|
|
235
|
+
failed = True
|
|
236
|
+
raise
|
|
237
|
+
finally:
|
|
238
|
+
if not failed and estimated_tokens > 0:
|
|
239
|
+
self.record_tokens(estimated_tokens)
|
|
240
|
+
|
|
241
|
+
|
|
242
|
+
# Global singleton instance for runtime interception
|
|
243
|
+
GLOBAL_CIRCUIT_BREAKER = TokenCircuitBreaker()
|
|
244
|
+
|
|
245
|
+
|
|
246
|
+
def record_tokens(count: int, model: Optional[str] = None) -> int:
|
|
247
|
+
return GLOBAL_CIRCUIT_BREAKER.record_tokens(count, model=model)
|
|
248
|
+
|
|
249
|
+
|
|
250
|
+
def record_http_status(status_code: int, error_message: str = "") -> Optional[str]:
|
|
251
|
+
return GLOBAL_CIRCUIT_BREAKER.record_http_status(status_code, error_message=error_message)
|
|
252
|
+
|
|
253
|
+
|
|
254
|
+
def can_execute() -> Tuple[bool, str]:
|
|
255
|
+
return GLOBAL_CIRCUIT_BREAKER.can_execute()
|
|
256
|
+
|
|
257
|
+
|
|
258
|
+
def get_active_model() -> str:
|
|
259
|
+
return GLOBAL_CIRCUIT_BREAKER.get_active_model()
|
|
260
|
+
|
|
261
|
+
|
|
262
|
+
def get_circuit_breaker() -> TokenCircuitBreaker:
|
|
263
|
+
return GLOBAL_CIRCUIT_BREAKER
|