Imported from Yavmarto/NeuroMorphicToolKit (
Neurobench/AGENTS.md). Install upstream withnpx skills add Yavmarto/NeuroMorphicToolKit --skill Neurobench. Copyright stays with the author.
Neurobench
Read first:
CODING_STYLE_GUIDE.mdneurobench/pyproject.tomlfrontend/pubspec.yamlfrontend/analysis_options.yamlneurobench_spec.mddocs/ADR-Gemini/,docs/ADR-Codex/,docs/ADR-claude/
Constraints:
neurobench/contracts/*.pyown request, report, comparison, regression, and robustness payloads; update contracts and contract tests before changing services or routers.- Keep benchmark execution logic in
app/services/; routers are transport only. If behavior changes, update service tests or property tests with it. - Optional
simulation,reports,spinnaker2,synsense, andpynqextras inneurobench/pyproject.tomlmust stay optional; core server startup must not depend on them. - Any change to benchmark inputs or suite-visible result schemas requires reading the upstream or downstream owner first:
neurocnl,Neurosense, orNeurohub. - Verify touched surfaces with
cd neurobench && poetry run pytest -v --cov=app tests/,cd neurobench && poetry run ruff check .,cd neurobench && poetry run mypy --strict ., andcd ../frontend && flutter test.
Do NOT:
- Encode benchmark or report schema changes only in frontend models.
- Make optional heavy dependencies mandatory just to satisfy a local code path.
- Move metric logic into routers or widget code.
Shell mode
Primary screen uses NmtkShellMode.command. Pass mode: NmtkShellMode.command to NmtkDesktopScaffold (or NmtkTopAppBar in embedded mode). This is the default, but always pass it explicitly for clarity.
NeuroBench uses GoRouter (Pattern B from UI_AUDIT_AND_FIX_PLAN.md ยงM.3): NmtkDesktopScaffold wraps the router's navigator via ShadApp.material.router's builder: callback. The NmtkWorkspaceSwitcherBar (Summary / Comparison / Reports / Robustness) lives inside the content area child, not in the top app bar. The utility panel width must use NmtkShellTokens.of(context).utilityPanelWidth โ never a hardcoded pixel value.
Pipeline Agent Directives
This document provides instructions and context for AI agents (like Jules) working on the Neurobench project. Neurobench is a testing and benchmarking workbench for evaluating Spiking Neural Network (SNN) performance.
๐ Project Architecture
Neurobench is divided into two main components:
- Backend (
neurobench/): A FastAPI-based Python application that handles benchmark execution, data persistence, and result analysis.app/: Contains the FastAPI application, routers, schemas, and services.contracts/: Pydantic models defining the core data contracts for benchmarks and results.cli/: Click-based CLI for running benchmarks from the command line.benchmarks/: JSON definitions for built-in and custom benchmarks.
- Frontend (
frontend/): A Flutter application for visualizing benchmark results, comparing targets, and managing benchmarks.
๐ Tech Stack
- Backend: Python 3.11+, FastAPI, Pydantic v2, SQLite, Poetry, Pytest, Hypothesis.
- Frontend: Flutter, Dart, Riverpod (state management).
- External Libraries:
neurocnl(simulation),nengo,numpy,mujoco.
๐ค General Instructions for Agents
- Read the Style Guide: Always adhere to the global coding standards defined in
CODING_STYLE_GUIDE.mdat the repository root. - Contract-First Development: When modifying benchmark data structures, always start with the Pydantic contracts in
neurobench/contracts/. - Strict Typing: Maintain strict typing in both Python (MyPy) and Dart. Avoid
Anyanddynamicwherever possible. - Property-Based Testing: Use
hypothesisfor testing complex logic, especially for data validation and metric calculations. - Simulations: Understand that the
BenchmarkRunnerinteracts withneurocnlto execute real SNN simulations.
๐ Development Workflows
Backend
- Install dependencies:
cd neurobench && poetry install - Run tests:
cd neurobench && poetry run pytest -v --cov=app tests/ - Linting:
cd neurobench && poetry run ruff check . - Type checking:
cd neurobench && poetry run mypy --strict .
Frontend
- Install dependencies:
cd frontend && flutter pub get - Run analysis:
cd frontend && flutter analyze - Run tests:
cd frontend && flutter test
๐งฉ Key Directories
neurobench/app/routers/: API endpoints.neurobench/app/services/: Business logic and core services (e.g.,benchmark_runner.py).neurobench/contracts/: Shared data models.frontend/lib/providers/: Riverpod state management logic.frontend/lib/screens/: Flutter UI screens.
<directory_structure> โโโ AGENTS.md โโโ CHANGELOG.md โโโ Dockerfile โโโ LICENSE โโโ Makefile โโโ PLAN.md โโโ README.md โโโ SECURITY.md โโโ UI migration.md โโโ docker-compose.yml โโโ docs โ โโโ ADR-Codex โ โ โโโ 0001-initial-architecture.md โ โโโ ADR-Gemini โ โ โโโ 0001-initial-architecture.md โ โ โโโ 0002-standardized-metrics-schema.md โ โโโ ADR-claude โ โ โโโ 0001-standardized-metrics-framework.md โ โ โโโ 0002-pluggable-hardware-backends.md โ โ โโโ 0003-regression-detection-engine.md โ โ โโโ 0004-report-generation.md โ โ โโโ 0005-robustness-testing.md โ โโโ api_reference.md โ โโโ archive โ โ โโโ 02-Apr-2026-status-Jules.md โ โ โโโ integration โ โ โ โโโ synsense_integration_plan.md โ โ โโโ pynq_integration_plan.md โ โ โโโ spinnaker2_integration_plan.md โ โโโ data-generation โ โ โโโ NSBI_execution_guide.md โ โ โโโ synthetic_dataset_generation_plan.md โ โโโ developer โ โ โโโ adding_new_metric.md โ โโโ unified-dev-pipeline โ โ โโโ neurobench โ โ โโโ GUARDRAILS.md โ โโโ user โ โโโ running_first_benchmark.md โโโ frontend โ โโโ LICENSE โ โโโ README.md โ โโโ analysis_options.yaml โ โโโ build_error.txt โ โโโ dart_test.yaml โ โโโ integration_test โ โ โโโ e2e_test.dart โ โโโ lib โ โ โโโ app.dart โ โ โโโ main.dart โ โ โโโ models โ โ โ โโโ benchmark.dart โ โ โ โโโ benchmark_job.dart โ โ โ โโโ result.dart โ โ โ โโโ workbench_tab.dart โ โ โ โโโ workspace_destination.dart โ โ โ โโโ workspace_route_state.dart โ โ โโโ providers โ โ โ โโโ benchmarks_provider.dart โ โ โ โโโ benchmarks_provider.g.dart โ โ โ โโโ compare_selection_provider.dart โ โ โ โโโ compare_selection_provider.g.dart โ โ โ โโโ dismissed_job_provider.dart โ โ โ โโโ dismissed_job_provider.g.dart โ โ โ โโโ execution_provider.dart โ โ โ โโโ execution_provider.g.dart โ โ โ โโโ results_provider.dart โ โ โโโ screens โ โ โ โโโ benchmark_screen.dart โ โ โ โโโ comparison_screen.dart โ โ โ โโโ regression_trends_screen.dart โ โ โ โโโ report_screen.dart โ โ โ โโโ robustness_screen.dart โ โ โ โโโ workbench_shell.dart โ โ โโโ services โ โ โ โโโ api_client.dart โ โ โโโ shell_adapter.dart โ โ โโโ widgets โ โ โโโ active_jobs_bar.dart โ โ โโโ baseline_selector.dart โ โ โโโ benchmark_catalog.dart โ โ โโโ benchmark_header_card.dart โ โ โโโ benchmark_results_table.dart โ โ โโโ benchmark_run_form.dart โ โ โโโ benchmark_workbench_tabs.dart โ โ โโโ comparison_workspace.dart โ โ โโโ metric_diff_table.dart โ โ โโโ neurobench_mobile_wizard.dart โ โ โโโ perturbation_curve_chart.dart โ โ โโโ report_builder.dart โ โ โโโ results_summary_card.dart โ โ โโโ robustness_curve_chart.dart โ โ โโโ run_history_timeline.dart โ โ โโโ target_comparison_grid.dart โ โ โโโ trend_chart.dart โ โโโ pubspec.lock โ โโโ pubspec.yaml โ โโโ test โ โ โโโ api_exception_test.dart โ โ โโโ api_integration_test.dart โ โ โโโ execution_flow_test.dart โ โ โโโ governance โ โ โ โโโ material_icons_audit_test.dart โ โ โโโ models โ โ โ โโโ result_test.dart โ โ โโโ navigation_test.dart โ โ โโโ test_helpers.dart โ โ โโโ widget_test.dart โ โ โโโ widgets โ โ โโโ active_jobs_bar_test.dart โ โ โโโ benchmark_run_form_test.dart โ โ โโโ perturbation_curve_chart_test.dart โ โ โโโ report_builder_test.dart โ โ โโโ robustness_curve_chart_test.dart โ โ โโโ run_history_timeline_no_nested_cards_test.dart โ โ โโโ run_history_timeline_test.dart โ โ โโโ target_comparison_grid_test.dart โ โ โโโ trend_chart_test.dart โ โโโ web โ โโโ favicon.png โ โโโ icons โ โ โโโ Icon-192.png โ โ โโโ Icon-512.png โ โ โโโ Icon-maskable-192.png โ โ โโโ Icon-maskable-512.png โ โโโ index.html โ โโโ manifest.json โโโ issues-archive โ โโโ 001-beta-implement-benchmark-create-endpoint-remove-501.md โ โโโ 001-hardware-benchmark-integration.md โ โโโ 001-spinncloud-spinnaker2-benchmarking.md โ โโโ 002-beta-fix-benchmark-fixtures-and-baseline-selector-typing.md โ โโโ 002-synsense-dynapcnn-benchmarking.md โ โโโ 002a-cloud-runner-schema.md โ โโโ 002b-cloud-orchestration-agent.md โ โโโ 003-beta-add-real-benchmark-execution-integration-smoke.md โ โโโ 003-pynq-z2-energy-power-benchmarking.md โ โโโ 003-wire-neurobench-verification-toggle.md โ โโโ 004-replace-pynq-placeholder-result-and-power-trace-endpoints.md โ โโโ 005-define-deterministic-karpathy-triplets.md โ โโโ 006-beta-rate-limiting.md โ โโโ 007-beta-authentication-layer.md โ โโโ 008-beta-structured-logging.md โ โโโ 009-beta-real-benchmark-execution.md โ โโโ 01-f811-redefined-names.md โ โโโ 010-beta-diff-engine-enhancements.md โ โโโ 011-beta-security-md-and-changelog-md.md โ โโโ 012-prod-end-to-end-integration-tests.md โ โโโ 013-prod-report-generation-system.md โ โโโ 014-prod-container-hardening.md โ โโโ 015-prod-regression-testing-framework.md โ โโโ 016-prod-user-documentation.md โ โโโ 02-plw0602-global-state.md โ โโโ 03-arg001-unused-router-args.md โ โโโ 04-g004-try401-logging.md โ โโโ 05-pt011-pytest-raises-match.md โ โโโ 06-pth-pathlib-modernization.md โ โโโ 07-sim117-nested-with.md โ โโโ 08-plc0206-era001-dict-and-deadcode.md โ โโโ 09-npy002-numpy-random.md โ โโโ 10-ann-type-hints.md โ โโโ 10-neurobench-shared-shell-theme-and-results-summary.md โ โโโ 11-d417-docstring-args.md โ โโโ 11-neurobench-shell-adapter-and-comparison-workspace.md โ โโโ 12-neurobench-job-setup-and-execution-controls.md โ โโโ 12-plc0415-inline-imports.md โ โโโ 13-plr2004-magic-numbers.md โ โโโ 14-plr0915-oversized-functions.md โ โโโ NBENCH-001-outdated-actions.md โ โโโ NBENCH-002-benchmark-runner-hardware-stubs.md โ โโโ NBENCH-003-fault-sweeper-real-implementation.md โ โโโ NBENCH-004-perturbation-sweeper-real-implementation.md โ โโโ NBENCH-005-encoding-comparator-real-implementation.md โ โโโ NBENCH-006-target-comparator-real-implementation.md โ โโโ NBENCH-007-spike-fidelity-edge-cases.md โ โโโ NBENCH-008-diff-engine-tolerance-edge-cases.md โ โโโ NBENCH-009-pydantic-contract-enforcement.md โ โโโ NBENCH-010-json-export-serialization.md โ โโโ sent-pynq_benchmarking_integration.md โ โโโ sent-spinnaker2_benchmarking_integration.md โโโ neurobench โ โโโ GUARDRAILS.md โ โโโ LICENSE โ โโโ app โ โ โโโ init.py โ โ โโโ auth.py โ โ โโโ config.py โ โ โโโ exceptions.py โ โ โโโ limiter.py โ โ โโโ logging_config.py โ โ โโโ main.py โ โ โโโ routers โ โ โ โโโ init.py โ โ โ โโโ baselines.py โ โ โ โโโ benchmarks.py โ โ โ โโโ comparison.py โ โ โ โโโ faults.py โ โ โ โโโ perturbation.py โ โ โ โโโ pynq.py โ โ โ โโโ regression.py โ โ โ โโโ reports.py โ โ โ โโโ results.py โ โ โ โโโ runner.py โ โ โ โโโ spinnaker2.py โ โ โ โโโ synsense.py โ โ โโโ runners โ โ โ โโโ pynq_runner.py โ โ โ โโโ spinnaker2_runner.py โ โ โ โโโ synsense_runner.py โ โ โโโ schemas โ โ โ โโโ init.py โ โ โ โโโ benchmarks.py โ โ โ โโโ common.py โ โ โ โโโ comparison.py โ โ โ โโโ reports.py โ โ โ โโโ results.py โ โ โ โโโ robustness.py โ โ โโโ services โ โ โ โโโ init.py โ โ โ โโโ benchmark_loader.py โ โ โ โโโ benchmark_markdown_report.py โ โ โ โโโ benchmark_runner.py โ โ โ โโโ cross_platform_validation.py โ โ โ โโโ diff_engine.py โ โ โ โโโ encoding_comparator.py โ โ โ โโโ fault_sweeper.py โ โ โ โโโ job_manager.py โ โ โ โโโ metric_normalizer.py โ โ โ โโโ neurobench_executor.py โ โ โ โโโ neurosense_artifact.py โ โ โ โโโ perturbation_sweeper.py โ โ โ โโโ regression_service.py โ โ โ โโโ report_generator.py โ โ โ โโโ result_store.py โ โ โ โโโ seed_published_results.py โ โ โ โโโ target_comparator.py โ โ โโโ templates โ โ โโโ report.html โ โโโ benchmarks โ โ โโโ builtin โ โ โโโ auto_radar.json โ โ โโโ dvs_gesture.json โ โ โโโ ecg_classification.json โ โ โโโ grip_stability.json โ โ โโโ keyword_spotting.json โ โ โโโ mackey_glass.json โ โ โโโ nehar.json โ โ โโโ neurosense_replay_contract.json โ โ โโโ primate_reaching.json โ โ โโโ ptb_lm.json โ โโโ cli โ โ โโโ main.py โ โโโ contracts โ โ โโโ init.py โ โ โโโ benchmark_contracts.py โ โ โโโ comparison_contracts.py โ โ โโโ regression_contracts.py โ โ โโโ report_contracts.py โ โ โโโ robustness_contracts.py โ โโโ data โ โ โโโ reports โ โ โโโ rep_013a4919.html โ โ โโโ rep_58c4e53a.html โ โ โโโ rep_7536d3f7.json โ โ โโโ rep_85687c15.json โ โ โโโ rep_e7012839.html โ โ โโโ rep_ead6c506.json โ โโโ neurobench.sqlite โ โโโ poetry.toml โ โโโ pyproject.toml โ โโโ reports โ โ โโโ rep_01a162a4.json โ โ โโโ rep_0283e563.html โ โ โโโ rep_27ceb33f.json โ โ โโโ rep_30d01f8d.html โ โ โโโ rep_4ae5da94.html โ โ โโโ rep_5c0cde54.json โ โ โโโ rep_6125611e.json โ โ โโโ rep_62bd53c7.html โ โ โโโ rep_69afc042.html โ โ โโโ rep_7386850a.json โ โ โโโ rep_8b97da06.html โ โ โโโ rep_972eef11.json โ โ โโโ rep_c755c648.json โ โ โโโ rep_d7e760cf.json โ โโโ tests โ โ โโโ FIXTURES.md โ โ โโโ init.py โ โ โโโ conftest.py โ โ โโโ properties โ โ โ โโโ init.py โ โ โ โโโ strategies.py โ โ โ โโโ test_benchmark_properties.py โ โ โ โโโ test_regression_properties.py โ โ โ โโโ test_robustness_properties.py โ โ โโโ services โ โ โ โโโ test_target_comparator.py โ โ โโโ test_auth.py โ โ โโโ test_benchmark_markdown_report.py โ โ โโโ test_benchmark_runner_hardware.py โ โ โโโ test_contracts.py โ โ โโโ test_cross_platform_validation.py โ โ โโโ test_data.npy โ โ โโโ test_diff_engine.py โ โ โโโ test_dummy.py โ โ โโโ test_encoding_comparator.py โ โ โโโ test_fault_sweeper.py โ โ โโโ test_metric_normalizer.py โ โ โโโ test_network.cnl โ โ โโโ test_neurosense_artifact_service.py โ โ โโโ test_perturbation_sweeper.py โ โ โโโ test_rate_limiting.py โ โ โโโ test_real_benchmarks.py โ โ โโโ test_regression_service.py โ โ โโโ test_report_generator.py โ โ โโโ test_result_store.py โ โ โโโ test_router_core.py โ โ โโโ test_router_results_comp.py โ โ โโโ test_router_robustness_reports.py โ โ โโโ test_schemas.py โ โ โโโ test_service_data.py โ โ โโโ test_service_logic.py โ โ โโโ test_service_stubs.py โ โ โโโ test_smoke.py โ โโโ uv.lock โโโ neurobench.sqlite โโโ neurobench_functional_testing_guide.md โโโ neurobench_spec.md โโโ reports โ โโโ rep_1b0d34d5.html โ โโโ rep_7c3ea763.json โโโ scripts โโโ generate_all_datasets.sh </directory_structure>
Remote Testing Configuration
For dev, REMOTE_HOST=dev@<dev-host> can be used. For example, when the agent wants to test run the app, you can use <dev-host> as the server address.
