Engine API Reference

Complete API documentation for the Q-Memetic AI engine.

MemeticEngine Class

The central orchestration engine for all memetic computing operations.

Constructor

class MemeticEngine:
    def __init__(
        self,
        license_key: Optional[str] = None,
        config: Optional[Dict[str, Any]] = None,
        data_dir: str = "./qmemetic_data"
    ) -> None:
        """
        Initialize the Q-Memetic AI engine.

        Args:
            license_key: QuantumMeta license key for feature access
            config: Configuration dictionary for engine settings
            data_dir: Directory for persistent data storage

        Raises:
            QMemeticLicenseError: If license validation fails
            ValueError: If configuration is invalid
        """

Parameters

Parameter	Type	Default	Description
license_key	Optional[str]	None	QuantumMeta license key
config	Optional[Dict]	None	Engine configuration
data_dir	str	"./qmemetic_data"	Data storage directory

Example

from qmemetic_ai import MemeticEngine

# Basic initialization
engine = MemeticEngine(license_key="your-license-key")

# Advanced configuration
config = {
    "evolution": {
        "population_size": 50,
        "mutation_rate": 0.15,
        "crossover_rate": 0.85
    },
    "entanglement": {
        "correlation_threshold": 0.7,
        "max_connections": 100
    },
    "performance": {
        "parallel_processing": True,
        "batch_size": 20
    }
}

engine = MemeticEngine(
    license_key="your-license-key",
    config=config,
    data_dir="/path/to/data"
)

Core Methods

Meme Creation

create_meme()

def create_meme(
    self,
    content: str,
    metadata: Optional[MemeMetadata] = None,
    vector_dim: int = 512
) -> Meme:
    """
    Create a new meme from content.

    Args:
        content: Text content for the meme
        metadata: Optional metadata object
        vector_dim: Dimension of the semantic vector

    Returns:
        Meme: Newly created meme object

    Raises:
        ValueError: If content is empty or invalid
        QMemeticLicenseError: If feature not available in license tier
    """

Example:

# Simple meme creation
meme = engine.create_meme("Quantum computing breakthrough")

# With metadata
from qmemetic_ai.core.meme import MemeMetadata

metadata = MemeMetadata(
    author="researcher_01",
    domain="quantum_computing",
    tags=["breakthrough", "research"],
    complexity=0.8
)

meme = engine.create_meme(
    content="Novel quantum algorithm for optimization",
    metadata=metadata,
    vector_dim=1024
)

create_memes()

def create_memes(
    self,
    content_list: List[str],
    batch_metadata: Optional[List[MemeMetadata]] = None
) -> List[Meme]:
    """
    Create multiple memes efficiently.

    Args:
        content_list: List of content strings
        batch_metadata: Optional list of metadata objects

    Returns:
        List[Meme]: List of created memes
    """

Example:

content_list = [
    "First research insight",
    "Second research finding", 
    "Third experimental result"
]

memes = engine.create_memes(content_list)
print(f"Created {len(memes)} memes")

Evolution Operations

evolve()

def evolve(
    self,
    memes: List[Meme],
    generations: int = 5,
    population_size: Optional[int] = None,
    fitness_function: Optional[Callable] = None,
    **kwargs
) -> List[Meme]:
    """
    Evolve a population of memes using genetic algorithms.

    Args:
        memes: Initial population of memes
        generations: Number of evolution generations
        population_size: Size of evolution population
        fitness_function: Custom fitness evaluation function
        **kwargs: Additional evolution parameters

    Returns:
        List[Meme]: Evolved population of memes

    Raises:
        MemeticEvolutionError: If evolution process fails
        QMemeticLicenseError: If advanced evolution features not licensed
    """

Parameters:

Parameter	Type	Default	Description
memes	List[Meme]	-	Initial meme population
generations	int	5	Number of generations
population_size	Optional[int]	None	Population size (auto if None)
fitness_function	Optional[Callable]	None	Custom fitness function
mutation_rate	float	0.25	Probability of mutation
crossover_rate	float	0.75	Probability of crossover
elitism_ratio	float	0.1	Fraction of elite preserved

Example:

# Basic evolution
initial_memes = [engine.create_meme(f"Idea {i}") for i in range(10)]
evolved = engine.evolve(initial_memes, generations=10)

# Custom fitness function
def research_fitness(meme):
    """Custom fitness based on research relevance."""
    relevance_score = calculate_research_relevance(meme.content)
    novelty_score = calculate_novelty(meme.vector)
    return 0.7 * relevance_score + 0.3 * novelty_score

evolved = engine.evolve(
    memes=initial_memes,
    generations=15,
    population_size=30,
    fitness_function=research_fitness,
    mutation_rate=0.3,
    crossover_rate=0.8
)

evolve_with_constraints()

def evolve_with_constraints(
    self,
    memes: List[Meme],
    constraints: Dict[str, Any],
    generations: int = 5
) -> List[Meme]:
    """
    Evolve memes with specific constraints.

    Args:
        memes: Initial population
        constraints: Evolution constraints
        generations: Number of generations

    Returns:
        List[Meme]: Constrained evolution results
    """

