@brainpilot/skills 0.0.6 → 0.0.7

package/skills/16_Animal_Behavior/ethoclaw-analysis-report/references/report-sections.md

@@ -0,0 +1,86 @@
+# Report Sections
+
+Read this file when organizing report structure or understanding `manifest["section_bodies"]`.
+
+## Body Filling Contract
+
+All body text is directly written to:
+
+- `manifest["section_bodies"][body_key]["body"]`
+
+Do not create `sections.json`. Do not write body text to other intermediate files.
+
+## Available Body List
+
+### `project_summary_body`
+
+- Corresponding section: Project Summary
+- Purpose: Compress path scope, core materials, current report mode, and key gaps into a short section
+- Empty condition: Never leave empty, should always be filled
+
+### `overview_body`
+
+- Corresponding section: Overview
+- Purpose: Provide high-level overview at the project level and add a sentence about experimental purpose and basic workflow
+- Empty condition: Only can be minimally written as result organization when project purpose and core background cannot be confirmed at all
+
+### `sample_check_body`
+
+- Corresponding section: Sample and Group Verification
+- Purpose: Verify sample count, sample IDs, candidate groups, group mapping, and control group
+- Empty condition: Never leave empty, should always be filled
+
+### `raw_trajectory_body`
+
+- Corresponding section: Raw Trajectory Summary
+- Purpose: When only raw skeleton or trajectory data exists, directly summarize activity areas, axis distribution, path length, and differences between samples
+- Empty condition: Leave empty when no directly readable trajectory coordinates exist; applicable to both single-sample and multi-sample projects
+
+### `heatmap_body`
+
+- Corresponding section: Heatmap Findings
+- Purpose: Describe spatial distribution or movement patterns reflected in heatmaps, trajectory plots, atlas, time-series plots
+- Empty condition: Leave empty when current directory has no heatmap materials
+
+### `radar_body`
+
+- Corresponding section: Radar Profile Findings
+- Purpose: Describe multi-parameter profiles in radar plots
+- Empty condition: Leave empty when current directory has no radar plots
+
+### `stats_body`
+
+- Corresponding section: Statistical Comparison Findings
+- Purpose: Summarize comparison results supported by statistical tables or clear statistical figures
+- Empty condition: Leave empty when no statistical basis exists or grouping information is insufficient to support comparisons
+
+### `cluster_body`
+
+- Corresponding section: Clustering Findings
+- Purpose: Describe pattern structures in cluster plots
+- Empty condition: Leave empty when current directory has no cluster plots
+
+### `single_subject_body`
+
+- Corresponding section: Single-Subject Profile
+- Purpose: Summarize core indicators and image observations for single sample in single-sample mode
+- Empty condition: Leave empty when not in `single-subject` mode
+
+### `integrated_interpretation_body`
+
+- Corresponding section: Integrated Interpretation
+- Purpose: Integrate multiple result sources across figure types to form concise direct comprehensive summary
+- Empty condition: Leave empty when figure types are insufficient or metadata is insufficient to support comprehensive organization
+
+## Usage Principles
+
+- Not every body needs to be filled every time
+- Figure-related bodies should be left empty when no evidence exists
+- Empty bodies will not be rendered
+- The `purpose`, `write_when`, `source_fields`, `rules` in `section_bodies` are writing constraints for the agent, should not be rendered as-is into final reports
+- Body language defaults to current user conversation language; when terms first appear, prioritize writing as "Chinese (English)"
+- When filling bodies, directly edit `manifest.json`, do not inject large text through shell pipes or inline commands to avoid encoding contamination
+- Each body should prioritize summarizing the most obvious results of current data, do not write entire section as "cannot draw conclusions"
+- If limitations need to be stated, prioritize concentrating in `project_summary_body`, `overview_body`, or `integrated_interpretation_body`
+- For obvious file name prefixes like `control`, `model`, `sham`, `vehicle`, can directly use as candidate groupings
+- For projects with only skeleton data, prioritize writing the most obvious activity areas, axis distribution, or movement range differences, not just doing material inventory

package/skills/16_Animal_Behavior/ethoclaw-analysis-report/references/section-selection-rules.md

