Imported from organvm-iii-ergon/materia-collider (AGENTS.md). Install upstream with npx skills add organvm-iii-ergon/materia-collider. Copyright stays with the author.

AGENTS.md - Agentic Coding Guidelines

This file provides guidance for AI coding agents operating in the materia-collider workspace.

Project Overview

materia-collider is a pre-codified experimental space in meta-organvm where ideas exist before they are structured enough for an organ. See CLAUDE.md for the full project philosophy.

Build, Test, and Development Commands

Running Tests

# Run all tests in a project
python -m pytest tests/ -v

# Run a specific test file
python -m pytest tests/unit/test_modules.py -v

# Run a single test class
python -m pytest tests/unit/test_modules.py::TestIntakeModule -v

# Run a single test method
python -m pytest tests/unit/test_modules.py::TestIntakeModule::test_intake_ingest_content -v

# Run with coverage (if pytest-cov installed)
python -m pytest tests/ -v --cov=src --cov-report=term-missing

# Run tests matching a pattern
python -m pytest -k "test_intake" -v

Running the Pipeline

# Check pipeline status
python scripts/pipeline.py status

# Run specific pipeline commands
python scripts/pipeline.py ingest path/to/file.txt
python scripts/pipeline.py refine atom_abc123
python scripts/pipeline.py deduplicate
python scripts/pipeline.py integrity
python scripts/pipeline.py assemble "your query here"

Code Quality

# Install dependencies
pip install requests pytest pytest-cov

# Lint with ruff (if available)
ruff check src/
ruff format src/

Code Style Guidelines

Python Conventions

• Indentation: 4 spaces (no tabs)
• Line Length: Maximum 88 characters (ruff default)
• Encoding: UTF-8

Naming Conventions

Import Organization

Order imports with blank lines between groups:

# Standard library
import hashlib
import json
import re
from dataclasses import dataclass, field
from datetime import datetime
from pathlib import Path
from typing import Optional

# Third-party packages
try:
    import nltk
    HAS_NLTK = True
except ImportError:
    HAS_NLTK = False

# Local imports (use relative when possible)
from .module import ClassName
from ..package import function

Type Hints

Use type hints throughout. Avoid Any when possible.

# Good
def process_atoms(atoms: list[dict]) -> list[str]:
    results: list[str] = []
    return results

# Avoid
def process_atoms(atoms):
    results = []
    return results

Error Handling

• Use specific exception types
• Never use bare except:
• Use context managers for resources

# Good
try:
    result = process_content(content)
except ValueError as e:
    logger.error(f"Invalid content: {e}")
    raise

with open(filepath, 'r') as f:
    content = f.read()

# Bad
try:
    result = process_content(content)
except:
    pass

f = open(filepath, 'r')
content = f.read()
f.close()

Docstrings

Use Google-style docstrings for public APIs:

def ingest_content(content: str, source_type: str = "text") -> IntakeRecord:
    """Ingest content into the knowledge engine.

    Args:
        content: The content to ingest.
        source_type: Type of source (file, url, text, transcript).

    Returns:
        IntakeRecord with ingested content and extracted pairs.

    Raises:
        ValueError: If content is empty.
    """

Project Structure

materia-collider/
├── bench/                  # Unstructured experimental ideas (no format requirements)
├── protocols/              # Experimental methods (repeatable processes)
├── experiments/            # Dated collision results (YYYY-MM-DD-*.md)
├── observations/           # Pattern analysis across experiments
├── genesis/               # Founding documents
├── .github/               # GitHub workflows and org standards
└── CLAUDE.md             # Project philosophy

Bench Subdirectories

Projects in bench/organ-reset-2026-03-11/ may have their own structure including:

• src/ - Source code
• tests/ - Test files
• docs/ - Documentation
• scripts/ - Automation scripts
• pyproject.toml - Python project configuration

Testing Guidelines

Test File Organization

• Place tests in tests/ directory at project root
• Name test files test_*.py
• Name test classes Test* and test methods test_*

class TestIntakeModule:
    """Tests for Source Intake module."""

    def test_intake_ingest_content(self):
        """Test content ingestion."""
        ...

Test Fixtures

Use pytest fixtures for setup/teardown:

@pytest.fixture
def temp_dir():
    with tempfile.TemporaryDirectory() as tmpdir:
        yield Path(tmpdir)

@pytest.fixture
def sample_text():
    return "Sample text for testing."

Assertions

Use descriptive assertions with clear error messages:

# Good
assert result.id is not None, "Atom ID should be generated"
assert len(atoms) > 0, "Should extract at least one atom"

# Avoid
assert result.id
assert len(atoms)

Commit Conventions

Use Conventional Commits with these prefixes:

git commit -m "feat: add content hashing to intake module"
git commit -m "fix: resolve regex parsing error in code refinery"
git commit -m "docs: update README with test instructions"

Security Best Practices

• Never commit secrets, API keys, or credentials
• Use environment variables for sensitive configuration
• Add secrets to .gitignore
• Report security issues through appropriate channels

Additional Resources

• See /Users/4jp/Workspace/meta-organvm/AGENTS.md for workspace-level guidelines
• See CLAUDE.md for project philosophy and structure
• Reference existing implementations in src/ directories for patterns

Last updated: 2026-03-14

Agent Context (auto-generated — do not edit)

This repo participates in the META-ORGANVM (Meta) swarm.

Active Subscriptions

• No active event subscriptions

Production Responsibilities

• Produce tooling for omni-dromenon-machina/amp-lab-media

External Dependencies

• Consume reference from meta-organvm/praxis-perpetua

Governance Constraints

• Adhere to unidirectional flow: I→II→III
• Never commit secrets or credentials

Last synced: 2026-04-14T21:32:17Z