docs: add comprehensive README files for all components

copycat/bond_README.md

@@ -0,0 +1,54 @@
+# README_bond.md
+
+## Overview
+`bond.py` implements the Bond system, a key component of the Copycat system that manages the relationships between objects in strings. It handles the creation, evaluation, and management of bonds that represent meaningful connections between objects based on their properties and relationships.
+
+## Core Components
+- `Bond` class: Main class that represents a bond between objects
+- Bond evaluation system
+- Bond compatibility management
+
+## Key Features
+- Manages bonds between objects in strings
+- Evaluates bond strength based on multiple factors
+- Handles bond direction and category
+- Supports bond flipping and versioning
+- Manages bond compatibility and support
+
+## Bond Components
+- `source`: Source object of the bond
+- `destination`: Destination object of the bond
+- `category`: Category of the bond
+- `facet`: Aspect of the bond
+- `directionCategory`: Direction of the bond
+- `sourceDescriptor`: Descriptor of the source object
+- `destinationDescriptor`: Descriptor of the destination object
+
+## Main Methods
+- `updateInternalStrength()`: Calculate internal bond strength
+- `updateExternalStrength()`: Calculate external bond strength
+- `buildBond()`: Create and establish bond
+- `breakBond()`: Remove bond
+- `localSupport()`: Calculate local support
+- `numberOfLocalSupportingBonds()`: Count supporting bonds
+- `sameCategories()`: Compare bond categories
+- `localDensity()`: Calculate local bond density
+
+## Bond Types
+- Letter category bonds
+- Direction-based bonds
+- Category-based bonds
+- Flipped bonds
+- Modified bonds
+
+## Dependencies
+- Requires `workspaceStructure` module
+- Used by the main `copycat` module
+
+## Notes
+- Bonds are evaluated based on member compatibility and facet factors
+- The system supports both same-type and different-type bonds
+- Bonds can have direction categories (left, right)
+- The system handles bond compatibility and support
+- Bonds can be flipped to create alternative versions
+- Local density and support factors influence bond strength 

copycat/codeletMethods_README.md

@@ -0,0 +1,51 @@
+# Codelet Methods
+
+## Overview
+The codelet methods system is a core component of the Copycat architecture that implements the various operations and behaviors that codelets can perform. This system defines the actual implementation of codelet behaviors that drive the analogical reasoning process.
+
+## Key Components
+- Codelet operation implementations
+- Behavior definitions
+- Action handlers
+- State management
+- Event processing
+
+## Codelet Types
+1. **Workspace Codelets**
+   - Object creation and modification
+   - Structure building
+   - Relationship formation
+   - Group management
+
+2. **Slipnet Codelets**
+   - Concept activation
+   - Node management
+   - Link formation
+   - Activation spreading
+
+3. **Correspondence Codelets**
+   - Mapping creation
+   - Relationship matching
+   - Structure alignment
+   - Similarity assessment
+
+## Usage
+Codelet methods are called by the coderack system when codelets are executed:
+
+```python
+# Example of a codelet method implementation
+def some_codelet_method(workspace, slipnet, coderack):
+    # Perform operations
+    # Update state
+    # Create new codelets
+```
+
+## Dependencies
+- Python 3.x
+- No external dependencies required
+
+## Related Components
+- Coderack: Manages codelet execution
+- Workspace: Provides objects to operate on
+- Slipnet: Provides conceptual knowledge
+- Correspondence: Manages mappings between structures 

copycat/codelet_README.md

@@ -0,0 +1,62 @@
+# Codelet System
+
+## Overview
+The codelet system is a fundamental component of the Copycat architecture that defines the basic structure and behavior of codelets. Codelets are small, specialized agents that perform specific operations in the workspace, forming the basis of the system's parallel processing capabilities.
+
+## Key Features
+- Codelet structure
+- Behavior definition
+- Priority management
+- State tracking
+- Execution control
+
+## Codelet Types
+1. **Basic Codelets**
+   - Scout codelets
+   - Builder codelets
+   - Evaluator codelets
+   - Breaker codelets
+
+2. **Specialized Codelets**
+   - Group codelets
+   - Bond codelets
+   - Correspondence codelets
+   - Rule codelets
+
+3. **Control Codelets**
+   - Temperature codelets
+   - Pressure codelets
+   - Urgency codelets
+   - Cleanup codelets
+
+## Usage
+Codelets are created and managed through the codelet system:
+
+```python
+# Create a codelet
+codelet = Codelet(name, priority)
+
+# Set behavior
+''''
+The behavior parameter would typically be a reference to one of the **many codelet methods defined in codeletMethods.py**.
+For example, a codelet might be assigned a behavior like:
+build_group - to create a new group of related elements
+evaluate_bond - to assess the strength of a bond
+scout_for_correspondence - to look for potential mappings between structures
+The behavior is what gives each codelet its purpose and role in the system's parallel processing architecture. When the codelet is executed via codelet.run(), it performs this assigned behavior in the context of the current workspace state.
+'''
+codelet.set_behavior(behavior)
+
+# Execute codelet
+result = codelet.run()
+```
+
+## Dependencies
+- Python 3.x
+- No external dependencies required
+
+## Related Components
+- Coderack: Manages codelet execution
+- CodeletMethods: Provides codelet behaviors
+- Workspace: Environment for codelets
+- Temperature: Influences codelet behavior 

copycat/coderack_README.md

