HeurAMS/tests/examples.py

"""
Examples and usage patterns for HeurAMS modules.

This file demonstrates how to use the various HeurAMS components
in common scenarios and workflows.
"""
import json
from datetime import datetime, timezone
from pathlib import Path

# Import only modules that work without configuration dependencies
from src.heurams.kernel.particles.atom import Atom
from src.heurams.kernel.particles.electron import Electron
from src.heurams.kernel.particles.nucleon import Nucleon
from src.heurams.kernel.particles.orbital import Orbital

from src.heurams.kernel.algorithms.sm2 import SM2Algorithm


class BasicUsageExamples:
    """Examples of basic usage patterns."""

    @staticmethod
    def create_basic_atom():
        """
        Example: Create a basic Atom with question and answer.
        """
        print("=== Creating Basic Atom ===")

        # Create the components
        nucleon = Nucleon(
            content="What is the capital of France?",
            answer="Paris"
        )
        electron = Electron()  # Uses default values
        orbital = Orbital()    # Uses default values

        # Combine into an Atom
        atom = Atom(nucleon=nucleon, electron=electron, orbital=orbital)

        print(f"Atom created:")
        print(f"  Question: {atom.nucleon.content}")
        print(f"  Answer: {atom.nucleon.answer}")
        print(f"  Current ease: {atom.electron.ease}")
        print(f"  Current interval: {atom.electron.interval} days")

        return atom

    @staticmethod
    def create_cloze_atom():
        """
        Example: Create an Atom with cloze deletion content.
        """
        print("\n=== Creating Cloze Atom ===")

        nucleon = Nucleon(
            content="The {{c1::capital}} of {{c2::France}} is {{c3::Paris}}.",
            answer="capital, France, Paris"
        )
        electron = Electron()
        orbital = Orbital()
        atom = Atom(nucleon=nucleon, electron=electron, orbital=orbital)

        print(f"Cloze Atom created:")
        print(f"  Content: {atom.nucleon.content}")
        print(f"  Answer: {atom.nucleon.answer}")

        return atom


class AlgorithmExamples:
    """Examples of algorithm usage."""

    @staticmethod
    def sm2_review_example():
        """
        Example: Process a review using SM2 algorithm.
        """
        print("\n=== SM2 Review Example ===")

        # Create an atom in learning phase
        nucleon = Nucleon(content="Test question", answer="Test answer")
        electron = Electron(repetitions=0, interval=1, ease=2.5)
        orbital = Orbital()
        atom = Atom(nucleon=nucleon, electron=electron, orbital=orbital)

        # Create algorithm
        algorithm = SM2Algorithm()

        print("Before review:")
        print(f"  Repetitions: {atom.electron.repetitions}")
        print(f"  Interval: {atom.electron.interval} days")
        print(f"  Ease: {atom.electron.ease}")

        # Process a successful review (quality 4)
        new_electron = algorithm.process_review(atom.electron, atom.orbital, 4)

        print("\nAfter review (quality 4):")
        print(f"  Repetitions: {new_electron.repetitions}")
        print(f"  Interval: {new_electron.interval} days")
        print(f"  Ease: {new_electron.ease:.2f}")

        return new_electron

    @staticmethod
    def sm2_failed_review_example():
        """
        Example: Process a failed review using SM2 algorithm.
        """
        print("\n=== SM2 Failed Review Example ===")

        # Create an atom in review phase
        nucleon = Nucleon(content="Hard question", answer="Hard answer")
        electron = Electron(repetitions=5, interval=10, ease=2.5)
        orbital = Orbital()
        atom = Atom(nucleon=nucleon, electron=electron, orbital=orbital)

        algorithm = SM2Algorithm()

        print("Before review:")
        print(f"  Repetitions: {atom.electron.repetitions}")
        print(f"  Interval: {atom.electron.interval} days")

        # Process a failed review (quality 1)
        new_electron = algorithm.process_review(atom.electron, atom.orbital, 1)

        print("\nAfter review (quality 1 - failed):")
        print(f"  Repetitions: {new_electron.repetitions}")  # Should reset to 0
        print(f"  Interval: {new_electron.interval} days")   # Should reset to 1

        return new_electron


class ReactorExamples:
    """Examples of reactor system usage."""

    @staticmethod
    def basic_atom_workflow():
        """
        Example: Basic Atom workflow.
        """
        print("\n=== Basic Atom Workflow ===")

        # Create an atom
        atom = Atom("test_atom")

        # Create nucleon with content
        nucleon = Nucleon("nucleon_id", {
            "content": "What is the capital of Germany?",
            "answer": "Berlin"
        })

        # Create electron with algorithm data
        electron = Electron("electron_id")

        # Create orbital configuration
        orbital = Orbital(
            quick_view=[["cloze", 1]],
            recognition=[],
            final_review=[],
            puzzle_config={}
        )

        # Link components to atom
        atom.link("nucleon", nucleon)
        atom.link("electron", electron)
        atom.link("orbital", orbital)

        print(f"Atom created with ID: {atom.ident}")
        print(f"Nucleon content: {atom['nucleon']['content']}")
        print(f"Electron algorithm: {electron.algo}")

        return atom


class ServiceExamples:
    """Examples of service usage."""

    @staticmethod
    def version_example():
        """
        Example: Using Version service.
        """
        print("\n=== Version Service Example ===")

        from src.heurams.services.version import ver, stage

        print(f"HeurAMS Version: {ver}")
        print(f"Development Stage: {stage}")

        return ver, stage


def run_all_examples():
    """
    Run all examples to demonstrate HeurAMS functionality.
    """
    print("=" * 50)
    print("HEURAMS EXAMPLES")
    print("=" * 50)

    # Basic usage
    BasicUsageExamples.create_basic_atom()
    BasicUsageExamples.create_cloze_atom()

    # Algorithm examples
    AlgorithmExamples.sm2_review_example()
    AlgorithmExamples.sm2_failed_review_example()

    # Reactor examples
    ReactorExamples.basic_atom_workflow()

    # Service examples
    ServiceExamples.version_example()

    print("\n" + "=" * 50)
    print("ALL EXAMPLES COMPLETED")
    print("=" * 50)


if __name__ == "__main__":
    run_all_examples()