# 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
```bash
python main.py abc abd ppqqrr --iterations 10
```
Arguments: `initial modified target [--iterations N] [--seed N] [--plot]`

### Run with GUI (requires matplotlib)
```bash
python gui.py [--seed N]
```

### Run with curses terminal UI
```bash
python curses_main.py abc abd xyz [--fps N] [--focus-on-slipnet] [--seed N]
```

### Run tests
```bash
python tests.py [distributions_file]
```

### Install as module
```bash
pip install -e .
```

Then use programmatically:
```python
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`.