@@ -0,0 +1,49 @@
+# README_coderack.md
+
+## Overview
+`coderack.py` implements the Coderack, a key component of the Copycat system that manages the execution of codelets (small, focused procedures) that drive the analogical reasoning process. It handles the posting, selection, and execution of codelets based on their urgency and the current state of the system.
+
+## Core Components
+- `Coderack` class: Main class that manages codelet execution
+- Codelet management system
+- Urgency-based codelet selection
+
+## Key Features
+- Manages a collection of codelets (small procedures)
+- Implements urgency-based codelet selection
+- Supports both top-down and bottom-up codelet posting
+- Handles codelet execution and removal
+- Manages rule, correspondence, description, and group proposals
+
+## Codelet Types
+- Breaker codelets
+- Description codelets (top-down and bottom-up)
+- Bond codelets (top-down and bottom-up)
+- Group codelets (top-down and whole-string)
+- Rule codelets (scout, strength-tester, builder, translator)
+- Correspondence codelets (bottom-up and important-object)
+- Replacement finder codelets
+
+## Main Methods
+- `post(codelet)`: Add a codelet to the coderack
+- `chooseAndRunCodelet()`: Select and execute a codelet
+- `postTopDownCodelets()`: Post codelets from activated slipnet nodes
+- `postBottomUpCodelets()`: Post codelets based on workspace state
+- `proposeRule()`: Create and post a rule proposal
+- `proposeCorrespondence()`: Create and post a correspondence proposal
+- `proposeDescription()`: Create and post a description proposal
+- `proposeGroup()`: Create and post a group proposal
+- `proposeBond()`: Create and post a bond proposal
+
+## Dependencies
+- Requires `codeletMethods` module
+- Uses `bond`, `codelet`, `correspondence`, `description`, `group`, and `rule` modules
+- Uses `logging` for debug output
+- Uses `math` for urgency calculations
+
+## Notes
+- Codelets are organized by urgency bins
+- The system maintains a maximum of 100 codelets
+- Codelet selection is influenced by temperature and workspace state
+- The system supports both deterministic and probabilistic codelet posting
+- Codelet urgency is calculated based on various factors including conceptual depth 

copycat/conceptMapping_README.md

@@ -0,0 +1,54 @@
+# Concept Mapping System
+
+## Overview
+The concept mapping system is a crucial component of the Copycat architecture that manages the mapping between concepts and their representations in the workspace. This system handles the translation between abstract concepts and concrete instances.
+
+## Key Features
+- Concept-to-instance mapping
+- Mapping validation
+- Relationship tracking
+- State management
+- Event handling
+
+## Mapping Types
+1. **Direct Mappings**
+   - Letter-to-concept mappings
+   - Number-to-concept mappings
+   - Symbol-to-concept mappings
+   - Pattern-to-concept mappings
+
+2. **Structural Mappings**
+   - Group-to-concept mappings
+   - Bond-to-concept mappings
+   - Hierarchy-to-concept mappings
+   - Pattern-to-concept mappings
+
+3. **Special Mappings**
+   - Rule-to-concept mappings
+   - Context-to-concept mappings
+   - Meta-concept mappings
+   - Derived mappings
+
+## Usage
+Concept mappings are created and managed through the mapping system:
+
+```python
+# Create a new concept mapping
+mapping = ConceptMapping(source, target)
+
+# Access mapping properties
+strength = mapping.get_strength()
+
+# Modify mapping state
+mapping.set_strength(new_value)
+```
+
+## Dependencies
+- Python 3.x
+- No external dependencies required
+
+## Related Components
+- Slipnet: Provides concepts to map
+- Workspace: Provides instances to map to
+- Codelets: Operate on mappings
+- Correspondence: Manages mapping relationships 

copycat/copycat_README.md

@@ -0,0 +1,40 @@
+# README_copycat.md
+
+## Overview
+`copycat.py` is the core module of the Copycat system, implementing the main analogical reasoning algorithm. It coordinates the interaction between various components like the workspace, slipnet, coderack, and temperature system.
+
+## Core Components
+- `Copycat` class: Main class that orchestrates the analogical reasoning process
+- `Reporter` class: Base class for defining different types of reporters (GUI, curses, etc.)
+
+## Key Features
+- Implements the main Copycat algorithm for analogical reasoning
+- Manages the interaction between different system components
+- Supports multiple interfaces (GUI, curses, command-line)
+- Provides temperature-based control of the reasoning process
+- Handles multiple iterations and answer collection
+
+## Main Methods
+- `run(initial, modified, target, iterations)`: Run the algorithm for a specified number of iterations
+- `runGUI()`: Run the algorithm with graphical interface
+- `run_forever(initial, modified, target)`: Run the algorithm continuously
+- `runTrial()`: Run a single trial of the algorithm
+- `step()`: Execute a single step of the algorithm
+- `update_workspace(currentTime)`: Update all workspace components
+
+## Dependencies
+- Requires `coderack`, `randomness`, `slipnet`, `temperature`, and `workspace` modules
+- Uses `pprint` for pretty printing results
+- Optional GUI support through the `gui` module
+
+## Usage
+The module is typically used through one of the interface modules:
+- `main.py` for command-line interface
+- `gui.py` for graphical interface
+- `curses_main.py` for terminal-based interface
+
+## Notes
+- The system uses a temperature-based control mechanism to guide the reasoning process
+- Results include answer statistics, temperature, and time metrics
+- The system supports both single-run and continuous operation modes
+- The reporter system allows for flexible output handling 

copycat/correspondence_README.md

