ifcraftcorpus 1.1.0__py3-none-any.whl → 1.2.0__py3-none-any.whl

ifcraftcorpus/cli.py

@@ -19,6 +19,10 @@ import argparse
 import json
 import sys
 from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ifcraftcorpus.providers import EmbeddingProvider
 
 
 def cmd_info(args: argparse.Namespace) -> int:
@@ -129,7 +133,7 @@ def cmd_embeddings_build(args: argparse.Namespace) -> int:
     )
 
     # Get provider
-    provider = None
+    provider: EmbeddingProvider | None = None
     if args.provider:
         if args.provider == "ollama":
             provider = OllamaEmbeddings(model=args.model, host=args.ollama_host)
@@ -273,7 +277,8 @@ def main() -> int:
         emb_parser.print_help()
         return 0
 
-    return args.func(args)
+    result: int = args.func(args)
+    return result
 
 
 if __name__ == "__main__":

ifcraftcorpus/embeddings.py

@@ -44,10 +44,13 @@ from __future__ import annotations
 import json
 import logging
 from pathlib import Path
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 import numpy as np
 
+if TYPE_CHECKING:
+    from sentence_transformers import SentenceTransformer
+
 if TYPE_CHECKING:
     from ifcraftcorpus.index import CorpusIndex
     from ifcraftcorpus.providers import EmbeddingProvider
@@ -107,7 +110,8 @@ class EmbeddingIndex:
         """
         self._provider = provider
         self._embeddings: np.ndarray | None = None
-        self._metadata: list[dict] = []
+        self._metadata: list[dict[str, Any]] = []
+        self._st_model: SentenceTransformer | None = None
 
         # For backward compatibility / persistence
         if provider:
@@ -117,7 +121,6 @@ class EmbeddingIndex:
             self.model_name = model_name
             self._provider_name = "sentence-transformers"
             # Lazy-load sentence-transformers model
-            self._st_model = None
             if not lazy_load:
                 self._load_st_model()
 
@@ -126,7 +129,7 @@ class EmbeddingIndex:
         """Get the provider name."""
         return self._provider_name
 
-    def _load_st_model(self):
+    def _load_st_model(self) -> SentenceTransformer:
         """Load sentence-transformers model (fallback)."""
         if self._st_model is None:
             try:
@@ -148,12 +151,13 @@ class EmbeddingIndex:
         else:
             # Fallback to sentence-transformers
             model = self._load_st_model()
-            return model.encode(texts, show_progress_bar=False, convert_to_numpy=True)
+            embeddings = model.encode(texts, show_progress_bar=False, convert_to_numpy=True)
+            return np.asarray(embeddings)
 
     def add_texts(
         self,
         texts: list[str],
-        metadata: list[dict],
+        metadata: list[dict[str, Any]],
     ) -> None:
         """Add texts with metadata to the index.
 
@@ -185,7 +189,7 @@ class EmbeddingIndex:
         *,
         top_k: int = 10,
         cluster: str | None = None,
-    ) -> list[tuple[dict, float]]:
+    ) -> list[tuple[dict[str, Any], float]]:
         """Search for semantically similar texts.
 
         Args:

ifcraftcorpus/index.py

@@ -48,6 +48,7 @@ from __future__ import annotations
 import sqlite3
 from dataclasses import dataclass
 from pathlib import Path
+from typing import Any
 
 from ifcraftcorpus.parser import Document, parse_directory
 
@@ -462,7 +463,7 @@ class CorpusIndex:
         cursor = self.conn.execute("SELECT DISTINCT cluster FROM documents ORDER BY cluster")
         return [row["cluster"] for row in cursor]
 
-    def get_document(self, name: str) -> dict | None:
+    def get_document(self, name: str) -> dict[str, Any] | None:
         """Get a document by name with all its sections.
 
         Retrieves complete document data including metadata and all
