Memes API Reference

Complete API documentation for meme objects and operations.

Meme Class

Core class representing individual memes in the Q-Memetic AI system.

Constructor

class Meme:
    def __init__(
        self,
        content: str,
        metadata: Optional[MemeMetadata] = None,
        vector: Optional[np.ndarray] = None,
        meme_id: Optional[str] = None
    ) -> None:
        """
        Initialize a new meme.

        Args:
            content: The textual content of the meme
            metadata: Optional metadata object
            vector: Optional pre-computed semantic vector
            meme_id: Optional unique identifier
        """

Properties

Core Properties

Property	Type	Description
meme_id	str	Unique identifier for the meme
content	str	Textual content of the meme
vector	np.ndarray	Semantic vector representation
metadata	MemeMetadata	Associated metadata object
fitness	float	Current fitness score
generation	int	Evolution generation number
created_at	datetime	Creation timestamp
modified_at	datetime	Last modification timestamp

Computed Properties

@property
def complexity(self) -> float:
    """Calculate content complexity score (0.0 to 1.0)."""

@property
def semantic_density(self) -> float:
    """Calculate semantic information density."""

@property
def novelty_score(self) -> float:
    """Calculate novelty relative to population."""

@property
def word_count(self) -> int:
    """Get word count of content."""

@property
def character_count(self) -> int:
    """Get character count of content."""

Methods

Content Manipulation

def update_content(self, new_content: str) -> None:
    """
    Update meme content and refresh derived properties.

    Args:
        new_content: New textual content
    """

def append_content(self, additional_content: str) -> None:
    """
    Append content to existing meme.

    Args:
        additional_content: Content to append
    """

def prepend_content(self, prefix_content: str) -> None:
    """
    Prepend content to existing meme.

    Args:
        prefix_content: Content to prepend
    """

Example:

meme = Meme("Original insight")
meme.update_content("Expanded original insight with new findings")
meme.append_content(" Additional conclusions drawn from data.")
print(meme.content)
# Output: "Expanded original insight with new findings Additional conclusions drawn from data."

Vector Operations

def compute_vector(
    self,
    model: str = "sentence-transformers",
    dim: int = 512
) -> np.ndarray:
    """
    Compute semantic vector representation.

    Args:
        model: Embedding model to use
        dim: Vector dimensionality

    Returns:
        np.ndarray: Semantic vector
    """

def update_vector(self, new_vector: np.ndarray) -> None:
    """
    Update the semantic vector.

    Args:
        new_vector: New vector representation
    """

def vector_similarity(self, other_meme: 'Meme') -> float:
    """
    Calculate cosine similarity with another meme.

    Args:
        other_meme: Meme to compare with

    Returns:
        float: Similarity score (0.0 to 1.0)
    """

Example:

meme1 = Meme("Quantum computing applications")
meme2 = Meme("Quantum algorithm development")

# Compute vectors
meme1.compute_vector(model="all-MiniLM-L6-v2", dim=384)
meme2.compute_vector(model="all-MiniLM-L6-v2", dim=384)

# Calculate similarity
similarity = meme1.vector_similarity(meme2)
print(f"Similarity: {similarity:.3f}")

Fitness and Evaluation

def calculate_fitness(
    self,
    fitness_function: Optional[Callable] = None,
    context: Optional[Dict[str, Any]] = None
) -> float:
    """
    Calculate fitness score for the meme.

    Args:
        fitness_function: Custom fitness function
        context: Additional context for evaluation

    Returns:
        float: Fitness score
    """

def evaluate_quality(self) -> Dict[str, float]:
    """
    Comprehensive quality evaluation.

    Returns:
        Dict[str, float]: Quality metrics including:
            - coherence: Logical consistency
            - clarity: Readability and understanding
            - originality: Uniqueness score
            - relevance: Domain relevance
            - impact: Potential influence score
    """

Example:

def research_fitness(meme):
    """Custom fitness for research applications."""
    quality = meme.evaluate_quality()
    return (
        0.3 * quality['coherence'] +
        0.2 * quality['clarity'] +
        0.3 * quality['originality'] +
        0.2 * quality['relevance']
    )

fitness = meme.calculate_fitness(fitness_function=research_fitness)
quality_metrics = meme.evaluate_quality()
print(f"Fitness: {fitness:.3f}")
print(f"Quality breakdown: {quality_metrics}")

Serialization