@@ -0,0 +1,51 @@
+# README_correspondence.md
+
+## Overview
+`correspondence.py` implements the Correspondence system, a key component of the Copycat system that manages the mapping relationships between objects in the initial and target strings. It handles the creation, evaluation, and management of correspondences that link objects based on their properties and relationships.
+
+## Core Components
+- `Correspondence` class: Main class that represents a mapping between objects
+- Concept mapping system
+- Correspondence strength evaluation
+
+## Key Features
+- Manages mappings between objects in initial and target strings
+- Evaluates correspondence strength based on multiple factors
+- Handles concept slippages and mappings
+- Supports both direct and accessory concept mappings
+- Manages correspondence compatibility and support
+
+## Correspondence Components
+- `objectFromInitial`: Object from the initial string
+- `objectFromTarget`: Object from the target string
+- `conceptMappings`: List of concept mappings
+- `accessoryConceptMappings`: Additional concept mappings
+- `flipTargetObject`: Flag for target object flipping
+
+## Main Methods
+- `updateInternalStrength()`: Calculate internal correspondence strength
+- `updateExternalStrength()`: Calculate external correspondence strength
+- `buildCorrespondence()`: Create and establish correspondence
+- `breakCorrespondence()`: Remove correspondence
+- `incompatible()`: Check correspondence compatibility
+- `supporting()`: Check if correspondence supports another
+- `internallyCoherent()`: Check internal coherence
+
+## Concept Mapping Types
+- Distinguishing mappings
+- Relevant distinguishing mappings
+- Bond mappings
+- Direction mappings
+- Symmetric mappings
+
+## Dependencies
+- Requires `conceptMapping`, `group`, `letter`, and `workspaceStructure` modules
+- Uses `formulas` for mapping calculations
+- Used by the main `copycat` module
+
+## Notes
+- Correspondences are evaluated based on concept mapping strength and coherence
+- The system supports both direct and indirect concept mappings
+- Correspondences can be incompatible with each other
+- The system handles both letter and group correspondences
+- Concept slippages are tracked and managed 

copycat/curses_reporter_README.md

@@ -0,0 +1,55 @@
+# Curses Reporter System
+
+## Overview
+The curses reporter system is a visualization component of the Copycat architecture that provides a terminal-based user interface for monitoring and debugging the system's operation. This system uses the curses library to create an interactive display of the system's state.
+
+## Key Features
+- Real-time state display
+- Interactive monitoring
+- Debug information
+- System metrics visualization
+- User input handling
+
+## Display Components
+1. **Main Display**
+   - Workspace visualization
+   - Slipnet state
+   - Coderack status
+   - Correspondence view
+
+2. **Debug Panels**
+   - Codelet execution
+   - Activation levels
+   - Mapping strengths
+   - Error messages
+
+3. **Control Interface**
+   - User commands
+   - System controls
+   - Display options
+   - Navigation
+
+## Usage
+The curses reporter is used to monitor the system:
+
+```python
+# Initialize the reporter
+reporter = CursesReporter()
+
+# Update the display
+reporter.update_display()
+
+# Handle user input
+reporter.process_input()
+```
+
+## Dependencies
+- Python 3.x
+- curses library
+- No other external dependencies required
+
+## Related Components
+- Workspace: Provides state to display
+- Slipnet: Provides activation information
+- Coderack: Provides execution status
+- Correspondence: Provides mapping information 

copycat/description_README.md

@@ -0,0 +1,54 @@
+# Description System
+
+## Overview
+The description system is a core component of the Copycat architecture that manages the representation and generation of descriptions for objects and structures in the workspace. This system provides detailed characterizations of elements in the analogical reasoning process.
+
+## Key Features
+- Object description
+- Structure characterization
+- Property management
+- Relationship description
+- State representation
+
+## Description Types
+1. **Basic Descriptions**
+   - Object properties
+   - Structure features
+   - Relationship details
+   - State information
+
+2. **Composite Descriptions**
+   - Group characteristics
+   - Pattern descriptions
+   - Hierarchical details
+   - Context information
+
+3. **Special Descriptions**
+   - Rule descriptions
+   - Mapping details
+   - Meta-descriptions
+   - Derived characteristics
+
+## Usage
+Descriptions are created and managed through the description system:
+
+```python
+# Create a description
+desc = Description(object)
+
+# Add properties
+desc.add_property('property_name', value)
+
+# Generate description
+text = desc.generate()
+```
+
+## Dependencies
+- Python 3.x
+- No external dependencies required
+
+## Related Components
+- Workspace: Contains described objects
+- WorkspaceObject: Objects to describe
+- Codelets: Use descriptions
+- Correspondence: Maps descriptions 

copycat/formulas_README.md

@@ -0,0 +1,54 @@
+# Formulas System
+
+## Overview
+The formulas system is a utility component of the Copycat architecture that provides mathematical and logical formulas for various calculations and evaluations throughout the system. This system implements core mathematical operations used in the analogical reasoning process.
+
+## Key Features
+- Mathematical operations
+- Probability calculations
+- Distance metrics
+- Similarity measures
+- Utility functions
+
+## Formula Types
+1. **Mathematical Formulas**
+   - Probability calculations
+   - Distance metrics
+   - Similarity scores
+   - Weight computations
+
+2. **Evaluation Formulas**
+   - Fitness functions
+   - Quality measures
+   - Comparison metrics
+   - Ranking formulas
+
+3. **Special Formulas**
+   - Temperature adjustments
+   - Activation functions
+   - Threshold calculations
+   - Normalization methods
+
+## Usage
+Formulas are used throughout the system:
+
+```python
+# Calculate probability
+prob = formulas.calculate_probability(event)
+
+# Compute similarity
+sim = formulas.compute_similarity(obj1, obj2)
+
+# Evaluate fitness
+fitness = formulas.evaluate_fitness(solution)
+```
+
+## Dependencies
+- Python 3.x
+- No external dependencies required
+
+## Related Components
+- Temperature: Uses formulas for calculations
+- Slipnet: Uses formulas for activation
+- Workspace: Uses formulas for evaluation
+- Statistics: Uses formulas for analysis 

