copycat/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Python implementation of Douglas Hofstadter and Melanie Mitchell's Copycat algorithm for analogical reasoning. Given a pattern like "abc → abd", it finds analogous transformations for new strings (e.g., "ppqqrr → ppqqss").

Python Environment

Use Anaconda Python:

C:\Users\alexa\anaconda3\python.exe

Common Commands

Run the main program

python main.py abc abd ppqqrr --iterations 10

Arguments: initial modified target [--iterations N] [--seed N] [--plot]

Run with GUI (requires matplotlib)

python gui.py [--seed N]

Run with curses terminal UI

python curses_main.py abc abd xyz [--fps N] [--focus-on-slipnet] [--seed N]

Run tests

python tests.py [distributions_file]

Install as module

pip install -e .

Then use programmatically:

from copycat import Copycat
Copycat().run('abc', 'abd', 'ppqqrr', 10)

Architecture (FARG Components)

The system uses the Fluid Analogies Research Group (FARG) architecture with four main components that interact each step:

Copycat (copycat/copycat.py)

Central orchestrator that coordinates the main loop. Every 5 codelets, it updates the workspace, slipnet activations, and temperature.

Slipnet (copycat/slipnet.py)

A semantic network of concepts (nodes) and relationships (links). Contains:

• Letter concepts (a-z), numbers (1-5)
• Structural concepts: positions (leftmost, rightmost), directions (left, right)
• Bond/group types: predecessor, successor, sameness
• Activation spreads through the network during reasoning

Coderack (copycat/coderack.py)

A probabilistic priority queue of "codelets" (small procedures). Codelets are chosen stochastically based on urgency. All codelet behaviors are implemented in copycat/codeletMethods.py (the largest file at ~1100 lines).

Workspace (copycat/workspace.py)

The "working memory" containing:

• Three strings: initial, modified, target (and the answer being constructed)
• Structures built during reasoning: bonds, groups, correspondences, rules

Temperature (copycat/temperature.py)

Controls randomness in decision-making. High temperature = more random exploration; low temperature = more deterministic choices. Temperature decreases as the workspace becomes more organized.

Key Workspace Structures

• Bond (bond.py): Links between adjacent letters (e.g., successor relationship between 'a' and 'b')
• Group (group.py): Collection of letters with a common bond type (e.g., "abc" as a successor group)
• Correspondence (correspondence.py): Mapping between objects in different strings
• Rule (rule.py): The transformation rule discovered (e.g., "replace rightmost letter with successor")

Output

Results show answer frequencies and quality metrics:

• count: How often Copycat chose that answer (higher = more obvious)
• avgtemp: Average final temperature (lower = more elegant solution)
• avgtime: Average codelets run to reach answer

Logs written to output/copycat.log, answers saved to output/answers.csv.