Skip to content

Latest commit

 

History

History
315 lines (252 loc) · 11.4 KB

AGENTS.md

File metadata and controls

315 lines (252 loc) · 11.4 KB

Noematics

Styled after the DyTopo paper: https://arxiv.org/html/2602.06039v1

AGENTS.md - Agent Coding Guidelines

This file provides strict coding and behavioral constraints for agent implementations in this repository.

Build, Lint, and Test Commands

Development Setup

poetry install          # Install dependencies
poetry shell           # Activate virtual environment
pre-commit install     # Install pre-commit hooks

Running Tests

pytest                             # Run all tests
pytest tests/unit/test_agent_system.py              # Single test file
pytest tests/unit/test_agent_system.py::TestAgentBase::test_agent_initialization  # Single test
pytest --cov=src/noematics --cov-report=html       # With coverage
pytest -k "test_semantic"                       # Pattern matching
pytest -v                                       # Verbose mode
pytest -s                                       # Disable stdin capture
pytest tests/integration/                        # Integration tests only

Linting and Formatting

black src/ tests/                              # Format code
black --check src/ tests/                      # Check without applying
mypy src/                                      # Type checking
mypy --strict src/                             # Strict mode
pre-commit run --all-files                    # Run all linters

Interface Stability (CRITICAL)

DO NOT MODIFY src/noematics/core/interfaces.py

This file is a stable contract, not a working surface.

  • Do NOT add methods
  • Do NOT add convenience fields
  • Do NOT "improve ergonomics"
  • Do NOT let future-you touch it casually

If something later feels like it needs a change here, that's a signal the runtime or interpretation implementation is wrong — not the interfaces.

Code Style Guidelines

Imports

  • Use absolute imports: from noematics.agents.base import Agent
  • Sort: standard library → third-party → local
  • Never use wildcard imports (from x import *)

Formatting (Black)

  • Line length: 100 characters
  • Run Black before committing

Types

  • Use type hints for all signatures
  • Use Optional[X] instead of X | None (Python 3.9 compatibility)
  • Use List, Dict, Tuple from typing
  • Use @dataclass for simple data containers

Naming Conventions

  • Classes: CamelCase (e.g., AgentMessage, SemanticMatcher)
  • Functions/methods: snake_case (e.g., build_communication_graph)
  • Constants: UPPER_SNAKE_CASE (e.g., MAX_ROUNDS)
  • Private attributes: _leading_underscore (e.g., _internal_state)

Noematic Terminology

Term Usage
noema Semantic unit with query/key vectors — the fundamental atomic entity
node Network/graph vertex (use only in graph/network contexts)
agent Entity with perspective/agency — MUST have a role and execute tasks
field Collection of noemata with shared topology — NOT "cluster" or "group"
link Directed edge between noemata — NOT "edge", "connection", "wire"

Error Handling

  • Use custom exceptions for domain-specific errors
  • Never use bare except:
  • Use raise NewError("msg") from original_error for context
  • Log errors before raising

Async Code

  • Use async/await consistently
  • Use asyncio.gather() for concurrent operations
  • Use asyncio.create_task() for fire-and-forget
  • Use asyncio.timeout() or asyncio.wait_for() for timeouts
  • Never block the event loop with sync I/O

Testing

  • Use pytest with pytest-asyncio for async tests
  • Name tests: test_<method>_<expected_behavior>
  • Mock external dependencies (LLM APIs, file I/O)
  • Test both success and failure paths

Documentation

  • Use Google-style docstrings
  • Document all public APIs
  • Include type hints in docstrings

Project Documentation

Documentation Hierarchy

File Role Properties
FIRST_STEPS.md Execution on-ramp — "What do I do right now, in what order?" Linear, opinionated, prescriptive, short, cannot branch
dev_tasks.md Maintainer control surface — "What work exists, what's blocked?" Non-linear, can grow, can reference future phases, scope pressure management
implementation_plan.md Normative spec — "What does it mean for implementation to be correct?" Almost never changes casually
docs/invariants.md Formal system invariants — structural, temporal, interpretation 8 invariants with formal statements
docs/interpretation.md Mechanical interpretation specification Pseudocode, data structures, conflict resolution

Quick Reference

  • FIRST_STEPS.md — Keep frozen and ruthless. This is the strict commit-order plan. Do not skip steps.
  • dev_tasks.md — Let breathe and evolve. Broad context for future work.
  • implementation_plan.md — The authoritative technical specification.
  • docs/invariants.md — Required invariants all implementations must preserve.
  • docs/interpretation.md — How interpretation works mechanically.
  • docs/planning/ — Resource planning and operational details (non-normative).
  • docs/reference/ — Reference implementation sketches (non-normative).

Locked Files

These files are stable contracts. They may be clarified but should almost never change in meaning.