copycat/group_README.md

@@ -0,0 +1,53 @@
+# README_group.md
+
+## Overview
+`group.py` implements the Group system, a key component of the Copycat system that manages the grouping of objects in strings. It handles the creation, evaluation, and management of groups that represent meaningful collections of objects based on their properties and relationships.
+
+## Core Components
+- `Group` class: Main class that represents a group of objects
+- Group evaluation system
+- Group description management
+
+## Key Features
+- Manages groups of objects in strings
+- Evaluates group strength based on multiple factors
+- Handles group descriptions and bond descriptions
+- Supports group flipping and versioning
+- Manages group compatibility and support
+
+## Group Components
+- `groupCategory`: Category of the group
+- `directionCategory`: Direction of the group
+- `facet`: Aspect of the group
+- `objectList`: List of objects in the group
+- `bondList`: List of bonds in the group
+- `descriptions`: List of group descriptions
+- `bondDescriptions`: List of bond descriptions
+
+## Main Methods
+- `updateInternalStrength()`: Calculate internal group strength
+- `updateExternalStrength()`: Calculate external group strength
+- `buildGroup()`: Create and establish group
+- `breakGroup()`: Remove group
+- `localSupport()`: Calculate local support
+- `numberOfLocalSupportingGroups()`: Count supporting groups
+- `sameGroup()`: Compare groups for equality
+
+## Group Types
+- Single letter groups
+- Multi-letter groups
+- Direction-based groups
+- Category-based groups
+- Length-based groups
+
+## Dependencies
+- Requires `description`, `workspaceObject`, and `formulas` modules
+- Used by the main `copycat` module
+
+## Notes
+- Groups are evaluated based on bond association and length
+- The system supports both single and multi-object groups
+- Groups can have multiple descriptions and bond descriptions
+- The system handles group compatibility and support
+- Groups can be flipped to create alternative versions
+- Length descriptions are probabilistically added based on temperature 

copycat/io_README.md

@@ -0,0 +1,54 @@
+# Input/Output System
+
+## Overview
+The input/output system is a utility component of the Copycat architecture that handles file and data input/output operations. This system provides interfaces for reading and writing data to and from various sources.
+
+## Key Features
+- File operations
+- Data parsing
+- Format conversion
+- Error handling
+- State management
+
+## Operation Types
+1. **File Operations**
+   - File reading
+   - File writing
+   - File management
+   - Path handling
+
+2. **Data Operations**
+   - Data parsing
+   - Format conversion
+   - Data validation
+   - Error handling
+
+3. **Special Operations**
+   - Configuration loading
+   - Logging
+   - Debug output
+   - State persistence
+
+## Usage
+I/O operations are performed through the I/O system:
+
+```python
+# Read from a file
+data = io.read_file(file_path)
+
+# Write to a file
+io.write_file(file_path, data)
+
+# Parse data
+parsed = io.parse_data(data)
+```
+
+## Dependencies
+- Python 3.x
+- No external dependencies required
+
+## Related Components
+- Workspace: Uses I/O for data loading
+- Statistics: Uses I/O for logging
+- Curses Reporter: Uses I/O for display
+- Problem: Uses I/O for problem loading 

copycat/letter_README.md

@@ -0,0 +1,54 @@
+# Letter System
+
+## Overview
+The letter system is a specialized component of the Copycat architecture that handles the representation and manipulation of individual letters and characters in the workspace. This system manages the properties and behaviors of letter objects in the analogical reasoning process.
+
+## Key Features
+- Letter representation
+- Character properties
+- Letter manipulation
+- Pattern matching
+- State management
+
+## Letter Types
+1. **Basic Letters**
+   - Alphabetic characters
+   - Numeric characters
+   - Special characters
+   - Whitespace
+
+2. **Structured Letters**
+   - Grouped letters
+   - Bonded letters
+   - Hierarchical letters
+   - Pattern letters
+
+3. **Special Letters**
+   - Rule letters
+   - Mapping letters
+   - Context letters
+   - Meta-letters
+
+## Usage
+Letter operations are performed through the letter system:
+
+```python
+# Create a letter
+letter = Letter(char, properties)
+
+# Access letter properties
+char = letter.get_char()
+
+# Modify letter state
+letter.set_properties(new_properties)
+```
+
+## Dependencies
+- Python 3.x
+- No external dependencies required
+
+## Related Components
+- Workspace: Contains letter objects
+- WorkspaceObject: Base class for letters
+- Codelets: Operate on letters
+- Correspondence: Maps between letters 

copycat/plot_README.md

@@ -0,0 +1,56 @@
+# Plot System
+
+## Overview
+The plot system is a visualization component of the Copycat architecture that provides plotting and graphing capabilities for analyzing and displaying system data. This system helps in visualizing various metrics and relationships in the analogical reasoning process.
+
+## Key Features
+- Data visualization
+- Graph generation
+- Metric plotting
+- Analysis display
+- State management
+
+## Plot Types
+1. **Performance Plots**
+   - Activation curves
+   - Execution timelines
+   - Success rates
+   - Error distributions
+
+2. **System Plots**
+   - Object counts
+   - Link distributions
+   - State changes
+   - Memory usage
+
+3. **Analysis Plots**
+   - Pattern frequencies
+   - Relationship maps
+   - Similarity matrices
+   - Correlation graphs
+
+## Usage
+Plots are generated through the plot system:
+
+```python
+# Create a plot
+plot = Plot(data, plot_type)
+
+# Configure plot
+plot.set_title("Title")
+plot.set_labels("X", "Y")
+
+# Display plot
+plot.show()
+```
+
+## Dependencies
+- Python 3.x
+- matplotlib library
+- No other external dependencies required
+
+## Related Components
+- Statistics: Provides data for plotting
+- Curses Reporter: Uses plots for display
+- Workspace: Provides object data
+- Slipnet: Provides activation data 