Example:

constraints = {
    "max_complexity": 0.8,
    "required_domains": ["AI", "quantum"],
    "diversity_threshold": 0.6,
    "semantic_bounds": {
        "min_similarity": 0.3,
        "max_similarity": 0.9
    }
}

constrained_evolution = engine.evolve_with_constraints(
    memes=initial_memes,
    constraints=constraints,
    generations=8
)

Entanglement Operations

entangle()

def entangle(
    self,
    memes: Optional[List[Meme]] = None,
    correlation_threshold: float = 0.7,
    max_connections: int = 100
) -> QuantumEntanglementNetwork:
    """
    Create quantum-inspired entanglement network.

    Args:
        memes: Memes to entangle (all if None)
        correlation_threshold: Minimum correlation for entanglement
        max_connections: Maximum connections per meme

    Returns:
        QuantumEntanglementNetwork: Entanglement network object

    Raises:
        NetworkEntanglementError: If network creation fails
    """

Example:

# Entangle all memes in engine
network = engine.entangle()

# Entangle specific memes
selected_memes = evolved[:20]  # Top 20 evolved memes
network = engine.entangle(
    memes=selected_memes,
    correlation_threshold=0.8,
    max_connections=50
)

# Analyze network properties
print(f"Network density: {network.density:.3f}")
print(f"Average clustering: {network.clustering_coefficient:.3f}")
print(f"Connected components: {network.num_components}")

measure_entanglement()

def measure_entanglement(
    self,
    meme_a: Meme,
    meme_b: Meme
) -> float:
    """
    Measure entanglement strength between two memes.

    Args:
        meme_a: First meme
        meme_b: Second meme

    Returns:
        float: Entanglement strength (0.0 to 1.0)
    """

Federation Operations

sync()

def sync(
    self,
    mode: str = "bidirectional",
    peer_filters: Optional[Dict[str, Any]] = None
) -> Dict[str, Any]:
    """
    Synchronize with federated network.

    Args:
        mode: Sync mode ("pull", "push", "bidirectional")
        peer_filters: Filters for peer selection

    Returns:
        Dict[str, Any]: Synchronization results

    Raises:
        FederationError: If sync operation fails
        QMemeticLicenseError: If federation features not licensed
    """

Example:

# Basic synchronization
sync_result = engine.sync()
print(f"Received {sync_result['memes_received']} memes")
print(f"Sent {sync_result['memes_sent']} memes")

# Filtered synchronization
peer_filters = {
    "domains": ["AI", "quantum_computing"],
    "trust_level": 0.8,
    "geographic_region": "North America"
}

sync_result = engine.sync(
    mode="pull",
    peer_filters=peer_filters
)

Analysis Operations

analyze()

def analyze(
    self,
    analysis_type: str = "comprehensive",
    memes: Optional[List[Meme]] = None,
    parameters: Optional[Dict[str, Any]] = None
) -> Dict[str, Any]:
    """
    Perform comprehensive analysis of meme population.

    Args:
        analysis_type: Type of analysis to perform
        memes: Memes to analyze (all if None)
        parameters: Analysis parameters

    Returns:
        Dict[str, Any]: Analysis results
    """

Analysis Types:

Type	Description	Output
"comprehensive"	Full statistical analysis	All metrics
"fitness"	Fitness distribution analysis	Fitness statistics
"diversity"	Population diversity metrics	Diversity measures
"clustering"	Semantic clustering analysis	Cluster information
"evolution"	Evolution trajectory analysis	Evolution metrics
"network"	Network topology analysis	Network properties

Example:

# Comprehensive analysis
analysis = engine.analyze(analysis_type="comprehensive")
print(f"Population size: {analysis['population_size']}")
print(f"Average fitness: {analysis['fitness']['mean']:.3f}")
print(f"Diversity index: {analysis['diversity']['simpson_index']:.3f}")

# Clustering analysis
cluster_analysis = engine.analyze(
    analysis_type="clustering",
    parameters={
        "num_clusters": 5,
        "method": "kmeans",
        "include_visualization": True
    }
)

for i, cluster in enumerate(cluster_analysis['clusters']):
    print(f"Cluster {i}: {len(cluster['memes'])} memes")
    print(f"  Centroid: {cluster['centroid_summary']}")

Status and Information

get_status()

def get_status(self) -> Dict[str, Any]:
    """
    Get comprehensive engine status.

    Returns:
        Dict[str, Any]: Status information including:
            - license_info: License status and features
            - meme_count: Number of memes in system
            - network_info: Entanglement network status
            - federation_info: Federation connection status
            - performance_metrics: System performance data
    """

Example:

status = engine.get_status()
print(f"License tier: {status['license_info']['tier']}")
print(f"Total memes: {status['meme_count']}")
print(f"Network connections: {status['network_info']['total_connections']}")
print(f"Federation peers: {status['federation_info']['connected_peers']}")

get_license_info()

def get_license_info(self) -> Dict[str, Any]:
    """
    Get detailed license information.

    Returns:
        Dict[str, Any]: License details including tier, features, expiration
    """

Data Management

