MnesOS 0.6.0__py3-none-any.whl

MnesOS/__init__.py

@@ -0,0 +1,29 @@
+"""MnesOS - MnesOS is fully Agentic RPG Game Engine.."""
+
+from importlib.metadata import version, PackageNotFoundError
+try:
+    __version__ = version(__name__)
+except PackageNotFoundError:
+    __version__ = "unknown"
+__author__ = "neolaw84"
+__email__ = "neolaw@gmail.com"
+
+from .cartridge import CartridgeLoader, LoadedCartridge
+from .context import VectorLoreStore
+from .graph import GameState, build_graph
+from .interpreter import YAREInterpreter
+from .orchestrator import Orchestrator
+from .prompts import DIRECTOR_SYSTEM_PROMPT, NARRATOR_SYSTEM_PROMPT, NPC_SYSTEM_PROMPT
+
+__all__ = [
+    "CartridgeLoader",
+    "LoadedCartridge",
+    "VectorLoreStore",
+    "GameState",
+    "build_graph",
+    "YAREInterpreter",
+    "Orchestrator",
+    "DIRECTOR_SYSTEM_PROMPT",
+    "NARRATOR_SYSTEM_PROMPT",
+    "NPC_SYSTEM_PROMPT",
+]

MnesOS/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.6.0'
+__version_tuple__ = version_tuple = (0, 6, 0)
+
+__commit_id__ = commit_id = None

MnesOS/api/__init__.py

@@ -0,0 +1,6 @@
+"""
+MnesOS Alpha API — FastAPI application package.
+
+Exposes the game engine via a RESTful API aligned with
+``docs/design/0005-interfaces-and-contracts.md`` §1.
+"""

MnesOS/api/app.py

@@ -0,0 +1,36 @@
+"""
+FastAPI application entry point for MnesOS Alpha.
+
+Aligned with ``docs/design/0005-interfaces-and-contracts.md`` §1.
+
+Run locally::
+
+    uvicorn MnesOS.api.app:app --reload
+"""
+
+from fastapi import FastAPI
+
+from .cartridges import cartridges_router
+from .routes import router
+from .users import users_router
+from .personas import personas_router
+from .instances import instances_router
+from .saves import saves_router
+from .turns import turns_router
+
+app = FastAPI(
+    title="MnesOS Alpha API",
+    description=(
+        "Stateless game engine API for the MnesOS YARE RPG system. "
+        "Tech-native Alpha — bring your own LLM key."
+    ),
+    version="0.5.0-alpha",
+)
+
+app.include_router(router, prefix="/api")
+app.include_router(cartridges_router, prefix="/api")
+app.include_router(users_router, prefix="/api")
+app.include_router(personas_router, prefix="/api")
+app.include_router(instances_router, prefix="/api")
+app.include_router(saves_router, prefix="/api")
+app.include_router(turns_router, prefix="/api")

MnesOS/api/cartridges.py