copycat/problem_README.md

@@ -0,0 +1,54 @@
+# Problem System
+
+## Overview
+The problem system is a core component of the Copycat architecture that manages the representation and handling of analogical reasoning problems. This system defines the structure and properties of problems that the system attempts to solve.
+
+## Key Features
+- Problem representation
+- Problem loading
+- Problem validation
+- Solution tracking
+- State management
+
+## Problem Types
+1. **Basic Problems**
+   - String problems
+   - Pattern problems
+   - Rule problems
+   - Mapping problems
+
+2. **Composite Problems**
+   - Multi-step problems
+   - Hierarchical problems
+   - Network problems
+   - Context problems
+
+3. **Special Problems**
+   - Test problems
+   - Debug problems
+   - Meta-problems
+   - Derived problems
+
+## Usage
+Problems are created and managed through the problem system:
+
+```python
+# Create a problem
+problem = Problem(initial_state, target_state)
+
+# Load a problem
+problem = Problem.load_from_file(file_path)
+
+# Solve a problem
+solution = problem.solve()
+```
+
+## Dependencies
+- Python 3.x
+- No external dependencies required
+
+## Related Components
+- Workspace: Contains problem state
+- Slipnet: Provides concepts for solving
+- Codelets: Operate on problems
+- Correspondence: Maps problem elements 

copycat/randomness_README.md

@@ -0,0 +1,54 @@
+# Randomness System
+
+## Overview
+The randomness system is a utility component of the Copycat architecture that provides controlled random number generation and probabilistic operations. This system ensures consistent and reproducible random behavior across the analogical reasoning process.
+
+## Key Features
+- Random number generation
+- Probability distributions
+- State management
+- Seed control
+- Reproducibility
+
+## Operation Types
+1. **Basic Operations**
+   - Random number generation
+   - Probability sampling
+   - Distribution selection
+   - State initialization
+
+2. **Advanced Operations**
+   - Weighted selection
+   - Distribution mixing
+   - State transitions
+   - Pattern generation
+
+3. **Special Operations**
+   - Seed management
+   - State persistence
+   - Debug control
+   - Test reproducibility
+
+## Usage
+Random operations are performed through the randomness system:
+
+```python
+# Generate a random number
+value = randomness.random()
+
+# Sample from a distribution
+sample = randomness.sample(distribution)
+
+# Set random seed
+randomness.set_seed(seed)
+```
+
+## Dependencies
+- Python 3.x
+- No external dependencies required
+
+## Related Components
+- Codelets: Use randomness for selection
+- Temperature: Uses randomness for control
+- Statistics: Uses randomness for sampling
+- Workspace: Uses randomness for operations 

copycat/replacement_README.md

@@ -0,0 +1,54 @@
+# Replacement System
+
+## Overview
+The replacement system is a utility component of the Copycat architecture that manages the substitution and replacement of objects and structures in the workspace. This system handles the transformation of elements during the analogical reasoning process.
+
+## Key Features
+- Object replacement
+- Structure transformation
+- Pattern substitution
+- State management
+- History tracking
+
+## Operation Types
+1. **Basic Operations**
+   - Element replacement
+   - Pattern substitution
+   - Structure transformation
+   - State updates
+
+2. **Advanced Operations**
+   - Chain replacements
+   - Group transformations
+   - Context updates
+   - History tracking
+
+3. **Special Operations**
+   - Rule application
+   - Mapping translation
+   - Meta-replacements
+   - Derived transformations
+
+## Usage
+Replacements are performed through the replacement system:
+
+```python
+# Replace an object
+new_obj = replacement.replace(old_obj, new_obj)
+
+# Apply a transformation
+result = replacement.transform(obj, rule)
+
+# Track changes
+history = replacement.get_history()
+```
+
+## Dependencies
+- Python 3.x
+- No external dependencies required
+
+## Related Components
+- Workspace: Contains objects to replace
+- Rule: Provides replacement rules
+- Correspondence: Maps replacements
+- Codelets: Execute replacements 

copycat/rule_README.md

@@ -0,0 +1,47 @@
+# README_rule.md
+
+## Overview
+`rule.py` implements the Rule system, a key component of the Copycat system that manages the transformation rules used in analogical reasoning. It handles the creation, evaluation, and application of rules that describe how to transform strings based on their properties and relationships.
+
+## Core Components
+- `Rule` class: Main class that represents a transformation rule
+- Rule evaluation system
+- Rule translation and application system
+
+## Key Features
+- Defines transformation rules with facets, descriptors, categories, and relations
+- Evaluates rule strength based on multiple factors
+- Supports rule translation through concept slippages
+- Handles string transformations based on rules
+- Manages rule compatibility with correspondences
+
+## Rule Components
+- `facet`: The aspect of the object to change (e.g., length)
+- `descriptor`: The property being changed
+- `category`: The type of object being changed
+- `relation`: The transformation to apply
+
+## Main Methods
+- `updateInternalStrength()`: Calculate rule strength
+- `updateExternalStrength()`: Update external strength
+- `activateRuleDescriptions()`: Activate rule-related concepts
+- `buildTranslatedRule()`: Apply rule to target string
+- `incompatibleRuleCorrespondence()`: Check rule-correspondence compatibility
+- `ruleEqual()`: Compare rules for equality
+
+## Rule Types
+- Length-based rules (predecessor, successor)
+- Character-based rules (predecessor, successor)
+- Category-based rules
+
+## Dependencies
+- Requires `workspaceStructure` and `formulas` modules
+- Uses `logging` for debug output
+- Used by the main `copycat` module
+
+## Notes
+- Rules are evaluated based on conceptual depth and descriptor sharing
+- Rule strength is calculated using weighted averages
+- Rules can be translated through concept slippages
+- The system supports both single-character and length-based transformations
+- Rules can be incompatible with certain correspondences 