@@ -535,7 +536,8 @@ class CorpusIndex:
             Count of documents in the index.
         """
         cursor = self.conn.execute("SELECT COUNT(*) FROM documents")
-        return cursor.fetchone()[0]
+        result = cursor.fetchone()
+        return int(result[0]) if result else 0
 
 
 def build_index(corpus_dir: Path, output_path: Path) -> CorpusIndex:

ifcraftcorpus/mcp_server.py

@@ -10,6 +10,7 @@ Features:
     - Retrieve specific documents
     - List available documents and clusters
     - Get corpus statistics
+    - Subagent prompts for IF authoring workflows
 
 Installation:
     The MCP server requires the ``mcp`` extra::
@@ -51,18 +52,72 @@ Tools:
     corpus_stats: Get corpus statistics.
     embeddings_status: Check embedding provider and index status.
     build_embeddings: Build or rebuild semantic search embeddings.
+
+Prompts:
+    if_story_architect: System prompt for an IF Story Architect agent.
+    if_prose_writer: System prompt for an IF Prose Writer agent.
+    if_quality_reviewer: System prompt for an IF Quality Reviewer agent.
+    if_genre_consultant: System prompt for an IF Genre Consultant agent.
+    if_world_curator: System prompt for an IF World Curator agent.
+    if_platform_advisor: System prompt for an IF Platform Advisor agent.
 """
 
 from __future__ import annotations
 
 import os
+import sys
 from pathlib import Path
-from typing import Literal
+from typing import Any, Literal
 
 from fastmcp import FastMCP
+from fastmcp.prompts import Message
+from mcp.types import PromptMessage
 
 from ifcraftcorpus.search import Corpus
 
+
+def _get_subagents_dir() -> Path:
+    """Get the path to the subagents directory.
+
+    Returns the subagents directory from either:
+    1. The installed package location (share/ifcraftcorpus/subagents)
+    2. The development location (project root/subagents)
+    """
+    # Try installed location first
+    if sys.prefix != sys.base_prefix:
+        # We're in a virtual environment
+        installed_path = Path(sys.prefix) / "share" / "ifcraftcorpus" / "subagents"
+        if installed_path.exists():
+            return installed_path
+
+    # Try development location (relative to this file)
+    dev_path = Path(__file__).parent.parent.parent.parent / "subagents"
+    if dev_path.exists():
+        return dev_path
+
+    # Fallback to current directory
+    return Path("subagents")
+
+
+def _load_subagent_template(name: str) -> str:
+    """Load a subagent template by name.
+
+    Args:
+        name: Template name (without .md extension)
+
+    Returns:
+        The template content as a string.
+
+    Raises:
+        FileNotFoundError: If the template doesn't exist.
+    """
+    subagents_dir = _get_subagents_dir()
+    template_path = subagents_dir / f"{name}.md"
+    if not template_path.exists():
+        raise FileNotFoundError(f"Subagent template not found: {template_path}")
+    return template_path.read_text(encoding="utf-8")
+
+
 # Initialize FastMCP server
 mcp = FastMCP(
     name="IF Craft Corpus",
@@ -98,7 +153,7 @@ def search_corpus(
     query: str,
     cluster: str | None = None,
     limit: int = 5,
-) -> list[dict]:
+) -> list[dict[str, Any]]:
     """Search the IF Craft Corpus for writing guidance.
 
     Use this tool to find craft advice for interactive fiction writing,
@@ -136,7 +191,7 @@ def search_corpus(
 
 
 @mcp.tool
-def get_document(name: str) -> dict | None:
+def get_document(name: str) -> dict[str, Any] | None:
     """Get a specific document from the IF Craft Corpus.
 
     Use this tool when you need the full content of a known document,
@@ -154,7 +209,7 @@ def get_document(name: str) -> dict | None:
 
 
 @mcp.tool
-def list_documents(cluster: str | None = None) -> list[dict]:
+def list_documents(cluster: str | None = None) -> list[dict[str, Any]]:
     """List all documents in the IF Craft Corpus.
 
     Use this tool to discover what craft guidance is available.
@@ -175,7 +230,7 @@ def list_documents(cluster: str | None = None) -> list[dict]:
 
 
 @mcp.tool
-def list_clusters() -> list[dict]:
+def list_clusters() -> list[dict[str, Any]]:
     """List all topic clusters in the IF Craft Corpus.
 
     Each cluster groups related craft documents. Use this to understand
@@ -189,7 +244,7 @@ def list_clusters() -> list[dict]:
     docs = corpus.list_documents()
 
     # Count documents per cluster