def to_dict(self) -> Dict[str, Any]:
    """
    Serialize meme to dictionary.

    Returns:
        Dict[str, Any]: Serialized meme data
    """

@classmethod
def from_dict(cls, data: Dict[str, Any]) -> 'Meme':
    """
    Deserialize meme from dictionary.

    Args:
        data: Serialized meme data

    Returns:
        Meme: Reconstructed meme object
    """

def to_json(self) -> str:
    """
    Serialize meme to JSON string.

    Returns:
        str: JSON representation
    """

@classmethod
def from_json(cls, json_str: str) -> 'Meme':
    """
    Deserialize meme from JSON string.

    Args:
        json_str: JSON representation

    Returns:
        Meme: Reconstructed meme object
    """

Example:

# Serialize meme
meme_dict = meme.to_dict()
meme_json = meme.to_json()

# Deserialize meme
reconstructed_from_dict = Meme.from_dict(meme_dict)
reconstructed_from_json = Meme.from_json(meme_json)

# Verify reconstruction
assert meme.content == reconstructed_from_dict.content
assert meme.meme_id == reconstructed_from_json.meme_id

MemeMetadata Class

Container for meme metadata and attributes.

Constructor

class MemeMetadata:
    def __init__(
        self,
        author: Optional[str] = None,
        domain: Optional[str] = None,
        tags: Optional[List[str]] = None,
        complexity: Optional[float] = None,
        generation: int = 0,
        source: Optional[str] = None,
        confidence: float = 1.0,
        **kwargs
    ) -> None:
        """
        Initialize meme metadata.

        Args:
            author: Author identifier
            domain: Subject domain
            tags: List of descriptive tags
            complexity: Complexity score (0.0 to 1.0)
            generation: Evolution generation
            source: Source information
            confidence: Confidence score (0.0 to 1.0)
            **kwargs: Additional metadata fields
        """

Properties

Property	Type	Default	Description
author	Optional[str]	None	Author identifier
domain	Optional[str]	None	Subject domain
tags	List[str]	[]	Descriptive tags
complexity	float	0.0	Complexity score
generation	int	0	Evolution generation
source	Optional[str]	None	Source information
confidence	float	1.0	Confidence score
parent_ids	List[str]	[]	Parent meme IDs
child_ids	List[str]	[]	Child meme IDs
created_at	float	time.time()	Creation timestamp
modified_at	float	time.time()	Modification timestamp

Methods

def add_tag(self, tag: str) -> None:
    """Add a tag to the metadata."""

def remove_tag(self, tag: str) -> None:
    """Remove a tag from the metadata."""

def has_tag(self, tag: str) -> bool:
    """Check if metadata has a specific tag."""

def get_age_days(self) -> float:
    """Get age of meme in days."""

def add_parent(self, parent_id: str) -> None:
    """Add a parent meme ID."""

def add_child(self, child_id: str) -> None:
    """Add a child meme ID."""

def to_dict(self) -> Dict[str, Any]:
    """Serialize metadata to dictionary."""

@classmethod
def from_dict(cls, data: Dict[str, Any]) -> 'MemeMetadata':
    """Deserialize metadata from dictionary."""

Example:

metadata = MemeMetadata(
    author="research_team_alpha",
    domain="artificial_intelligence",
    tags=["machine_learning", "neural_networks"],
    complexity=0.7,
    source="research_paper_2024"
)

metadata.add_tag("breakthrough")
metadata.add_parent("parent_meme_id_123")

print(f"Age: {metadata.get_age_days():.1f} days")
print(f"Has ML tag: {metadata.has_tag('machine_learning')}")

MemeVector Class

Specialized vector operations for memes.

Constructor

class MemeVector:
    def __init__(
        self,
        vector: np.ndarray,
        model_name: str = "default",
        dimensionality: Optional[int] = None
    ) -> None:
        """
        Initialize semantic vector.

        Args:
            vector: Numerical vector representation
            model_name: Name of embedding model used
            dimensionality: Vector dimensionality
        """

Vector Operations

def cosine_similarity(self, other: 'MemeVector') -> float:
    """Calculate cosine similarity with another vector."""

def euclidean_distance(self, other: 'MemeVector') -> float:
    """Calculate Euclidean distance to another vector."""

def manhattan_distance(self, other: 'MemeVector') -> float:
    """Calculate Manhattan distance to another vector."""