copycat/sliplink_README.md

@@ -0,0 +1,54 @@
+# Sliplink System
+
+## Overview
+The sliplink system is a core component of the Copycat architecture that manages the connections between nodes in the slipnet. This system handles the creation, modification, and traversal of links between conceptual nodes in the network.
+
+## Key Features
+- Link representation
+- Connection management
+- Weight handling
+- State tracking
+- Event processing
+
+## Link Types
+1. **Basic Links**
+   - Category links
+   - Property links
+   - Instance links
+   - Similarity links
+
+2. **Structural Links**
+   - Hierarchy links
+   - Composition links
+   - Association links
+   - Pattern links
+
+3. **Special Links**
+   - Rule links
+   - Context links
+   - Meta-links
+   - Derived links
+
+## Usage
+Sliplinks are created and managed through the sliplink system:
+
+```python
+# Create a sliplink
+link = Sliplink(source_node, target_node, weight)
+
+# Access link properties
+weight = link.get_weight()
+
+# Modify link state
+link.set_weight(new_weight)
+```
+
+## Dependencies
+- Python 3.x
+- No external dependencies required
+
+## Related Components
+- Slipnet: Contains sliplinks
+- Slipnode: Connected by sliplinks
+- Codelets: Use sliplinks for traversal
+- Workspace: Uses links for relationships 

copycat/slipnet_README.md

@@ -0,0 +1,51 @@
+# README_slipnet.md
+
+## Overview
+`slipnet.py` implements the Slipnet, a key component of the Copycat system that represents the conceptual network of relationships between different concepts. It manages a network of nodes (concepts) and links (relationships) that are used in analogical reasoning.
+
+## Core Components
+- `Slipnet` class: Main class that manages the conceptual network
+- Network of `Slipnode` objects representing concepts
+- Network of `Sliplink` objects representing relationships
+
+## Key Features
+- Manages a network of conceptual nodes and their relationships
+- Handles activation spreading between nodes
+- Supports both slip and non-slip links
+- Implements various types of relationships:
+  - Letter categories
+  - String positions
+  - Alphabetic positions
+  - Directions
+  - Bond types
+  - Group types
+  - Other relations
+
+## Node Types
+- Letters (a-z)
+- Numbers (1-5)
+- String positions (leftmost, rightmost, middle, single, whole)
+- Alphabetic positions (first, last)
+- Directions (left, right)
+- Bond types (predecessor, successor, sameness)
+- Group types (predecessorGroup, successorGroup, samenessGroup)
+- Categories (letterCategory, stringPositionCategory, etc.)
+
+## Link Types
+- Slip links (lateral connections)
+- Non-slip links (fixed connections)
+- Category links (hierarchical connections)
+- Instance links (specific examples)
+- Property links (attributes)
+- Opposite links (antonyms)
+
+## Dependencies
+- Requires `slipnode` and `sliplink` modules
+- Used by the main `copycat` module
+
+## Notes
+- The network is initialized with predefined nodes and links
+- Activation spreads through the network during reasoning
+- Some nodes are initially clamped to high activation
+- The network supports both hierarchical and lateral relationships
+- The system uses conceptual depth to determine link strengths 

copycat/slipnode_README.md

@@ -0,0 +1,54 @@
+# Slipnode System
+
+## Overview
+The slipnode system is a fundamental component of the Copycat architecture that implements the nodes in the slipnet. Slipnodes represent concepts and their relationships in the conceptual network, forming the basis for analogical reasoning.
+
+## Key Features
+- Concept representation
+- Activation management
+- Link formation
+- State tracking
+- Event handling
+
+## Node Types
+1. **Concept Nodes**
+   - Letter concepts
+   - Number concepts
+   - Relationship concepts
+   - Category concepts
+
+2. **Structural Nodes**
+   - Group concepts
+   - Bond concepts
+   - Hierarchy concepts
+   - Pattern concepts
+
+3. **Special Nodes**
+   - Rule nodes
+   - Mapping nodes
+   - Context nodes
+   - Meta-concept nodes
+
+## Usage
+Slipnodes are created and managed through the slipnet system:
+
+```python
+# Create a new slipnode
+node = Slipnode(name, initial_activation)
+
+# Access node properties
+activation = node.get_activation()
+
+# Modify node state
+node.set_activation(new_value)
+```
+
+## Dependencies
+- Python 3.x
+- No external dependencies required
+
+## Related Components
+- Slipnet: Main container for slipnodes
+- Sliplinks: Connect slipnodes
+- Codelets: Operate on slipnodes
+- Workspace: Provides context for node activation 

copycat/statistics_README.md

