ifcraftcorpus 1.11.0

Interactive fiction craft corpus with search library and MCP server

IF Craft Corpus

A curated knowledge base for interactive fiction writing craft, with a Python library for search and RAG applications.

Features

• 48 documents covering narrative structure, prose craft, genre conventions, and more
• 1300+ searchable sections with detailed craft guidance
• Python library for programmatic access with FTS and optional semantic search
• Pre-built index for instant search without setup

Installation

pip install ifcraftcorpus

For semantic search with embeddings:

pip install ifcraftcorpus[embeddings]

Quick Start

from ifcraftcorpus import Corpus

# Initialize corpus (uses bundled content and pre-built index)
corpus = Corpus()

# Full-text search
results = corpus.search("dialogue subtext techniques")
for r in results:
    print(f"{r.document}: {r.heading}")
    print(f"  {r.snippet}...")

# Browse by cluster
docs = corpus.list_documents(cluster="prose-and-language")

# Get full document
doc = corpus.get_document("dialogue_craft")
print(doc.title, doc.summary)

Semantic Search (Optional)

# Enable semantic search with sentence-transformers
corpus = Corpus(embeddings="all-MiniLM-L6-v2")

# Hybrid search combines FTS + semantic
results = corpus.search(
    "how to write realistic conversations",
    mode="hybrid"
)

Corpus Clusters

Cluster	Documents	Focus
narrative-structure	9	Pacing, beats, branching, scene structure
prose-and-language	7	Dialogue, voice, style, prose patterns
craft-foundations	10	Quality standards, testing, workflow, tools
world-and-setting	5	Worldbuilding, canon, setting, naming
genre-conventions	7	Mystery, horror, fantasy, romance, sci-fi, tropes
audience-and-access	3	Accessibility, localization, targeting
emotional-design	2	Emotional beats, catharsis
scope-and-planning	1	Scope, length, planning
agent-design	3	Multi-agent patterns, prompt engineering
game-design	1	Mechanics design patterns

Verbose Logging

Set LOG_LEVEL (e.g., INFO, DEBUG) or the convenience flag VERBOSE=1 before launching ifcraftcorpus, ifcraftcorpus-mcp, or the Docker image to emit detailed logs to stderr. Example:

LOG_LEVEL=DEBUG ifcraftcorpus-mcp

# Docker
docker run -p 8000:8000 \
  -e LOG_LEVEL=DEBUG \
  ghcr.io/pvliesdonk/if-craft-corpus

Logs never touch stdout, so stdio transports remain compatible.

Documentation

Full documentation: https://pvliesdonk.github.io/if-craft-corpus

License

• Code: MIT License (see LICENSE)
• Content: CC-BY-4.0 (see LICENSE-CONTENT)

Contributing

Contributions welcome! Please open an issue or PR.