File Reason
src/noematics/core/interfaces.py Hard contract surface — downstream code and alternative implementations depend on this
src/noematics/core/mic.py Semantic anchor — reference MIC; invariant honesty depends on stability
docs/invariants.md Normative — formal system invariants
docs/interpretation.md Normative — mechanical semantics
docs/mic.md Normative — executable semantics and determinism guarantees
docs/architecture/system_overview.md Conceptual map — defines what exists, not how it’s built
docs/architecture/execution_layers.md Layer boundaries — prevents semantic leakage across layers
implementation_plan.md Meta-contract — delegates authority; structure is stable
FIRST_STEPS.md Commit-order discipline — protects project boot sequence
README.md External contract — project identity and intent

Contolled (but editable)

Changes require justification, not prohibition.

File Why
docs/roadmap/phases.md Roadmaps must evolve; already marked non-normative
docs/roadmap/risks.md Risk assessment should update as reality changes

Explicitly Not Locked (by design)

docs/architecture/*.md (except the two above) - Descriptive, extensible

docs/reference/** - Examples only

docs/testing/strategy.md - Guidance, not requirements

docs/rationale/** - Historical record

dev_tasks.md - Technical debt ledger (must change!)

Semantically Stable

These files may be edited for clarity, but not for meaning.

docs/architecture/data_flow.md

docs/architecture/extension_points.md

docs/architecture/data_structures.md

Project Structure

.
├── AGENTS.md
├── FIRST_STEPS.md
├── LICENSE
├── README.md
├── dev_tasks.md
├── docs
│   ├── architecture
│   │   ├── agents.md
│   │   ├── data_flow.md
│   │   ├── data_structures.md
│   │   ├── execution_layers.md
│   │   ├── extension_points.md
│   │   ├── manager_policy.md
│   │   ├── semantic_routing.md
│   │   ├── synchronization.md
│   │   └── system_overview.md
│   ├── interpretation.md
│   ├── invariants.md
│   ├── mic.md
│   ├── planning
│   │   └── resource_requirements.md
│   ├── rationale
│   │   ├── design_choices.md
│   │   └── rejected_alternatives.md
│   ├── reference
│   │   ├── agents_example.md
│   │   ├── dytopo.md
│   │   ├── framework_api.md
│   │   ├── llm_backends.md
│   │   ├── llm_integration.md
│   │   ├── semantic_routing_example.md
│   │   └── synchronization_example.md
│   ├── roadmap
│   │   ├── deferred_features.md
│   │   ├── phases.md
│   │   └── risks.md
│   └── testing
│       └── strategy.md
├── implementation_plan.md
├── pyproject.toml
├── src
│   ├── noematics
│   │   ├── __init__.py
│   │   ├── __pycache__
│   │   ├── core
│   │   │   ├── __init__.py
│   │   │   ├── __pycache__
│   │   │   ├── interfaces.py
│   │   │   └── mic.py
│   │   ├── llm
│   │   │   ├── __init__.py
│   │   │   └── interpretation.py
│   │   └── semantic
│   │       ├── __init__.py
│   │       ├── __pycache__
│   │       ├── dytopo.py
│   │       ├── encoder.py
│   │       ├── matcher.py
│   │       └── topology.py
│   └── noematics.egg-info
│       ├── PKG-INFO
│       ├── SOURCES.txt
│       ├── dependency_links.txt
│       └── top_level.txt
└── tests
    ├── __init__.py
    ├── __pycache__
    └── mic
        ├── __pycache__
        ├── test_dytopo.py
        └── test_minimal_core.py

Configuration

  • Use Pydantic BaseSettings for configuration
  • Support environment variables with env field
  • Store secrets in env vars, never in code

Common Patterns

Creating an Agent

from noematics.agents.factory import AgentFactory
from noematics.llm.openai import OpenAIBackend

backend = OpenAIBackend(api_key=os.getenv("OPENAI_API_KEY"))
agent = AgentFactory.create_agent(role="developer", agent_id="dev_1", llm_backend=backend)

Running a Task

import asyncio
from noematics.core.framework import NoematicsFramework

async def main():
    framework = NoematicsFramework(config)
    result = await framework.solve(task="Your task", agent_roles=["developer", "tester"], max_rounds=5)
    print(result.final_answer)

asyncio.run(main())

Key Dependencies

  • torch, transformers, sentence-transformers - ML/NLP
  • openai, httpx - LLM backends
  • networkx, scipy, numpy - Graph processing
  • pydantic - Data validation
  • pytest, pytest-asyncio - Testing
  • black, mypy, flake8 - Code quality

Notes for Agents

  • Run pytest before committing
  • Run black src/ before submitting
  • Check type safety with mypy src/
  • Use logging instead of print statements
  • Follow existing code patterns in the repository