@@ -0,0 +1,54 @@
+# Statistics System
+
+## Overview
+The statistics system is a utility component of the Copycat architecture that collects and analyzes various metrics and statistics about the system's operation. This system helps in understanding and debugging the analogical reasoning process.
+
+## Key Features
+- Performance metrics collection
+- Statistical analysis
+- Data aggregation
+- Reporting utilities
+- Debugging support
+
+## Metric Types
+1. **Performance Metrics**
+   - Codelet execution counts
+   - Activation levels
+   - Mapping strengths
+   - Processing times
+
+2. **System Metrics**
+   - Memory usage
+   - Object counts
+   - Link counts
+   - State changes
+
+3. **Analysis Metrics**
+   - Success rates
+   - Error rates
+   - Pattern frequencies
+   - Relationship distributions
+
+## Usage
+Statistics are collected and analyzed through the statistics system:
+
+```python
+# Record a statistic
+statistics.record_metric('metric_name', value)
+
+# Get statistical analysis
+analysis = statistics.analyze_metric('metric_name')
+
+# Generate report
+report = statistics.generate_report()
+```
+
+## Dependencies
+- Python 3.x
+- No external dependencies required
+
+## Related Components
+- Coderack: Provides execution metrics
+- Workspace: Provides object statistics
+- Slipnet: Provides activation statistics
+- Correspondence: Provides mapping statistics 

copycat/temperature_README.md

@@ -0,0 +1,51 @@
+# README_temperature.md
+
+## Overview
+`temperature.py` implements the Temperature system, a crucial component of the Copycat system that controls the balance between exploration and exploitation during analogical reasoning. It provides various formulas for adjusting probabilities based on the current temperature, which affects how the system makes decisions.
+
+## Core Components
+- `Temperature` class: Main class that manages the temperature system
+- Multiple adjustment formulas for probability modification
+- Temperature history tracking
+
+## Key Features
+- Manages temperature-based control of the reasoning process
+- Provides multiple formulas for probability adjustment
+- Supports temperature clamping and unclamping
+- Tracks temperature history and differences
+- Allows dynamic switching between adjustment formulas
+
+## Adjustment Formulas
+- `original`: Basic temperature-based adjustment
+- `entropy`: Entropy-based adjustment
+- `inverse`: Inverse weighted adjustment
+- `fifty_converge`: Convergence to 0.5
+- `soft_curve`: Soft curve adjustment
+- `weighted_soft_curve`: Weighted soft curve
+- `alt_fifty`: Alternative fifty convergence
+- `average_alt`: Averaged alternative
+- `best`: Working best formula
+- `sbest`: Soft best formula
+- `pbest`: Parameterized best
+- `meta`: Meta-level adjustment
+- `pmeta`: Parameterized meta
+- `none`: No adjustment
+
+## Main Methods
+- `update(value)`: Update temperature value
+- `clampUntil(when)`: Clamp temperature until specified time
+- `tryUnclamp(currentTime)`: Attempt to unclamp temperature
+- `value()`: Get current temperature
+- `getAdjustedProbability(value)`: Get temperature-adjusted probability
+- `useAdj(adj)`: Switch to different adjustment formula
+
+## Dependencies
+- Uses `math` for mathematical operations
+- Used by the main `copycat` module
+
+## Notes
+- Temperature starts at 100.0 and can be clamped
+- Lower temperatures encourage more conservative decisions
+- Higher temperatures allow more exploratory behavior
+- The system tracks average differences between adjusted and original probabilities
+- Different adjustment formulas can be used for different reasoning strategies 

copycat/workspaceFormulas_README.md

@@ -0,0 +1,54 @@
+# Workspace Formulas System
+
+## Overview
+The workspace formulas system is a utility component of the Copycat architecture that provides mathematical and logical formulas for workspace operations. This system implements various calculations and transformations used in the analogical reasoning process.
+
+## Key Features
+- Mathematical formulas
+- Logical operations
+- Transformation rules
+- Calculation utilities
+- State management
+
+## Formula Types
+1. **Mathematical Formulas**
+   - Distance calculations
+   - Similarity measures
+   - Probability computations
+   - Activation formulas
+
+2. **Logical Formulas**
+   - Boolean operations
+   - Condition evaluations
+   - Rule applications
+   - Constraint checks
+
+3. **Transformation Formulas**
+   - Object transformations
+   - State transitions
+   - Value mappings
+   - Structure modifications
+
+## Usage
+Formulas are used throughout the workspace system:
+
+```python
+# Apply a formula
+result = workspace_formulas.calculate_distance(obj1, obj2)
+
+# Evaluate a condition
+is_valid = workspace_formulas.check_condition(condition)
+
+# Transform an object
+transformed = workspace_formulas.apply_transformation(obj)
+```
+
+## Dependencies
+- Python 3.x
+- No external dependencies required
+
+## Related Components
+- Workspace: Uses formulas for operations
+- WorkspaceObject: Provides objects for calculations
+- Codelets: Apply formulas in operations
+- Statistics: Uses formulas for metrics 

copycat/workspaceObject_README.md

