Logic Lab

Python translations of creative coding examples using py5. Each simulation is organized by domain, demonstrating core computational creativity concepts: physics, steering behaviors, genetic algorithms, neural networks, fractals, cellular automata, tiling patterns, and mathematical systems.

MCP Server

Logic Lab is available as an MCP server for AI agents. Agents can search the Logic Lab manifest, find algorithms by visual intent or category, read short summaries, and fetch bounded source snippets for selected examples.

Option 1: Quick Start

If you just want to use the MCP server directly via Glama or your AI agent without cloning the repository, you can run it remotely using uvx.

Add the following to your AI tool's MCP

configuration:

{
  "mcpServers": {
    "logic-lab": {
      "command": "uvx",
      "args": [
        "--from",
        "logic-lab",
        "logic-lab-mcp"
      ]
    }
  }
}

Option 2: Manual Installation (For local development)

Requires uv. Clone this repository locally if you want to modify the algorithms or run the server from your local source.

git clone https://github.com/asamiile/logic-lab.git
cd logic-lab
uv sync

Registration (Local)

After manual installation, register the local server with your AI tool using the logic-lab-mcp command:

Claude Code:

claude mcp add logic-lab -- logic-lab-mcp

Codex:

codex mcp add logic-lab -- logic-lab-mcp

GitHub Copilot in VS Code (.vscode/mcp.json or user MCP settings):

{
  "servers": {
    "logic-lab": {
      "type": "stdio",
      "command": "logic-lab-mcp"
    }
  }
}

Cursor (.cursor/mcp.json or ~/.cursor/mcp.json):

{
  "mcpServers": {
    "logic-lab": {
      "type": "stdio",
      "command": "logic-lab-mcp"
    }
  }
}

Available Tools

303 algorithms across 11 domains are accessible via 6 MCP tools:

Recommended workflow: search_algorithms → get_algorithm_summary → get_algorithm

See src/logic_lab/mcp/README.md for full parameter reference, security notes, and resource endpoints.

Agent Conversation Example

User: I want to create flowing smoke with invisible force fields.

Agent: Running search_algorithms("flowing smoke invisible force fields")...

• steering_behaviors/flow_field.py — particles following a fluid vector field
• physics/fluid_simulation.py — grid-based fluid dynamics

Checking details with get_algorithm_summary("steering_behaviors/flow_field.py")... complexity: medium, concepts: [flow field, Perlin noise, autonomous agents]

Fetching source with get_algorithm("steering_behaviors/flow_field.py") to use as reference for implementation.

Algorithm Domains

• mathematical/ - Generative geometry, color harmony, noise functions, fractals
• physics/ - Particle systems, forces, spring physics, fluid dynamics, collision
• steering_behaviors/ - Autonomous agents, flocking, pathfinding, flow fields
• genetic_algorithms/ - Evolution, selection, crossover, mutation
• neuro_evolution/ - Neural networks evolved via genetic algorithms
• fractals/ - Recursive structures, space-filling curves, Mandelbrot sets
• cellular_automata/ - Rule-based systems, Game of Life, emergence
• tiling_patterns/ - Symmetry, tessellations, ornamental patterns
• research/ - Experimental systems combining multiple domains
• simulation/ - Prototype implementations and archived experiments
• shader/ - GLSL fragment shaders for TouchDesigner and UE5

Example: Autonomous Artwork Generation

py5-media-art — a project that uses the Logic Lab MCP server with Claude Code to autonomously generate py5 sketches. Claude searches Logic Lab for relevant algorithms, adapts them into new compositions, and optionally writes accompanying articles.

Gallery

Examples of generative art created with Logic Lab algorithms:

Development

To contribute new algorithms or fixes, see CONTRIBUTING.md for detailed guidelines on:

• Development setup with uv
• Algorithm addition workflow
• py5 code patterns and templates
• Testing requirements
• Conventional Commits specification
• Automated release process

Setup

Install dependencies:

uv sync

Running Tests

# Install dev dependencies
uv sync --group dev

# Run all tests
uv run pytest tests/

# Run with coverage
uv run pytest tests/ --cov=src/logic_lab

Code Quality

# Lint with ruff
uv run ruff check src/ tests/

# Format with black
uv run black src/ tests/

# Lint and fix
uv run ruff check --fix src/ tests/

Repository Structure

logic-lab/
├── src/logic_lab/                 # Package root
│   ├── __init__.py
│   ├── mcp/                       # MCP server for AI agent access
│   ├── physics/                   # Motion, forces, particles, simulations
│   ├── steering_behaviors/        # Autonomous agents, flow fields, flocking
│   ├── genetic_algorithms/        # Selection, mutation, evolutionary search
│   ├── neuro_evolution/           # Neural networks evolved via genetics
│   ├── fractals/                  # Recursion, trees, Koch curves, L-systems
│   ├── cellular_automata/         # Rule-based grids, lattice systems
│   ├── mathematical/              # Noise, curves, geometry, harmony
│   ├── tiling_patterns/           # Symmetry, tessellation, ornaments
│   ├── research/                  # Experimental and hybrid systems
│   ├── simulation/                # Prototypes and reference implementations
│   ├── shared/                    # Reusable utilities and helpers
│   └── shader/                    # GLSL shader experiments
├── tests/                         # Pytest test suite
├── CONTRIBUTING.md                # Contributor guidelines and conventions
├── CHANGELOG.md                   # Version history and release notes
├── pyproject.toml                 # Package configuration and dependencies
└── .github/workflows/
    ├── test.yml                   # CI: lint and test automation
    └── release.yml                # CD: automated releases with release-please

Reference

• The Nature of Code
• Pythonではじめるオープンエンドな進化的アルゴリズム
• 数学から創るジェネラティブアート
• リアルタイムグラフィックスの数学

License

Author

Asami.K

If you find this helpful, consider supporting the work: