spyglass icon indicating copy to clipboard operation
spyglass copied to clipboard

Add AGENTS.md for LLM guidance on Spyglass standards and conventions

Open Copilot opened this issue 7 months ago • 2 comments

This PR adds a comprehensive AGENTS.md file to provide Large Language Models (LLMs) and AI agents with essential guidance for working with the Spyglass neuroscience data analysis framework. The file serves as a definitive reference to ensure consistent and correct assistance when helping developers create new Spyglass tables, pipelines, and analyses.

What's included

The AGENTS.md file provides:

  • Core Architecture Overview: DataJoint foundations, SpyglassMixin requirements, and schema organization patterns
  • Detailed Table Type Definitions: Comprehensive coverage of Parameters, Selection, Computed, NWB Ingestion, and Merge tables with practical code examples
  • Development Standards: Naming conventions, code organization principles, and required method implementations
  • LLM-Specific Best Practices: Guidelines for creating tables, common workflows, and avoiding typical mistakes
  • Validated Patterns: All examples verified against actual Spyglass codebase implementation

Key benefits

This documentation will help LLMs:

  • Understand the mandatory SpyglassMixin inheritance pattern: class MyTable(SpyglassMixin, dj.TableType)
  • Select appropriate table types based on use case (Lookup for parameters, Manual for selections, Computed for analysis)
  • Follow established naming conventions and schema organization
  • Implement required methods like make() and insert_default()
  • Handle NWB file operations and DataJoint dependencies correctly

Example usage guidance

The file includes practical examples like this Parameters table pattern:

@schema
class MyAnalysisParameters(SpyglassMixin, dj.Lookup):
    definition = """
    analysis_params_name: varchar(32)
    ---
    analysis_params: blob
    """
    
    contents = [
        ["default", {"threshold": 0.5, "window_size": 100}],
    ]
    
    @classmethod
    def insert_default(cls):
        cls().insert(rows=cls.contents, skip_duplicates=True)

The documentation ensures LLMs will provide assistance that maintains consistency with Spyglass standards while helping developers create robust, reproducible neuroscience analysis pipelines.

Fixes #1406.


💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

Copilot avatar Sep 23 '25 12:09 Copilot

Codecov Report

:white_check_mark: All modified and coverable lines are covered by tests. :white_check_mark: Project coverage is 70.54%. Comparing base (be9314f) to head (e75209b). :warning: Report is 20 commits behind head on master.

Additional details and impacted files
@@           Coverage Diff           @@
##           master    #1407   +/-   ##
=======================================
  Coverage   70.54%   70.54%           
=======================================
  Files         104      104           
  Lines       12650    12650           
=======================================
  Hits         8924     8924           
  Misses       3726     3726           

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

:rocket: New features to boost your workflow:
  • :snowflake: Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

codecov[bot] avatar Sep 23 '25 13:09 codecov[bot]

Possibly should wait to merge until https://github.com/LorenFrankLab/spyglass/pull/1377 is merged

edeno avatar Sep 23 '25 13:09 edeno