@@ -0,0 +1,62 @@
+# Workspace Object System
+
+## Overview
+The workspace object system is a fundamental component of the Copycat architecture that manages the representation and manipulation of objects in the workspace. The system consists of several related files:
+
+- `workspaceObject.py`: Core implementation of workspace objects
+- `workspaceString.py`: String-specific object implementations
+- `workspaceStructure.py`: Structural object implementations
+- `workspaceFormulas.py`: Formula and calculation utilities
+
+## Workspace Objects
+Workspace objects are the basic building blocks of the workspace, representing:
+- Letters and characters
+- Groups and collections
+- Bonds and relationships
+- Structural elements
+
+## Key Features
+- Object hierarchy and inheritance
+- Property management and access
+- Relationship tracking
+- State management
+- Event handling
+
+## Object Types
+1. **Basic Objects**
+   - Letters and characters
+   - Numbers and symbols
+   - Special markers
+
+2. **Structural Objects**
+   - Groups and collections
+   - Bonds and connections
+   - Hierarchical structures
+
+3. **Composite Objects**
+   - Formulas and expressions
+   - Complex relationships
+   - Derived objects
+
+## Usage
+Workspace objects are created and managed through the workspace system:
+
+```python
+# Create a new workspace object
+obj = WorkspaceObject(properties)
+
+# Access object properties
+value = obj.get_property('property_name')
+
+# Modify object state
+obj.set_property('property_name', new_value)
+```
+
+## Dependencies
+- Python 3.x
+- No external dependencies required
+
+## Related Components
+- Workspace: Main container for workspace objects
+- Codelets: Operate on workspace objects
+- Slipnet: Provides conceptual knowledge for object interpretation 

copycat/workspaceString_README.md

@@ -0,0 +1,54 @@
+# Workspace String System
+
+## Overview
+The workspace string system is a specialized component of the Copycat architecture that handles string representations and operations in the workspace. This system manages the manipulation and analysis of string-based objects in the analogical reasoning process.
+
+## Key Features
+- String representation
+- String manipulation
+- Pattern matching
+- String analysis
+- State management
+
+## String Types
+1. **Basic Strings**
+   - Character sequences
+   - Word strings
+   - Symbol strings
+   - Special markers
+
+2. **Structured Strings**
+   - Grouped strings
+   - Bonded strings
+   - Hierarchical strings
+   - Pattern strings
+
+3. **Special Strings**
+   - Rule strings
+   - Mapping strings
+   - Context strings
+   - Meta-strings
+
+## Usage
+String operations are performed through the workspace string system:
+
+```python
+# Create a workspace string
+string = WorkspaceString(content)
+
+# Access string properties
+length = string.get_length()
+
+# Modify string state
+string.set_content(new_content)
+```
+
+## Dependencies
+- Python 3.x
+- No external dependencies required
+
+## Related Components
+- Workspace: Contains string objects
+- WorkspaceObject: Base class for strings
+- Codelets: Operate on strings
+- Correspondence: Maps between strings 

copycat/workspaceStructure_README.md

@@ -0,0 +1,54 @@
+# Workspace Structure System
+
+## Overview
+The workspace structure system is a fundamental component of the Copycat architecture that manages the structural organization of objects in the workspace. This system handles the creation and management of hierarchical and relational structures that form the basis of analogical reasoning.
+
+## Key Features
+- Structure representation
+- Hierarchy management
+- Relationship tracking
+- Pattern recognition
+- State management
+
+## Structure Types
+1. **Basic Structures**
+   - Linear sequences
+   - Hierarchical trees
+   - Network graphs
+   - Pattern structures
+
+2. **Composite Structures**
+   - Group structures
+   - Bond structures
+   - Rule structures
+   - Mapping structures
+
+3. **Special Structures**
+   - Context structures
+   - Meta-structures
+   - Derived structures
+   - Temporary structures
+
+## Usage
+Structures are created and managed through the workspace structure system:
+
+```python
+# Create a new structure
+structure = WorkspaceStructure(type, properties)
+
+# Access structure properties
+children = structure.get_children()
+
+# Modify structure state
+structure.add_child(child)
+```
+
+## Dependencies
+- Python 3.x
+- No external dependencies required
+
+## Related Components
+- Workspace: Contains structures
+- WorkspaceObject: Base class for structures
+- Codelets: Operate on structures
+- Correspondence: Maps between structures 

copycat/workspace_README.md

@@ -0,0 +1,42 @@
+# README_workspace.md
+
+## Overview
+`workspace.py` implements the Workspace, a central component of the Copycat system that manages the current state of the analogical reasoning process. It maintains the strings being compared, their objects, structures, and the overall state of the reasoning process.
+
+## Core Components
+- `Workspace` class: Main class that manages the reasoning workspace
+- `WorkspaceString` objects for initial, modified, and target strings
+- Collection of objects and structures (bonds, correspondences, etc.)
+
+## Key Features
+- Manages the three strings involved in the analogy (initial, modified, target)
+- Tracks objects and their relationships
+- Maintains structures like bonds, correspondences, and rules
+- Calculates various unhappiness metrics
+- Updates object values and structure strengths
+- Manages the temperature-based control system
+
+## Main Methods
+- `resetWithStrings(initial, modified, target)`: Initialize workspace with new strings
+- `updateEverything()`: Update all objects and structures
+- `getUpdatedTemperature()`: Calculate current temperature
+- `buildRule(rule)`: Add or replace the current rule
+- `breakRule()`: Remove the current rule
+- `buildDescriptions(objekt)`: Add descriptions to an object
+
+## State Management
+- Tracks total, intra-string, and inter-string unhappiness
+- Maintains lists of objects and structures
+- Manages the current rule and final answer
+- Tracks changed objects and their correspondences
+
+## Dependencies
+- Requires `formulas`, `bond`, `correspondence`, `letter`, and `workspaceString` modules
+- Used by the main `copycat` module
+
+## Notes
+- The workspace is the central state container for the reasoning process
+- Unhappiness metrics guide the temperature-based control system
+- The system supports both rule-based and correspondence-based reasoning
+- Objects can have multiple descriptions and relationships
+- The workspace maintains the final answer when reasoning is complete