save_state()

def save_state(self, file_path: str) -> None:
    """
    Save complete engine state to file.

    Args:
        file_path: Path to save state file

    Raises:
        DataPersistenceError: If save operation fails
    """

load_state()

def load_state(self, file_path: str) -> None:
    """
    Load engine state from file.

    Args:
        file_path: Path to state file

    Raises:
        DataPersistenceError: If load operation fails
        FileNotFoundError: If state file doesn't exist
    """

Example:

# Save current state
engine.save_state("research_session_backup.json")

# Load previous state
engine.load_state("research_session_backup.json")

export_data()

def export_data(
    self,
    file_path: str,
    format: str = "json",
    include_vectors: bool = False
) -> None:
    """
    Export meme data to external file.

    Args:
        file_path: Output file path
        format: Export format ("json", "csv", "yaml")
        include_vectors: Whether to include vector data
    """

import_data()

def import_data(
    self,
    file_path: str,
    format: str = "auto",
    merge_strategy: str = "append"
) -> int:
    """
    Import meme data from external file.

    Args:
        file_path: Input file path
        format: File format ("auto", "json", "csv", "yaml")
        merge_strategy: How to handle existing data

    Returns:
        int: Number of memes imported
    """

Configuration Options

Engine Configuration

default_config = {
    "evolution": {
        "population_size": 20,
        "generations": 5,
        "mutation_rate": 0.25,
        "crossover_rate": 0.75,
        "elitism_ratio": 0.1,
        "fitness_caching": True,
        "parallel_evolution": True
    },
    "entanglement": {
        "correlation_threshold": 0.7,
        "max_connections_per_meme": 100,
        "network_update_frequency": 10,
        "decoherence_rate": 0.05,
        "clustering_algorithm": "louvain"
    },
    "federation": {
        "auto_discovery": True,
        "sync_interval": 300,  # seconds
        "max_peers": 50,
        "trust_threshold": 0.6,
        "bandwidth_limit": "10MB/s"
    },
    "performance": {
        "parallel_processing": True,
        "batch_size": 20,
        "memory_limit": "2GB",
        "disk_cache_size": "1GB",
        "optimization_level": "balanced"
    },
    "security": {
        "encryption_enabled": True,
        "audit_logging": True,
        "session_timeout": 7200,
        "api_rate_limiting": True
    },
    "logging": {
        "level": "INFO",
        "file_output": True,
        "console_output": True,
        "log_rotation": True
    }
}

Error Handling

Exception Types

from qmemetic_ai.exceptions import (
    QMemeticLicenseError,
    MemeticEvolutionError,
    NetworkEntanglementError,
    FederationError,
    DataPersistenceError
)

try:
    engine = MemeticEngine(license_key="invalid-key")
except QMemeticLicenseError as e:
    print(f"License error: {e}")

try:
    evolved = engine.evolve(memes, generations=100)
except MemeticEvolutionError as e:
    print(f"Evolution failed: {e}")
    # Try with reduced parameters
    evolved = engine.evolve(memes, generations=10, population_size=10)

Best Practices

# Always use context managers for resource management
with MemeticEngine(license_key="your-key") as engine:
    memes = engine.create_memes(content_list)
    evolved = engine.evolve(memes)
    network = engine.entangle(evolved)

# Handle license errors gracefully
def safe_engine_init(license_key):
    try:
        return MemeticEngine(license_key=license_key)
    except QMemeticLicenseError:
        # Fall back to trial mode with limited features
        return MemeticEngine()  # No license key

# Use proper error handling for evolution
def robust_evolution(engine, memes, max_attempts=3):
    for attempt in range(max_attempts):
        try:
            return engine.evolve(memes, generations=10)
        except MemeticEvolutionError as e:
            if attempt == max_attempts - 1:
                raise e
            # Reduce complexity and try again
            generations = max(1, 10 - attempt * 3)
            population_size = max(5, 20 - attempt * 5)

Performance Optimization

Parallel Processing

# Enable parallel processing
config = {
    "performance": {
        "parallel_processing": True,
        "max_workers": 8,
        "batch_size": 50
    }
}

engine = MemeticEngine(license_key="your-key", config=config)

# Batch operations for better performance
large_content_list = [f"Content {i}" for i in range(1000)]
memes = engine.create_memes(large_content_list)  # Automatically batched

Memory Management

# Configure memory limits
config = {
    "performance": {
        "memory_limit": "4GB",
        "disk_cache_size": "2GB",
        "cleanup_interval": 3600
    }
}

# Monitor memory usage
status = engine.get_status()
memory_usage = status['performance_metrics']['memory_usage']
if memory_usage > 0.8:
    engine.cleanup_memory()

Caching Strategies

# Enable aggressive caching for repeated operations
config = {
    "caching": {
        "fitness_cache_size": 10000,
        "vector_cache_size": 5000,
        "network_cache_ttl": 3600
    }
}

# Pre-warm caches for better performance
engine.pre_warm_caches(expected_operations=["evolution", "entanglement"])

For more detailed API documentation, see the individual module references: - Meme API - Evolution API - Entanglement API - Visualization API