memi-engine 0.1.0__py3-none-any.whl

memi_engine/__init__.py

@@ -0,0 +1,29 @@
+"""memi-engine: build your own memi memory card game.
+
+Usage:
+    from memi_engine import CategoryProvider, MemiConfig, create_app, register
+
+    class MyCategory(CategoryProvider):
+        key = "my:category"
+        items = ["Item 1", "Item 2"]
+
+    register(MyCategory())
+
+    app = create_app(MemiConfig(title="My Memi"))
+"""
+
+from memi_engine.app import create_app
+from memi_engine.config import MemiConfig
+from memi_engine.provider import AggregateProvider, CategoryProvider
+from memi_engine.registry import register
+from memi_engine.scientific import SCIENTIFIC_NAMES, ScientificNameProvider
+
+__all__ = [
+    "SCIENTIFIC_NAMES",
+    "AggregateProvider",
+    "CategoryProvider",
+    "MemiConfig",
+    "ScientificNameProvider",
+    "create_app",
+    "register",
+]

memi_engine/app.py

@@ -0,0 +1,256 @@
+"""Generic Flask app for memi instances.
+
+All category-specific logic lives in CategoryProviders. This module
+handles routing, filtering, and the game loop — without knowing
+anything about specific categories.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import random
+import subprocess
+
+from flask import (
+    Flask,
+    Response,
+    jsonify,
+    render_template,
+    request,
+    send_from_directory,
+)
+
+from memi_engine import images, registry
+from memi_engine.config import MemiConfig
+from memi_engine.menu import build_menu
+
+_logger = logging.getLogger(__name__)
+
+# Items excluded via the review system
+_excluded_items: set[str] = set()
+
+
+def create_app(config: MemiConfig, instance_static: str | None = None) -> Flask:
+    """Create a Flask app for a memi instance.
+
+    Args:
+        config: MemiConfig with title, themes, footers, etc.
+        instance_static: Path to the instance's static folder (for logos, etc.).
+            If provided, files here are served alongside the engine's static files.
+    """
+    images.set_wikipedia_lang(config.wikipedia_lang)
+
+    engine_dir = os.path.dirname(__file__)
+    engine_templates = os.path.join(engine_dir, "templates")
+    engine_static = os.path.join(engine_dir, "static")
+
+    # Disable Flask's built-in static handler — we'll handle it ourselves
+    app = Flask(
+        __name__,
+        template_folder=engine_templates,
+        static_folder=None,
+    )
+
+    # Custom static file handler: instance first, then engine
+    static_dirs = (
+        [instance_static, engine_static] if instance_static else [engine_static]
+    )
+
+    @app.route("/static/<path:filename>")
+    def static(filename):
+        for d in static_dirs:
+            if d and os.path.isfile(os.path.join(d, filename)):
+                return send_from_directory(d, filename)
+        return "Not found", 404
+
+    @app.route("/favicon.svg")
+    def favicon():
+        svg = (
+            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">'
+            f'<rect width="64" height="64" rx="14" fill="{config.favicon_color}"/>'
+            '<text x="32" y="46" font-family="system-ui,-apple-system,sans-serif" '
+            'font-size="40" font-weight="700" text-anchor="middle" fill="#fff" '
+            'letter-spacing="-1">m</text>'
+            "</svg>"
+        )
+        return Response(svg, mimetype="image/svg+xml")
+
+    # Detect git version
+    if not config.version:
+        try:
+            config.version = (
+                subprocess.check_output(
+                    ["git", "rev-parse", "--short", "HEAD"],
+                    stderr=subprocess.DEVNULL,
+                )
+                .decode()
+                .strip()
+            )
+        except Exception:
+            config.version = "dev"
+
+    # Load excluded items
+    _load_excluded_items(app)
+
+    # --- Routes ---
+
+    @app.route("/")
+    def index():
+        top_level, subs = build_menu()
+        # Collect all unique filters from all providers
+        all_filters = _collect_filters()
+        return render_template(
+            "index.html",
+            top_level=top_level,
+            subcategories=subs,
+            version=config.version,
+            config=config,
+            filters=all_filters,
+        )
+
+    @app.route("/about")
+    def about():
+        return render_template(
+            "about.html", version=config.version, config=config
+        )
+
+    @app.route("/api/random")
+    def random_item():
+        cats = request.args.get("cats", "")
+        cat_list = [c for c in cats.split(",") if registry.get(c)]
+        if not cat_list:
+            return jsonify({"error": "Unknown category"}), 400
+
+        seen = (
+            set(request.args.get("seen", "").split(","))
+            if request.args.get("seen")
+            else set()
+        )
+
+        category = random.choice(cat_list)
+        provider = registry.get(category)
+        items = list(provider.items)
+
+        # Apply filters
+        for filter_name, filter_map in provider.filters.items():
+            param = request.args.get(filter_name, "")
+            if param:
+                allowed = set()
+                for val in param.split(","):
+                    allowed.update(filter_map.get(val, []))
+                items = [i for i in items if i in allowed]
+                if not items:
+                    return jsonify({"error": f"No items for {filter_name}"}), 400
+
+        items = [i for i in items if i not in _excluded_items]
+        unseen = [i for i in items if i not in seen]
+        if not unseen:
+            return jsonify({"error": "All items seen"}), 400
+        candidates = random.sample(unseen, min(10, len(unseen)))
+
+        for item in candidates:
+            result = provider.get_image(item)
+            if not result or not result.get("image"):
+                continue
+
+            result["item"] = item
+
+            # Clean up name
+            name = result.get("name", item)
+            if "(" in name:
+                name = name.split("(")[0].strip()
+            result["name"] = name
+
+            if provider.override_name:
+                result["name"] = item
+
+            # Tag
+            tag = provider.get_tag(item)
+            if tag:
+                result["tag"] = tag
+                if provider.tag_style:
+                    result["tag_style"] = provider.tag_style
+
+            # Clue
+            clue = provider.get_clue(item)
+            if clue:
+                result["clue"] = clue
+
+            if provider.light_bg:
+                result["light_bg"] = True
+
+            # Footers
+            if provider.footers:
+                result["footers"] = provider.footers
+
+            return jsonify(result)
+
+        return jsonify({"error": "No image found"}), 404
+
+    @app.route("/api/report", methods=["POST"])
+    def report():
+        data = request.get_json(silent=True) or {}
+        item = data.get("item", "")
+        cats = data.get("cats", "")
+        if item:
+            _logger.info(f"REPORTED: {item} (categories: {cats})")
+            logging.getLogger("reports").info(
+                f"REPORTED: {item} (categories: {cats})"
+            )
+        return jsonify({"ok": True})
+
+    @app.route("/healthz")
+    def healthz():
+        return jsonify({"status": "ok", "categories": len(registry.get_all())})
+
+    return app
+
+
+def _collect_filters() -> dict:
+    """Collect all unique filters across all providers.
+
+    Returns a dict like:
+    {
+        "continents": {
+            "categories": ["geography:countries:flags", ...],
+            "options": ["africa", "america", "asia", ...]
+        },
+        ...
+    }
+    """
+    filters: dict = {}
+    for key, provider in registry.get_all().items():
+        for filter_name, filter_map in provider.filters.items():
+            if filter_name not in filters:
+                filters[filter_name] = {
+                    "categories": [],
+                    "options": sorted(filter_map.keys()),
+                }
+            filters[filter_name]["categories"].append(key)
+    return filters
+
+
+def _load_excluded_items(app):
+    """Load excluded items from file if it exists."""
+    # Use current working directory for data files, not the engine package
+    data_dir = os.getcwd()
+    excluded_file = os.path.join(data_dir, "excluded_items.txt")
+    if os.path.isfile(excluded_file):
+        with open(excluded_file) as f:
+            for line in f:
+                line = line.strip()
+                if line:
+                    _excluded_items.add(line)
+
+    # Set up report logging (don't crash if we can't write)
+    report_log = os.path.join(data_dir, "reported_items.log")
+    try:
+        handler = logging.FileHandler(report_log)
+        handler.setFormatter(
+            logging.Formatter("%(asctime)s %(message)s")
+        )
+        logging.getLogger("reports").addHandler(handler)
+    except PermissionError:
+        pass  # Reports won't be saved but app still works
+    logging.getLogger("reports").setLevel(logging.INFO)

memi_engine/config.py

@@ -0,0 +1,66 @@
+"""Configuration for a memi instance."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class MemiConfig:
+    """Configuration for a memi game instance.
+
+    Attributes:
+        title: Game title shown in the header.
+        subtitle: Subtitle shown below the title.
+        themes: List of available theme names.
+        default_theme: Initial theme.
+        sponsor_url: URL for the sponsor link (None to hide).
+        sponsor_text: Text next to the heart icon.
+        about_html: Custom HTML for the about page body.
+        analytics_html: Analytics script HTML (e.g. GoatCounter).
+        footers: Dict of footer_id -> HTML content for attribution footers.
+        related_sites: List of sibling memi games to link from the about page.
+            Each item is {"name": ..., "url": ...}.
+        version: Version string shown in the footer (auto-detected from git).
+    """
+
+    title: str = "memi"
+    subtitle: str = "practise your memory"
+    themes: list[str] = field(
+        default_factory=lambda: [
+            "light", "yellow", "pink", "blue",
+            "green", "brown", "grey", "dark",
+        ]
+    )
+    default_theme: str = "light"
+    sponsor_url: str | None = None
+    sponsor_text: str = "sponsor"
+    about_html: str | None = None
+    analytics_html: str | None = None
+    footers: dict[str, str] = field(default_factory=dict)
+    related_sites: list[dict[str, str]] = field(default_factory=list)
+    version: str = ""
+
+    # UI labels (for i18n)
+    label_theme: str = "theme"
+    label_about: str = "about"
+    label_report: str = "report"
+    label_reported: str = "reported"
+    label_clues_on: str = "clues: on"
+    label_clues_off: str = "clues: off"
+    label_show_letter: str = "show letter"
+    label_pick_category: str = "pick a category"
+    label_loading: str = "loading..."
+    label_all_done: str = "all done! click to start over"
+    label_click_to_reveal: str = "click the image to reveal the answer"
+    label_click_for_new: str = "click again for a new one"
+    label_back: str = "back to playing"
+    label_related_sites: str = "more memi games"
+    label_more: str = "know more"
+    done_html: str = ""  # Custom HTML shown when all items are done
+
+    # Favicon: background of the rounded square (default dark goldenrod)
+    favicon_color: str = "#b8860b"
+
+    # Wikipedia language edition for the default image / "know more" helpers.
+    wikipedia_lang: str = "en"