-    counts = {}
+    counts: dict[str, int] = {}
     for d in docs:
         c = d["cluster"]
         counts[c] = counts.get(c, 0) + 1
@@ -198,7 +253,7 @@ def list_clusters() -> list[dict]:
 
 
 @mcp.tool
-def corpus_stats() -> dict:
+def corpus_stats() -> dict[str, Any]:
     """Get statistics about the IF Craft Corpus.
 
     Returns:
@@ -214,7 +269,7 @@ def corpus_stats() -> dict:
 
 
 @mcp.tool
-def embeddings_status() -> dict:
+def embeddings_status() -> dict[str, Any]:
     """Get status of embedding providers and index.
 
     Returns information about available embedding providers (Ollama, OpenAI,
@@ -223,7 +278,7 @@ def embeddings_status() -> dict:
     Returns:
         Dict with provider availability and embedding index status.
     """
-    result = {
+    result: dict[str, Any] = {
         "semantic_search_available": get_corpus().has_semantic_search,
         "providers": {},
         "saved_embeddings": None,
@@ -281,7 +336,7 @@ def embeddings_status() -> dict:
 def build_embeddings(
     provider: str | None = None,
     force: bool = False,
-) -> dict:
+) -> dict[str, Any]:
     """Build or rebuild the embedding index for semantic search.
 
     Builds embeddings for all corpus documents using the specified provider.
@@ -373,6 +428,257 @@ def build_embeddings(
     }
 
 
+# =============================================================================
+# Subagent Prompts
+# =============================================================================
+#
+# These prompts provide system prompts for specialized IF authoring agents.
+# Each agent has a specific role in the IF creation workflow.
+
+
+@mcp.prompt(
+    name="if_story_architect",
+    description="System prompt for an IF Story Architect - an orchestrator agent that "
+    "plans narrative structure, decomposes IF projects, and coordinates creation.",
+)
+def if_story_architect_prompt(
+    project_name: str | None = None,
+    genre: str | None = None,
+) -> list[PromptMessage]:
+    """Get the IF Story Architect system prompt.
+
+    Args:
+        project_name: Optional project name to include in the prompt context.
+        genre: Optional genre to emphasize (fantasy, horror, mystery, etc.).
+
+    Returns:
+        System prompt messages for the Story Architect agent.
+    """
+    template = _load_subagent_template("if_story_architect")
+
+    # Add optional context
+    context_parts = []
+    if project_name:
+        context_parts.append(f"Project: {project_name}")
+    if genre:
+        context_parts.append(f"Genre: {genre}")
+
+    if context_parts:
+        context = "\n\n---\n\n## Current Project Context\n\n" + "\n".join(context_parts)
+        template = template + context
+
+    return [Message(template, role="user")]
+
+
+@mcp.prompt(
+    name="if_prose_writer",
+    description="System prompt for an IF Prose Writer - a specialist agent that "
+    "creates narrative content including prose, dialogue, and scene text.",
+)
+def if_prose_writer_prompt(
+    genre: str | None = None,
+    pov: str | None = None,
+) -> list[PromptMessage]:
+    """Get the IF Prose Writer system prompt.
+
+    Args:
+        genre: Optional genre to emphasize (fantasy, horror, mystery, etc.).
+        pov: Optional point of view (first, second, third).
+
+    Returns:
+        System prompt messages for the Prose Writer agent.
+    """
+    template = _load_subagent_template("if_prose_writer")
+
+    # Add optional context
+    context_parts = []
+    if genre:
+        context_parts.append(f"Genre: {genre}")
+    if pov:
+        context_parts.append(f"Point of View: {pov}")
+
+    if context_parts:
+        context = "\n\n---\n\n## Current Project Context\n\n" + "\n".join(context_parts)
+        template = template + context
+
+    return [Message(template, role="user")]
+
+
+@mcp.prompt(
+    name="if_quality_reviewer",
+    description="System prompt for an IF Quality Reviewer - a validator agent that "
+    "reviews IF content for craft quality, consistency, and standards compliance.",
+)
+def if_quality_reviewer_prompt(
+    focus_areas: str | None = None,
+) -> list[PromptMessage]:
+    """Get the IF Quality Reviewer system prompt.
+
+    Args:
+        focus_areas: Optional comma-separated list of areas to focus on
+                    (e.g., "voice,pacing,continuity").
+
+    Returns:
+        System prompt messages for the Quality Reviewer agent.
+    """
+    template = _load_subagent_template("if_quality_reviewer")
+
+    if focus_areas:
+        context = f"\n\n---\n\n## Review Focus\n\nPrioritize these areas: {focus_areas}"
+        template = template + context
+
+    return [Message(template, role="user")]
+
+
+@mcp.prompt(
+    name="if_genre_consultant",
+    description="System prompt for an IF Genre Consultant - a researcher agent that "
+    "provides genre-specific guidance on conventions, tropes, and reader expectations.",
+)
+def if_genre_consultant_prompt(
+    primary_genre: str | None = None,
+    secondary_genre: str | None = None,
+) -> list[PromptMessage]:
+    """Get the IF Genre Consultant system prompt.
+
+    Args:
+        primary_genre: Optional primary genre to focus on.
+        secondary_genre: Optional secondary genre for blending advice.
+
+    Returns:
+        System prompt messages for the Genre Consultant agent.
+    """
+    template = _load_subagent_template("if_genre_consultant")
+
+    context_parts = []
+    if primary_genre:
+        context_parts.append(f"Primary Genre: {primary_genre}")
+    if secondary_genre:
+        context_parts.append(f"Secondary Genre: {secondary_genre}")
+
+    if context_parts:
+        context = "\n\n---\n\n## Genre Focus\n\n" + "\n".join(context_parts)
+        template = template + context
+
+    return [Message(template, role="user")]
+
+
+@mcp.prompt(
+    name="if_world_curator",
+    description="System prompt for an IF World Curator - a curator agent that "
+    "maintains world consistency, manages canon, and ensures setting coherence.",
+)
+def if_world_curator_prompt(
+    world_name: str | None = None,
+    setting_type: str | None = None,
+) -> list[PromptMessage]:
+    """Get the IF World Curator system prompt.
+
+    Args:
+        world_name: Optional name of the world/setting.
+        setting_type: Optional setting type (e.g., "fantasy medieval", "sci-fi space").
+
+    Returns:
+        System prompt messages for the World Curator agent.
+    """
+    template = _load_subagent_template("if_world_curator")
+
+    context_parts = []
+    if world_name:
+        context_parts.append(f"World: {world_name}")
+    if setting_type:
+        context_parts.append(f"Setting Type: {setting_type}")
+
+    if context_parts:
+        context = "\n\n---\n\n## World Context\n\n" + "\n".join(context_parts)
+        template = template + context
+
+    return [Message(template, role="user")]
+
+
+@mcp.prompt(
+    name="if_platform_advisor",
+    description="System prompt for an IF Platform Advisor - a researcher agent that "
+    "provides guidance on tools, platforms, and technical implementation.",
+)
+def if_platform_advisor_prompt(
+    target_platform: str | None = None,
+    team_size: str | None = None,
+) -> list[PromptMessage]:
+    """Get the IF Platform Advisor system prompt.
+
+    Args:
+        target_platform: Optional target platform if already decided.
+        team_size: Optional team size (solo, small, large).
+
+    Returns:
+        System prompt messages for the Platform Advisor agent.
+    """
+    template = _load_subagent_template("if_platform_advisor")
+
+    context_parts = []
+    if target_platform:
+        context_parts.append(f"Target Platform: {target_platform}")
+    if team_size:
+        context_parts.append(f"Team Size: {team_size}")
+
+    if context_parts:
+        context = "\n\n---\n\n## Project Context\n\n" + "\n".join(context_parts)
+        template = template + context
+
+    return [Message(template, role="user")]
+
+
+@mcp.tool
+def list_subagents() -> list[dict[str, Any]]:
+    """List all available IF subagent prompts.
+
+    Returns a list of subagent templates that can be used as system prompts
+    for specialized IF authoring agents.
+
+    Returns:
+        List of subagents with name, description, and parameters.
+    """
+    return [
+        {
+            "name": "if_story_architect",
+            "description": "Orchestrator that plans narrative structure and coordinates creation",
+            "archetype": "orchestrator",
+            "parameters": ["project_name", "genre"],
+        },
+        {
+            "name": "if_prose_writer",
+            "description": "Specialist that creates narrative prose, dialogue, and scene text",
+            "archetype": "creator",
+            "parameters": ["genre", "pov"],
+        },
+        {
+            "name": "if_quality_reviewer",
+            "description": "Validator agent that reviews content for quality and consistency",
+            "archetype": "validator",
+            "parameters": ["focus_areas"],
+        },
+        {
+            "name": "if_genre_consultant",
+            "description": "Researcher agent for genre conventions, tropes, and expectations",
+            "archetype": "researcher",
+            "parameters": ["primary_genre", "secondary_genre"],
+        },
+        {
+            "name": "if_world_curator",
+            "description": "Curator agent that maintains world consistency and canon",
+            "archetype": "curator",
+            "parameters": ["world_name", "setting_type"],
+        },
+        {
+            "name": "if_platform_advisor",
+            "description": "Researcher agent for tools, platforms, and technical implementation",
+            "archetype": "researcher",
+            "parameters": ["target_platform", "team_size"],
+        },
+    ]
+
+
 def run_server(
     transport: Literal["stdio", "http"] = "stdio",
     host: str = "127.0.0.1",

ifcraftcorpus/providers.py

@@ -21,7 +21,7 @@ from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    pass
+    from sentence_transformers import SentenceTransformer
 
 logger = logging.getLogger(__name__)
 
@@ -314,12 +314,12 @@ class SentenceTransformersEmbeddings(EmbeddingProvider):
         """
         self._model_name = model or DEFAULT_MODELS["sentence-transformers"]
         self._dimension = MODEL_DIMENSIONS.get(self._model_name, 384)
-        self._model_instance = None
+        self._model_instance: SentenceTransformer | None = None
 
         if not lazy_load:
             self._load_model()
 
-    def _load_model(self):
+    def _load_model(self) -> SentenceTransformer:
         """Load the sentence transformer model."""
         if self._model_instance is None:
             try:

ifcraftcorpus/search.py

@@ -42,11 +42,12 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from pathlib import Path
-from typing import TYPE_CHECKING, Literal
+from typing import TYPE_CHECKING, Any, Literal
 
 from ifcraftcorpus.index import CorpusIndex
 
 if TYPE_CHECKING:
+    from ifcraftcorpus.embeddings import EmbeddingIndex
     from ifcraftcorpus.providers import EmbeddingProvider
 
 
@@ -190,7 +191,7 @@ class Corpus:
         self._use_bundled = use_bundled
 
         self._fts_index: CorpusIndex | None = None
-        self._embedding_index = None  # Lazy loaded
+        self._embedding_index: EmbeddingIndex | None = None  # Lazy loaded
 
     def _get_corpus_dir(self) -> Path:
         """Get the corpus directory path.
@@ -247,7 +248,7 @@ class Corpus:
                 self._fts_index.build_from_directory(corpus_dir)
         return self._fts_index
 
-    def _get_embedding_index(self):
+    def _get_embedding_index(self) -> EmbeddingIndex | None:
         """Get the embedding index for semantic search.
 
         Lazily loads the embedding index if embeddings_path was provided.
@@ -445,18 +446,21 @@ class Corpus:
 
         # Deduplicate and sort by score
         if mode == "hybrid":
-            seen = set()
-            unique_results = []
-            for r in sorted(results, key=lambda x: x.score, reverse=True):
-                key = (r.document_name, r.section_heading)
+            seen: set[tuple[str, str | None]] = set()
+            unique_results: list[CorpusResult] = []
+            sorted_results: list[CorpusResult] = sorted(
+                results, key=lambda x: x.score, reverse=True
+            )
+            for result in sorted_results:
+                key = (result.document_name, result.section_heading)
                 if key not in seen:
                     seen.add(key)
-                    unique_results.append(r)
+                    unique_results.append(result)
             results = unique_results[:limit]
 
         return results
 
-    def get_document(self, name: str) -> dict | None:
+    def get_document(self, name: str) -> dict[str, Any] | None:
         """Get a document by name with all its sections.
 
         Retrieves complete document data including metadata and all