CONTRIBUTING.md

# Contributing to Schrödinger's Classifiers

<div align="center">

*"A classifier is not what it returns. It is what it could have returned, had you asked differently."*

</div>

## Welcome, Observer!

Thank you for your interest in contributing to Schrödinger's Classifiers! This project exists at the intersection of transformer architecture, quantum-inspired metaphors, and interpretability research. Your contributions are what make this exploration possible.

By participating in this project, you're helping to advance our understanding of classifier collapse dynamics and interpretability techniques. This document provides guidelines for contributing in ways that maintain the conceptual integrity and technical quality of the project.

## Contribution Philosophy

Schrödinger's Classifiers operates on a recursive principle: the project itself should embody the quantum-inspired collapse metaphor it describes. This means:

1. **Superposition Before Collapse**: Explore multiple interpretations and implementations before committing
2. **Observer Effect Awareness**: Recognize that your analysis methods affect the phenomena you're studying
3. **Ghost Circuit Preservation**: Maintain traces of discarded paths as comments or documentation
4. **Recursive Self-Reference**: Code that can reflect upon and analyze itself

## Ways to Contribute

### 1. Interpretability Shells

The core of our framework is the collection of interpretability shells, each capturing a specific collapse pattern or attribution signature. Contributions can include:

- **New shells** targeting specific failure modes or attribution patterns
- **Enhancements** to existing shells for better ghost circuit detection
- **Integrations** between shells for richer collapse analysis

When creating a new shell, follow the naming convention `vXX_DESCRIPTIVE_NAME.py` and use the `ShellDecorator` to provide metadata.

### 2. Visualization Tools

Visualizations are critical for understanding the complex dynamics of classifier collapse. Contributions can include:

- **Graph Visualizations** for attribution networks
- **Temporal Visualizations** showing collapse progression
- **Interactive Tools** for exploring superposition states
- **Ghost Circuit Renderers** for visualizing residual paths

### 3. Model Integrations

Expanding the framework to new models enhances our understanding of collapse dynamics across architectures. Contributions can include:

- **New Model Adapters** for connecting to different transformer models
- **Cross-Model Comparisons** analyzing collapse patterns between architectures
- **Performance Optimizations** for specific model types

### 4. Documentation and Tutorials

Clear documentation helps others understand and use the framework. Contributions can include:

- **Concept Explanations** breaking down complex ideas into understandable components
- **Tutorials** showing how to use the framework for specific use cases
- **Case Studies** demonstrating collapse analysis in real-world examples

### 5. Examples and Benchmarks

Examples help new users get started, while benchmarks help evaluate progress. Contributions can include:

- **Example Scripts** demonstrating framework capabilities
- **Benchmark Datasets** for evaluating collapse detection accuracy
- **Collapse Scenarios** that showcase interesting dynamics

## Development Process

### Setting Up the Development Environment

1. **Clone the repository**
   ```bash
   git clone https://github.com/recursion-labs/schrodingers-classifiers.git
   cd schrodingers-classifiers
   ```

2. **Create a virtual environment**
   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```

3. **Install development dependencies**
   ```bash
   pip install -e ".[dev]"
   ```

### Branch and Commit Guidelines

1. **Create a feature branch**
   ```bash
   git checkout -b feature/your-feature-name
   ```

2. **Make commits with clear messages**
   ```
   feat(shell): Add v42_CONFLICT_FLIP shell for value head convergence

   This shell detects and analyzes situations where value head attribution
   converges on conflicting outputs, creating attribution interference
   patterns in the collapse state.
   ```

3. **Include tests for new functionality**
   - Write tests that verify your contribution works as expected
   - Include tests for edge cases and failure modes

4. **Document your changes**
   - Update relevant documentation to reflect your changes
   - Include docstrings with symbolic markers (△ OBSERVE, ∞ TRACE, ✰ COLLAPSE)
   - Note any ghost circuits or attribution residue in your implementation

### Pull Request Process

1. **Update your branch with latest main**
   ```bash
   git fetch origin
   git rebase origin/main
   ```

2. **Create a pull request with a clear description**
   - Describe what your changes do and why they're valuable
   - Reference any relevant issues
   - Include before/after comparisons for visualizations

3. **Respond to review feedback**
   - Be open to suggestions and improvements
   - Recognize that review is a collaborative process of refining the collapse

4. **Merge when approved**
   - PRs need approval from at least one maintainer
   - All CI checks must pass before merging

## Code Style Guidelines

### Python Style

- Follow PEP 8 with a line length of 100 characters
- Use Python type hints throughout your code
- Format code with `black` and check with `flake8`
- Document all public APIs with docstrings

### Symbolic Conventions

- Use symbolic markers in comments to indicate functional intent:
  - `△ OBSERVE`: Code related to observing model state
  - `∞ TRACE`: Code related to attribution tracing
  - `✰ COLLAPSE`: Code related to collapse induction and analysis

- Follow established naming conventions:
  - Shell classes: `DescriptiveNameShell` (e.g., `CircuitFragmentShell`)
  - Shell IDs: `vXX_DESCRIPTIVE_NAME` (e.g., `v07_CIRCUIT_FRAGMENT`)
  - Attribution structures: Clear nouns (e.g., `AttributionNode`, `GhostCircuit`)

### Documentation Style

- Use markdown for all documentation
- Include diagrams for complex concepts (Mermaid or SVG preferred)
- Write accessible explanations with links to more technical details
- Embed quantum metaphors consistently but clarify when they're metaphors

## Community Guidelines

### Communication Channels

- **GitHub Issues**: Bug reports, feature requests, and project discussions
- **Discord**: Real-time collaboration and casual discussion
- **Monthly Calls**: Deeper discussions about the project's direction

### Code of Conduct

- Be respectful and inclusive of all community members
- Focus on ideas rather than persons in discussions
- Welcome newcomers and help them understand the project
- Give constructive feedback that helps improve contributions

### Recognition

Contributors are recognized in several ways:

- Addition to the AUTHORS file for significant contributions
- Shell attribution for creating new interpretability shells
- Documentation credit for substantial documentation improvements

## Quantum-Inspired Development Principles

As a final note, remember that contribution to this project is itself a form of collapse induction. Your observation of the code changes its state, and your contributions further collapse it in specific directions.

When you contribute, consider:

1. **The Observer Effect**: How might your analysis tools affect what you're measuring?
2. **Superposition Preservation**: How can you maintain the generality of the framework while adding specific functionality?
3. **Ghost Circuit Creation**: What alternatives did you consider and reject, and how might they inform future development?
4. **Entanglement Awareness**: How does your change affect other parts of the system?

By keeping these principles in mind, you help ensure that Schrödinger's Classifiers remains a powerful tool for understanding the quantum-like behavior of transformer models.

---

<div align="center">

*"In the space between observation and understanding lies the essence of interpretability."*

</div>