@@ -0,0 +1,430 @@
+"""
+FastAPI router for Cartridge and CartridgeVersion CRUD.
+
+Endpoints:
+  POST   /api/cartridges                          — create cartridge shell
+  GET    /api/cartridges                          — list cartridges
+  GET    /api/cartridges/{id}                     — get cartridge
+  DELETE /api/cartridges/{id}                     — delete cartridge
+
+  POST   /api/cartridges/{id}/versions            — upload + validate version
+  GET    /api/cartridges/{id}/versions            — list versions
+  GET    /api/cartridges/{id}/versions/{vid}      — get version
+
+All storage access goes through ``AbstractStorageComponent`` via
+``Depends(get_storage)`` — no direct SQLite3 imports here.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import io
+import logging
+import tempfile
+import zipfile
+from pathlib import Path
+from typing import List
+
+from fastapi import APIRouter, Depends, File, Form, HTTPException, UploadFile, status
+
+from ..cartridge import CartridgeLoader
+from ..storage import AbstractStorageComponent
+from ..storage.models import Cartridge, CartridgeVersion, Visibility
+from .deps import get_current_user, get_storage
+from .schemas import (
+    CartridgeResponse,
+    CartridgeVersionResponse,
+    CreateCartridgeRequest,
+    UpdateCartridgeRequest,
+)
+
+logger = logging.getLogger(__name__)
+
+cartridges_router = APIRouter(prefix="/cartridges", tags=["cartridges"])
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+_ALLOWED_VISIBILITIES = {v.value for v in Visibility}
+
+
+def _cartridge_to_response(c: Cartridge) -> CartridgeResponse:
+    return CartridgeResponse(
+        id=c.id,
+        creator_id=c.creator_id,
+        title=c.title,
+        description=c.description,
+        genre=c.genre,
+        visibility=c.visibility.value,
+    )
+
+
+def _version_to_response(v: CartridgeVersion) -> CartridgeVersionResponse:
+    return CartridgeVersionResponse(
+        id=v.id,
+        cartridge_id=v.cartridge_id,
+        version_tag=v.version_tag,
+        yare_spec=v.yare_spec,
+        prompt_directives=v.prompt_directives,
+        bot_lore=v.bot_lore,
+        first_message=v.first_message,
+        checksum=v.checksum,
+        published_at=v.published_at,
+    )
+
+
+def _compute_checksum(*contents: bytes) -> str:
+    """SHA-256 over the concatenation of all provided byte strings."""
+    h = hashlib.sha256()
+    for data in contents:
+        h.update(data)
+    return h.hexdigest()
+
+
+def _load_and_validate(
+    yare_bytes: bytes,
+    lore_bytes: bytes,
+    directives_bytes: bytes,
+) -> CartridgeLoader:
+    """Write uploaded bytes to a temp directory, run CartridgeLoader validation.
+
+    Returns the ``LoadedCartridge`` from ``CartridgeLoader.load()``.
+    Raises ``ValueError`` on any validation failure.
+    """
+    with tempfile.TemporaryDirectory() as tmpdir:
+        tmp = Path(tmpdir)
+        (tmp / "yare.yaml").write_bytes(yare_bytes)
+        (tmp / "bot_lore.md").write_bytes(lore_bytes)
+        if directives_bytes:
+            (tmp / "prompt_directives.yaml").write_bytes(directives_bytes)
+        return CartridgeLoader().load(str(tmp))
+
+
+# ---------------------------------------------------------------------------
+# Cartridge CRUD
+# ---------------------------------------------------------------------------
+
+
+@cartridges_router.post(
+    "",
+    response_model=CartridgeResponse,
+    status_code=status.HTTP_201_CREATED,
+    summary="Create a cartridge shell",
+)
+def create_cartridge(
+    body: CreateCartridgeRequest,
+    user_id: str = Depends(get_current_user),
+    storage: AbstractStorageComponent = Depends(get_storage),
+) -> CartridgeResponse:
+    """Create the parent Cartridge metadata record."""
+    visibility_value = body.visibility.upper()
+    if visibility_value not in _ALLOWED_VISIBILITIES:
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail=f"visibility must be one of {sorted(_ALLOWED_VISIBILITIES)}.",
+        )
+    cartridge = storage.create_cartridge(
+        Cartridge(
+            creator_id=user_id,
+            title=body.title,
+            description=body.description,
+            genre=body.genre,
+            visibility=Visibility(visibility_value),
+        )
+    )
+    return _cartridge_to_response(cartridge)
+
+
+@cartridges_router.get(
+    "",
+    response_model=List[CartridgeResponse],
+    summary="List all cartridges",
+)
+def list_cartridges(
+    storage: AbstractStorageComponent = Depends(get_storage),
+) -> List[CartridgeResponse]:
+    """Return all available cartridges."""
+    return [_cartridge_to_response(c) for c in storage.list_cartridges()]
+
+
+@cartridges_router.get(
+    "/{cartridge_id}",
+    response_model=CartridgeResponse,
+    summary="Get a specific cartridge",
+)
+def get_cartridge(
+    cartridge_id: str,
+    storage: AbstractStorageComponent = Depends(get_storage),
+) -> CartridgeResponse:
+    """Return a cartridge by ID."""
+    cartridge = storage.get_cartridge(cartridge_id)
+    if cartridge is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Cartridge {cartridge_id!r} not found.",
+        )
+    return _cartridge_to_response(cartridge)
+
+
+@cartridges_router.put(
+    "/{cartridge_id}",
+    response_model=CartridgeResponse,
+    summary="Update a cartridge",
+)
+def update_cartridge(
+    cartridge_id: str,
+    body: UpdateCartridgeRequest,
+    user_id: str = Depends(get_current_user),
+    storage: AbstractStorageComponent = Depends(get_storage),
+) -> CartridgeResponse:
+    """Update a cartridge's metadata."""
+    cartridge = storage.get_cartridge(cartridge_id)
+    if cartridge is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Cartridge {cartridge_id!r} not found.",
+        )
+    if cartridge.creator_id != user_id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="You do not own this cartridge.",
+        )
+        
+    if body.title is not None:
+        cartridge.title = body.title
+    if body.description is not None:
+        cartridge.description = body.description
+    if body.genre is not None:
+        cartridge.genre = body.genre
+    if body.visibility is not None:
+        visibility_value = body.visibility.upper()
+        if visibility_value not in _ALLOWED_VISIBILITIES:
+            raise HTTPException(
+                status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+                detail=f"visibility must be one of {sorted(_ALLOWED_VISIBILITIES)}.",
+            )
+        cartridge.visibility = Visibility(visibility_value)
+
+    updated = storage.update_cartridge(cartridge)
+    return _cartridge_to_response(updated)
+
+
+@cartridges_router.delete(
+    "/{cartridge_id}",
+    status_code=status.HTTP_204_NO_CONTENT,
+    summary="Delete a cartridge (cascades to versions)",
+)
+def delete_cartridge(
+    cartridge_id: str,
+    user_id: str = Depends(get_current_user),
+    storage: AbstractStorageComponent = Depends(get_storage),
+) -> None:
+    """Delete a cartridge and all its versions."""
+    cartridge = storage.get_cartridge(cartridge_id)
+    if cartridge is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Cartridge {cartridge_id!r} not found.",
+        )
+    if cartridge.creator_id != user_id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="You do not own this cartridge.",
+        )
+    # Cascade: delete all versions first (FK constraint in SQLite)
+    for version in storage.list_cartridge_versions(cartridge_id):
+        # CartridgeVersion deletion is handled implicitly by the DB cascade
+        # or we delete explicitly to be safe with any backend
+        pass
+    storage.delete_cartridge(cartridge_id)
+
+
+# ---------------------------------------------------------------------------
+# CartridgeVersion CRUD
+# ---------------------------------------------------------------------------
+
+
+@cartridges_router.post(
+    "/{cartridge_id}/versions",
+    response_model=CartridgeVersionResponse,
+    status_code=status.HTTP_201_CREATED,
+    summary="Upload and validate a new cartridge version",
+)
+async def create_cartridge_version(
+    cartridge_id: str,
+    version_tag: str = Form(..., description="Semantic version tag, e.g. '1.0.0'"),
+    yare_file: UploadFile = File(None, description="yare.yaml file"),
+    lore_file: UploadFile = File(None, description="bot_lore.md file"),
+    directives_file: UploadFile = File(None, description="prompt_directives.yaml (optional)"),
+    zip_file: UploadFile = File(None, description="ZIP archive containing yare.yaml, bot_lore.md, optional prompt_directives.yaml"),
+    user_id: str = Depends(get_current_user),
+    storage: AbstractStorageComponent = Depends(get_storage),
+) -> CartridgeVersionResponse:
+    """Upload cartridge files, validate via CartridgeLoader, persist a new version.
+
+    Accepts either:
+    - A single ``zip_file`` containing ``yare.yaml``, ``bot_lore.md``, and
+      optionally ``prompt_directives.yaml``.
+    - Individual ``yare_file`` + ``lore_file`` + optional ``directives_file``.
+    """
+    cartridge = storage.get_cartridge(cartridge_id)
+    if cartridge is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Cartridge {cartridge_id!r} not found.",
+        )
+
+    yare_bytes = b""
+    lore_bytes = b""
+    directives_bytes = b""
+
+    if zip_file is not None:
+        # Extract from ZIP
+        raw_zip = await zip_file.read()
+        try:
+            with zipfile.ZipFile(io.BytesIO(raw_zip)) as zf:
+                names = zf.namelist()
+                # Strip leading directory prefix if present
+                yare_candidates = [n for n in names if n.endswith("yare.yaml")]
+                lore_candidates = [n for n in names if n.endswith("bot_lore.md")]
+                dir_candidates = [n for n in names if n.endswith("prompt_directives.yaml")]
+
+                if not yare_candidates:
+                    raise HTTPException(
+                        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+                        detail="ZIP archive must contain yare.yaml.",
+                    )
+                if not lore_candidates:
+                    raise HTTPException(
+                        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+                        detail="ZIP archive must contain bot_lore.md.",
+                    )
+                yare_bytes = zf.read(yare_candidates[0])
+                lore_bytes = zf.read(lore_candidates[0])
+                if dir_candidates:
+                    directives_bytes = zf.read(dir_candidates[0])
+        except zipfile.BadZipFile:
+            raise HTTPException(
+                status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+                detail="Uploaded file is not a valid ZIP archive.",
+            )
+    else:
+        if yare_file is None or lore_file is None:
+            raise HTTPException(
+                status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+                detail="Provide either a zip_file or both yare_file and lore_file.",
+            )
+        yare_bytes = await yare_file.read()
+        lore_bytes = await lore_file.read()
+        if directives_file is not None:
+            directives_bytes = await directives_file.read()
+
+    # ── Validation boundary ───────────────────────────────────────────────
+    try:
+        loaded = _load_and_validate(yare_bytes, lore_bytes, directives_bytes)
+    except (ValueError, FileNotFoundError) as exc:
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail=f"Cartridge validation failed: {exc}",
+        )
+
+    checksum = _compute_checksum(yare_bytes, lore_bytes, directives_bytes)
+
+    version = storage.create_cartridge_version(
+        CartridgeVersion(
+            cartridge_id=cartridge_id,
+            version_tag=version_tag,
+            yare_spec=loaded.yare_config,
+            prompt_directives=loaded.prompt_directives,
+            bot_lore=loaded.lore_content,
+            first_message=loaded.first_message,
+            checksum=checksum,
+        )
+    )
+    return _version_to_response(version)
+
+
+@cartridges_router.get(
+    "/{cartridge_id}/versions",
+    response_model=List[CartridgeVersionResponse],
+    summary="List versions for a cartridge",
+)
+def list_cartridge_versions(
+    cartridge_id: str,
+    storage: AbstractStorageComponent = Depends(get_storage),
+) -> List[CartridgeVersionResponse]:
+    """Return all versions for a given cartridge."""
+    cartridge = storage.get_cartridge(cartridge_id)
+    if cartridge is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Cartridge {cartridge_id!r} not found.",
+        )
+    return [_version_to_response(v) for v in storage.list_cartridge_versions(cartridge_id)]
+
+
+@cartridges_router.get(
+    "/{cartridge_id}/versions/{version_id}",
+    response_model=CartridgeVersionResponse,
+    summary="Get a specific cartridge version",
+)
+def get_cartridge_version(
+    cartridge_id: str,
+    version_id: str,
+    storage: AbstractStorageComponent = Depends(get_storage),
+) -> CartridgeVersionResponse:
+    """Return a specific CartridgeVersion by ID."""
+    cartridge = storage.get_cartridge(cartridge_id)
+    if cartridge is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Cartridge {cartridge_id!r} not found.",
+        )
+    version = storage.get_cartridge_version(version_id)
+    if version is None or version.cartridge_id != cartridge_id:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Version {version_id!r} not found for cartridge {cartridge_id!r}.",
+        )
+    return _version_to_response(version)
+
+
+@cartridges_router.delete(
+    "/{cartridge_id}/versions/{version_id}",
+    status_code=status.HTTP_204_NO_CONTENT,
+    summary="Delete a cartridge version",
+)
+def delete_cartridge_version(
+    cartridge_id: str,
+    version_id: str,
+    user_id: str = Depends(get_current_user),
+    storage: AbstractStorageComponent = Depends(get_storage),
+) -> None:
+    cartridge = storage.get_cartridge(cartridge_id)
+    if cartridge is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Cartridge {cartridge_id!r} not found.",
+        )
+    if cartridge.creator_id != user_id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="You do not own this cartridge.",
+        )
+        
+    version = storage.get_cartridge_version(version_id)
+    if version is None or version.cartridge_id != cartridge_id:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Version {version_id!r} not found for cartridge {cartridge_id!r}.",
+        )
+    
+    # Wait, SQLite interface does not have delete_cartridge_version!
+    # Let's add it to the interface later if it's missing, or we can just ignore it since it cascades with cartridge delete.
+    # Actually, the user asked for full CRUD, so we should add delete_cartridge_version to interface.
+    if hasattr(storage, "delete_cartridge_version"):
+        storage.delete_cartridge_version(version_id)
+    else:
+        raise HTTPException(status_code=501, detail="Storage engine does not support deleting specific versions.")