def dot_product(self, other: 'MemeVector') -> float:
    """Calculate dot product with another vector."""

def normalize(self) -> 'MemeVector':
    """Return normalized version of vector."""

def add(self, other: 'MemeVector') -> 'MemeVector':
    """Add another vector (element-wise)."""

def subtract(self, other: 'MemeVector') -> 'MemeVector':
    """Subtract another vector (element-wise)."""

def multiply(self, scalar: float) -> 'MemeVector':
    """Multiply vector by scalar."""

Dimensional Analysis

def reduce_dimensions(
    self,
    target_dim: int,
    method: str = "pca"
) -> 'MemeVector':
    """
    Reduce vector dimensionality.

    Args:
        target_dim: Target dimensionality
        method: Reduction method ("pca", "tsne", "umap")

    Returns:
        MemeVector: Reduced-dimension vector
    """

def expand_dimensions(
    self,
    target_dim: int,
    method: str = "zero_pad"
) -> 'MemeVector':
    """
    Expand vector dimensionality.

    Args:
        target_dim: Target dimensionality
        method: Expansion method ("zero_pad", "interpolate")

    Returns:
        MemeVector: Expanded-dimension vector
    """

Example:

# Create vectors
vector1 = MemeVector(np.random.randn(512), model_name="sentence-bert")
vector2 = MemeVector(np.random.randn(512), model_name="sentence-bert")

# Calculate similarities
cosine_sim = vector1.cosine_similarity(vector2)
euclidean_dist = vector1.euclidean_distance(vector2)

print(f"Cosine similarity: {cosine_sim:.3f}")
print(f"Euclidean distance: {euclidean_dist:.3f}")

# Dimension operations
reduced = vector1.reduce_dimensions(target_dim=128, method="pca")
normalized = vector1.normalize()

Utility Functions

Content Analysis

def analyze_content_complexity(content: str) -> float:
    """
    Analyze content complexity.

    Args:
        content: Text content to analyze

    Returns:
        float: Complexity score (0.0 to 1.0)
    """

def extract_keywords(
    content: str,
    num_keywords: int = 10,
    method: str = "tfidf"
) -> List[str]:
    """
    Extract keywords from content.

    Args:
        content: Text content
        num_keywords: Number of keywords to extract
        method: Extraction method ("tfidf", "rake", "yake")

    Returns:
        List[str]: Extracted keywords
    """

def calculate_readability(content: str) -> Dict[str, float]:
    """
    Calculate readability metrics.

    Args:
        content: Text content

    Returns:
        Dict[str, float]: Readability scores
    """

Batch Operations

def create_meme_batch(
    content_list: List[str],
    metadata_list: Optional[List[MemeMetadata]] = None,
    batch_size: int = 100
) -> List[Meme]:
    """
    Create multiple memes efficiently.

    Args:
        content_list: List of content strings
        metadata_list: Optional list of metadata objects
        batch_size: Processing batch size

    Returns:
        List[Meme]: Created memes
    """

def similarity_matrix(memes: List[Meme]) -> np.ndarray:
    """
    Calculate pairwise similarity matrix.

    Args:
        memes: List of memes

    Returns:
        np.ndarray: Similarity matrix
    """

def cluster_memes(
    memes: List[Meme],
    num_clusters: int,
    method: str = "kmeans"
) -> Dict[int, List[Meme]]:
    """
    Cluster memes by similarity.

    Args:
        memes: List of memes to cluster
        num_clusters: Number of clusters
        method: Clustering method

    Returns:
        Dict[int, List[Meme]]: Clustered memes
    """

Example:

# Batch creation
content_list = [f"Research finding {i}" for i in range(100)]
memes = create_meme_batch(content_list, batch_size=25)

# Similarity analysis
sim_matrix = similarity_matrix(memes[:10])
print(f"Similarity matrix shape: {sim_matrix.shape}")

# Clustering
clusters = cluster_memes(memes, num_clusters=5, method="kmeans")
for cluster_id, cluster_memes in clusters.items():
    print(f"Cluster {cluster_id}: {len(cluster_memes)} memes")

Advanced Features

Genetic Operations

def crossover_memes(
    parent1: Meme,
    parent2: Meme,
    method: str = "semantic_blend"
) -> Tuple[Meme, Meme]:
    """
    Perform crossover between two memes.

    Args:
        parent1: First parent meme
        parent2: Second parent meme
        method: Crossover method

    Returns:
        Tuple[Meme, Meme]: Two offspring memes
    """