@@ -0,0 +1,169 @@
+# Section Selection Rules
+
+Read this file when dynamically selecting report mode and `section_bodies` based on project materials.
+
+## Report Mode Determination
+
+### `single-subject`
+
+Applicable conditions:
+
+- Only one sample detected
+- No formal groupings to compare
+- Focus is on summarizing single trajectory, single image result, or single statistical metric
+
+Enabled by default:
+
+- `project_summary_body`
+- `overview_body`
+- `sample_check_body`
+- `single_subject_body`
+
+Supplement based on materials:
+
+- `raw_trajectory_body`
+- `heatmap_body`
+- `radar_body`
+- `stats_body`
+- `integrated_interpretation_body`
+
+### `multi-sample-no-groups`
+
+Applicable conditions:
+
+- Multiple samples detected
+- No clear groupings
+- Or only ambiguous abbreviation labels appear
+
+Enabled by default:
+
+- `project_summary_body`
+- `overview_body`
+- `sample_check_body`
+
+Supplement based on materials:
+
+- `raw_trajectory_body`
+- `heatmap_body`
+- `radar_body`
+- `cluster_body`
+- `integrated_interpretation_body`
+
+Do not write formal inter-group conclusions.
+
+### `grouped-raw-summary`
+
+Applicable conditions:
+
+- Multiple samples detected
+- Clear groupings already appear in file name prefixes or configuration, e.g., `control` / `model`
+- Currently no formal statistical tables or result figures, but can directly make basic summaries from raw skeleton trajectories
+
+Enabled by default:
+
+- `project_summary_body`
+- `overview_body`
+- `sample_check_body`
+- `raw_trajectory_body`
+
+Supplement based on materials:
+
+- `heatmap_body`
+- `radar_body`
+- `integrated_interpretation_body`
+
+Allowed to directly write difference directions on raw trajectories, such as larger activity range, principal axis distribution more biased toward one side, but do not write as significance or mechanistic conclusions.
+
+### `grouped-comparison`
+
+Applicable conditions:
+
+- Clear groupings exist
+- Group meanings are confirmed, or file name prefixes are clear enough to support basic comparisons
+- At least some inter-group comparison figures, statistical tables, or other high-level results exist
+
+Enabled by default:
+
+- `project_summary_body`
+- `overview_body`
+- `sample_check_body`
+
+Supplement based on materials:
+
+- `raw_trajectory_body`
+- `heatmap_body`
+- `radar_body`
+- `stats_body`
+- `cluster_body`
+- `integrated_interpretation_body`
+
+### `raw-trajectory-summary`
+
+Applicable conditions:
+
+- Main available materials are raw skeleton or trajectory data
+- Not enough high-level result figures or statistical tables
+- But still can extract basic behavioral summaries from coordinate distributions and path lengths
+
+Enabled by default:
+
+- `project_summary_body`
+- `overview_body`
+- `sample_check_body`
+- `raw_trajectory_body`
+
+### `figure-only-summary`
+
+Applicable conditions:
+
+- Main inputs are image results
+- Lacking reliable tables or metadata support
+
+Enabled by default:
+
+- `project_summary_body`
+- `overview_body`
+- `sample_check_body`
+
+Supplement based on materials:
+
+- `heatmap_body`
+- `radar_body`
+- `cluster_body`
+- `integrated_interpretation_body`
+
+### `data-inventory-only`
+
+Applicable conditions:
+
+- Missing key background
+- Materials under `project_path` are very scattered
+- Cannot extract reliable result-level information
+
+Enabled by default:
+
+- `project_summary_body`
+- `overview_body`
+- `sample_check_body`
+
+Do not enable bodies that depend on figure interpretation.
+
+## Body Enabling Conditions
+
+- `project_summary_body`: Always enabled
+- `overview_body`: Always enabled
+- `sample_check_body`: Always enabled
+- `raw_trajectory_body`: Exists trajectory coordinates that can be directly read; enabled for both single-sample and multi-sample projects
+- `heatmap_body`: At least one heatmap, trajectory plot, atlas, or time-series plot exists
+- `radar_body`: Radar plot exists
+- `stats_body`: Statistical figure or statistical table exists
+- `cluster_body`: Cluster plot exists
+- `single_subject_body`: Current mode is `single-subject`
+- `integrated_interpretation_body`: At least two different evidence sources exist simultaneously, e.g., raw trajectory + image results, or two types of image results
+
+## Usage Boundaries
+
+- If file name prefixes are already obvious, labels like `control`, `model`, `sham`, `vehicle` can be directly used as candidate groupings
+- If labels are opaque abbreviations like `Y`, `K`, `A1`, still confirm with the user first
+- Leave `stats_body` empty when no statistical basis exists
+- `raw_trajectory_body` should prioritize writing intuitive features on coordinate distributions and activity ranges, not degrade to material inventory

package/skills/16_Animal_Behavior/ethoclaw-analysis-report/scripts/build_report_manifest.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from report_utils import build_manifest, ensure_project_path, save_json
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Build a manifest.json for an Ethoclaw analysis project.")
+    parser.add_argument("--project-path", required=True, help="Path to the project directory to analyze.")
+    parser.add_argument("--output", help="Optional output file path for manifest.json.")
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    project_path = ensure_project_path(args.project_path)
+    manifest = build_manifest(project_path)
+    if args.output:
+        save_json(Path(args.output), manifest)
+    else:
+        print(manifest)
+
+
+if __name__ == "__main__":
+    main()

package/skills/16_Animal_Behavior/ethoclaw-analysis-report/scripts/render_report.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from report_utils import load_json, render_report_html, render_report_markdown, write_text
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Render markdown and HTML outputs from a manifest.json file.")
+    parser.add_argument("--manifest", required=True, help="Path to an existing manifest JSON file.")
+    parser.add_argument("--output-dir", help="Directory for rendered report outputs.")
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    manifest_path = Path(args.manifest).resolve()
+    manifest = load_json(manifest_path)
+    project_path = Path(manifest["project_path"]).resolve()
+
+    output_dir = Path(args.output_dir).resolve() if args.output_dir else (project_path / "report_output")
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    markdown_text = render_report_markdown(manifest)
+    html_text = render_report_html(manifest, markdown_text)
+
+    write_text(output_dir / "report.md", markdown_text)
+    write_text(output_dir / "report.html", html_text)
+    print(f"Rendered HTML report to {output_dir}")
+
+
+if __name__ == "__main__":
+    main()