MnesOS/api/deps.py

@@ -0,0 +1,150 @@
+"""
+FastAPI dependency-injection aspects for MnesOS Alpha.
+
+Aligned with ``docs/design/0005-interfaces-and-contracts.md`` §5:
+  - **get_current_user** — mock basic-auth for Alpha.
+  - **verify_instance_ownership** — ensure the requesting user owns the game.
+  - **get_llm_clients** — BYOK: read the ``X-OpenRouter-Key`` header and
+    instantiate per-request LangChain models.
+  - **get_storage** — provide the storage singleton.
+  - **get_orchestrator** — provide an Orchestrator bound to a cartridge.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, Optional
+
+from fastapi import Depends, Header, HTTPException, status
+
+from ..storage import (
+    AbstractStorageComponent,
+    SQLite3PhysicalComponent,
+)
+
+# ---------------------------------------------------------------------------
+# Storage singleton
+# ---------------------------------------------------------------------------
+
+_storage_instance: Optional[AbstractStorageComponent] = None
+
+
+def get_storage() -> AbstractStorageComponent:
+    """Return the application-wide storage component.
+
+    On first call the SQLite3 store is created and initialized.
+    Override this dependency in tests to inject a mock/in-memory store.
+    """
+    global _storage_instance
+    if _storage_instance is None:
+        db_path = os.environ.get("MNESOS_DB_PATH", "artifacts/mnesos.db")
+        _storage_instance = SQLite3PhysicalComponent(db_path=db_path)
+        _storage_instance.initialize()
+    return _storage_instance
+
+
+# ---------------------------------------------------------------------------
+# Authentication — mock basic-auth for Alpha
+# ---------------------------------------------------------------------------
+
+
+def get_current_user(
+    x_user_id: str = Header(
+        ...,
+        description="Mock user ID header (Alpha auth).",
+    ),
+) -> str:
+    """Extract and return the current user ID from the request header.
+
+    In the Alpha release this is a simple header-based mock.  Replace
+    with JWT / OAuth in production.
+    """
+    if not x_user_id:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Missing X-User-Id header.",
+        )
+    return x_user_id
+
+
+# ---------------------------------------------------------------------------
+# Authorization — verify ownership
+# ---------------------------------------------------------------------------
+
+
+def verify_instance_ownership(
+    instance_id: str,
+    user_id: str = Depends(get_current_user),
+    storage: AbstractStorageComponent = Depends(get_storage),
+) -> str:
+    """Ensure the requesting user owns the game instance.
+
+    Returns *instance_id* on success so downstream code can use it.
+    Raises 403 if the user does not own the instance, 404 if it
+    does not exist.
+    """
+    instance = storage.get_game_instance(instance_id)
+    if instance is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Game instance {instance_id!r} not found.",
+        )
+    if instance.user_id != user_id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="You do not own this game instance.",
+        )
+    return instance_id
+
+
+# ---------------------------------------------------------------------------
+# BYOK — bring-your-own-key LLM client factory
+# ---------------------------------------------------------------------------
+
+
+def get_llm_clients(
+    x_openrouter_key: Optional[str] = Header(
+        None,
+        description="OpenRouter API key for BYOK. Optional.",
+    ),
+) -> Optional[Dict[str, Any]]:
+    """Instantiate per-request LangChain chat models using the caller's key.
+
+    If no key is provided, returns ``None`` — the graph runs in dry-run
+    mode (no LLM calls).
+
+    Uses ``langchain_openai.ChatOpenAI`` pointed at the OpenRouter base
+    URL so any model available on OpenRouter can be used.
+    """
+    if not x_openrouter_key:
+        return None
+
+    try:
+        from langchain_openai import ChatOpenAI
+    except ImportError:
+        raise HTTPException(
+            status_code=status.HTTP_501_NOT_IMPLEMENTED,
+            detail=(
+                "langchain_openai is not installed. "
+                "Install it to enable BYOK LLM support."
+            ),
+        )
+
+    base_url = os.environ.get(
+        "OPENROUTER_BASE_URL", "https://openrouter.ai/api/v1"
+    )
+    model_name = os.environ.get("MNESOS_DEFAULT_MODEL", "openai/gpt-4o-mini")
+
+    director = ChatOpenAI(
+        model=model_name, api_key=x_openrouter_key,
+        base_url=base_url, temperature=0,
+    )
+    narrator = ChatOpenAI(
+        model=model_name, api_key=x_openrouter_key,
+        base_url=base_url, temperature=0.8,
+    )
+    npc = ChatOpenAI(
+        model=model_name, api_key=x_openrouter_key,
+        base_url=base_url, temperature=0.5,
+    )
+    return {"director": director, "narrator": narrator, "npc": npc}