# namin/pyeurisko architecture

> Architecture diagram of the GitHub repository namin/pyeurisko, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/namin/pyeurisko
- Repository: https://github.com/namin/pyeurisko

## Overview

##### Project Type and Purpose
- PyEurisko is a specialized AI/heuristics system originally based on Eurisko, designed to implement heuristic and rule-based reasoning in Python.
- The project’s README explains it is experimental, porting some of the original ideas from Common Lisp to Python and integrating insights (with some aspects guided by Claude.ai).
- Look out for key themes: heuristic modules, task management, unit and slot components, and a reliance on external concepts (like lisp units) for core logic.

##### Analyzing the File Structure
- Notice the main top-level components:
- The "eurisko" package containing the heart of the application:
- "heuristics" directory: Contains multiple heuristic modules (e.g., h1.py, h2.py … h23.py), a rule_factory.py, and rules.py. These modules represent the system’s algorithm/rule-driven logic.
- "slots" directory: Likely implements re-entrant or dynamic function slots (function_slots.py) to allow flexible execution modules.
- "tasks" directory: Defines tasks and a task manager (task_manager.py, task.py, task_types.py) to schedule or organize system actions.
- "units" directory: Implements core representations (concepts, core logic, lisp implementation details) which are probably used for domain-specific knowledge encoding.
- "interfaces.py", "main.py", and "system.py" offer the entry points and integration between these components.
- Additional support/documentation directories:
- "claude-docs" and "my-docs": Contain debugging journals, design references, heuristics summaries, and goals. These support developing and evolving the system.
- "tests" and "tools": Provide tests for the heuristics (e.g., test_h6.py) and utility scripts.
- Standard files like README.md, RUN.md, setup.py, and requirements.txt suggest proper packaging and deployment practices.

##### Extracting Architecture Insights from the README
- The README highlights its experimental nature and reliance on insights from external tooling (Claude.ai and a filesystem MCP server).
- The references to “Lisp units” indicate that some modules (under eurisko/units) focus on legacy Lisp functionalities.
- There is an emphasis on continuous notes/documentation (claude-docs and my-docs) to refine heuristics and design, which means the architecture may be adaptive and iterative.

a. Main Components:
- Application Core:
- Main Engine (eurisko/main.py, eurisko/system.py): The starting point that orchestrates the system.
- Interface Module (eurisko/interfaces.py): Exposes API endpoints or integration points.
- Heuristics Engine:
- eurisko/heuristics directory: Contains the numerous heuristic modules (e.g., h1.py to h23.py) and rule factories that form the decision-making core.
- Task Management:
- eurisko/tasks: Represents the scheduling and management of tasks that the system performs.
- Unit and Representation Management:
- eurisko/units: Manages internal representations, concepts, and possibly handles Lisp interfaces.
- Slot Mechanisms:
- eurisko/slots: Likely provides dynamic binding functionalities or execution “slots” which could be important for integration or re-entrancy.
- Supporting Documentation and Tools:
- claude-docs & my-docs: Serve as supplementary design and debugging aids.
- tests and tools: Surround the core system with testing and utility scripts.

b. Relationships and Interactions:
- The Main Engine interacting with the Heuristics Engine, Task Manager, and Unit Modules.
- The Heuristics component engaging with rule factories and invoking individual heuristic modules to drive behavior.
- How tasks (in tasks) might schedule or trigger heuristic evaluations and system updates.
- Interfaces between units and slots (e.g., dynamic execution paths that may leverage function slots).
- Interactions with external or experimental components noted in the README (such as integration hints for re-entrant execution with a filesystem server).

c. Highlighting Architectural Patterns and Design Principles:
- Modular design is evident: separate directories for heuristics, tasks, slots, and units suggest a separation of concerns.
- The design might leverage patterns such as plug-in architecture (heuristics as pluggable modules) and dynamic dispatch (slots for re-entrant functionality).
- Iterative development and self-contained modules that interact primarily through defined interfaces.

d. Relevant Technologies & Libraries:
- Python is the core language.
- Look for potential reliance on external libraries for task scheduling, rule-based systems, or possibly interfacing with Lisp interpreters (hinted by the presence of lisp_units and lisp_impl).
- The existence of setup.py and requirements.txt indicates a standard Python packaging and dependency management environment.

##### Summary
- A central orchestration module (main.py/system.py) coordinating interactions.
- Modular blocks representing heuristics (multiple h*.py modules managed via rule factories).
- Supporting mechanisms such as dynamic slots and scheduled tasks.
- Interfacing modules (units and interfaces) that bridge internal logic with the external environment.
- Lean on directional flows that show which module calls or influences which other module, highlighting the layered and modular nature of the architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Application Core"
        A1("Main Engine"):::core
        A2("Interface Module"):::core
    end

    subgraph "Heuristics Engine"
        H("Heuristic Modules & Rules"):::heuristics
    end

    subgraph "Task Management"
        T("Task Manager"):::tasks
    end

    subgraph "Unit & Representation Management"
        U("Unit Manager"):::units
    end

    subgraph "Slot Mechanisms"
        S("Function Slots"):::slots
    end

    subgraph "Documentation & Tools"
        D1("claude-docs"):::docs
        D2("my-docs"):::docs
    end

    %% Connections
    A1 -->|"calls"| H
    A1 -->|"calls"| T
    A1 -->|"calls"| U
    A1 -->|"utilizes"| S
    A2 -->|"interfaces"| A1
    T -->|"triggers"| H

    %% Click Events for Application Core
    click A1 "https://github.com/namin/pyeurisko/blob/main/eurisko/main.py"
    click A1 "https://github.com/namin/pyeurisko/blob/main/eurisko/system.py"
    click A2 "https://github.com/namin/pyeurisko/blob/main/eurisko/interfaces.py"

    %% Click Event for Heuristics Engine
    click H "https://github.com/namin/pyeurisko/tree/main/eurisko/heuristics"

    %% Click Event for Task Management
    click T "https://github.com/namin/pyeurisko/tree/main/eurisko/tasks"

    %% Click Event for Unit and Representation Management
    click U "https://github.com/namin/pyeurisko/tree/main/eurisko/units"

    %% Click Event for Slot Mechanisms
    click S "https://github.com/namin/pyeurisko/blob/main/eurisko/slots/function_slots.py"

    %% Click Events for Supporting Documentation
    click D1 "https://github.com/namin/pyeurisko/tree/main/claude-docs"
    click D2 "https://github.com/namin/pyeurisko/tree/main/my-docs"

    %% Styles
    classDef core fill:#f9e79f,stroke:#d35400,stroke-width:2px;
    classDef heuristics fill:#aed6f1,stroke:#2874a6,stroke-width:2px;
    classDef tasks fill:#a9dfbf,stroke:#1e8449,stroke-width:2px;
    classDef units fill:#fef9e7,stroke:#b7950b,stroke-width:2px;
    classDef slots fill:#fadbd8,stroke:#c0392b,stroke-width:2px;
    classDef docs fill:#d5dbdb,stroke:#808b96,stroke-width:2px;
```
