How namin/pyeurisko works
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.