def mutate_meme(
    meme: Meme,
    mutation_rate: float = 0.1,
    mutation_type: str = "semantic"
) -> Meme:
    """
    Apply mutation to a meme.

    Args:
        meme: Meme to mutate
        mutation_rate: Probability of mutation
        mutation_type: Type of mutation

    Returns:
        Meme: Mutated meme
    """

Quality Metrics

class MemeQualityAssessor:
    """Assess meme quality across multiple dimensions."""

    def __init__(self):
        self.metrics = {
            "coherence": CoherenceMetric(),
            "novelty": NoveltyMetric(),
            "relevance": RelevanceMetric(),
            "clarity": ClarityMetric(),
            "impact": ImpactMetric()
        }

    def assess_quality(self, meme: Meme) -> Dict[str, float]:
        """
        Comprehensive quality assessment.

        Args:
            meme: Meme to assess

        Returns:
            Dict[str, float]: Quality scores
        """

    def compare_quality(
        self,
        meme1: Meme,
        meme2: Meme
    ) -> Dict[str, float]:
        """
        Compare quality between two memes.

        Args:
            meme1: First meme
            meme2: Second meme

        Returns:
            Dict[str, float]: Quality comparison scores
        """

Performance Optimization

def optimize_meme_storage(memes: List[Meme]) -> None:
    """Optimize memory usage for large meme collections."""

def cache_vectors(memes: List[Meme], cache_size: int = 1000) -> None:
    """Cache frequently accessed vectors."""

def batch_vector_computation(
    memes: List[Meme],
    model: str = "sentence-transformers",
    batch_size: int = 32
) -> None:
    """Compute vectors in batches for efficiency."""

Example:

# Quality assessment
assessor = MemeQualityAssessor()
quality_scores = assessor.assess_quality(meme)
print(f"Quality scores: {quality_scores}")

# Genetic operations
child1, child2 = crossover_memes(parent1, parent2, method="semantic_blend")
mutated = mutate_meme(child1, mutation_rate=0.2)

# Performance optimization
large_meme_collection = [Meme(f"Content {i}") for i in range(10000)]
optimize_meme_storage(large_meme_collection)
batch_vector_computation(large_meme_collection, batch_size=64)

Error Handling

Meme-Specific Exceptions

class MemeError(Exception):
    """Base exception for meme-related errors."""

class InvalidMemeContent(MemeError):
    """Raised when meme content is invalid."""

class MemeVectorError(MemeError):
    """Raised when vector operations fail."""

class MemeMetadataError(MemeError):
    """Raised when metadata is invalid."""

# Usage example
try:
    meme = Meme("")  # Empty content
except InvalidMemeContent as e:
    print(f"Invalid meme content: {e}")

try:
    similarity = meme1.vector_similarity(meme2)  # If vectors not computed
except MemeVectorError as e:
    print(f"Vector error: {e}")
    # Compute vectors first
    meme1.compute_vector()
    meme2.compute_vector()
    similarity = meme1.vector_similarity(meme2)

Integration Examples

With Evolution System

from qmemetic_ai.core.evolution import GeneticEvolver

# Create initial population
population = [Meme(f"Initial idea {i}") for i in range(20)]

# Set up evolver
evolver = GeneticEvolver(
    fitness_function=lambda m: m.calculate_fitness(),
    mutation_rate=0.25,
    crossover_rate=0.75
)

# Evolve population
evolved_population = evolver.evolve(population, generations=10)

# Analyze evolution results
for meme in evolved_population:
    quality = meme.evaluate_quality()
    print(f"Evolved meme: {meme.content[:50]}...")
    print(f"  Fitness: {meme.fitness:.3f}")
    print(f"  Generation: {meme.generation}")

With Entanglement System

from qmemetic_ai.core.entanglement import QuantumEntangler

# Create entanglement network
entangler = QuantumEntangler()
network = entangler.create_network(memes)

# Find entangled memes
for meme in memes:
    entangled_partners = entangler.get_entangled_memes(meme)
    print(f"Meme: {meme.content[:30]}...")
    for partner, strength in entangled_partners[:3]:  # Top 3
        print(f"  Partner: {partner.content[:30]}... (strength: {strength:.3f})")

For complete integration examples and advanced usage patterns, see the Engine API documentation.