Construct3 RAG

https://github.com/xhxiaiein/construct3-rag
Admin
A Retrieval-Augmented Generation (RAG) based question-answering assistant for Construct 3...
Tokens:7,172
Snippets:34
Trust Score:8.1
License:MIT
Update:9 months ago
Show doc for...
Tokens:
Raw
### Launch Gradio Web Interface and Programmatic Usage (Python)

Source: https://context7.com/xhxiaiein/construct3-rag/llms.txt

This Python code snippet shows how to launch the interactive Gradio web UI for the RAG system. It also demonstrates programmatic usage by getting the RAG instance and using the ask_stream function to get streaming responses.

```Python
from src.app.gradio_ui import main, get_rag, ask_stream

# Start web interface (auto-loads models on startup)
# Accessible at http://127.0.0.1:7860
main()

# Programmatic usage

# Get singleton RAG instance
rag = get_rag()

# Stream response generator
for text in ask_stream("如何使用 Platform 行为?"):
    print(text)
```

--------------------------------

### Data Indexing System API

Source: https://context7.com/xhxiaiein/construct3-rag/llms.txt

This API provides functionalities to index Construct 3 documentation, plugin schemas, and example projects into a Qdrant vector database. It supports full data indexing and manual indexing workflows.

```APIDOC
## Data Indexing System

### Description
Index Construct 3 documentation and schemas into Qdrant vector database. Supports automatic indexing of all data sources and manual workflows for creating and indexing documents.

### Method
`Indexer` class and `index_all_data` function

### Endpoint
N/A (Python library)

### Parameters
#### `index_all_data` function parameters
- **rebuild** (bool) - Optional - If True, rebuilds existing collections. Defaults to False.

#### `Indexer` Initialization Parameters
- **qdrant_host** (str) - Required - Hostname for the Qdrant vector database.
- **qdrant_port** (int) - Required - Port for the Qdrant vector database.
- **embedding_model** (str) - Required - The name of the embedding model to use (e.g., "BAAI/bge-m3").

#### `create_collection` method parameters
- **collection_name** (str) - Required - The name of the collection to create.
- **recreate** (bool) - Optional - If True, drops and recreates the collection. Defaults to False.

#### `index_documents` method parameters
- **collection_name** (str) - Required - The name of the collection to index documents into.
- **documents** (list) - Required - A list of document objects to index. Each object should have 'text' and 'metadata' keys.
- **batch_size** (int) - Optional - The number of documents to index in each batch. Defaults to 100.

#### `search` method parameters
- **collection_name** (str) - Required - The name of the collection to search within.
- **query** (str) - Required - The search query.
- **top_k** (int) - Required - The number of top results to return.

### Request Example
```python
from src.data_processing.indexer import Indexer, index_all_data

# Index all data sources (run once or with --rebuild)
# index_all_data(rebuild=True)

# Manual indexing workflow
indexer = Indexer(
    qdrant_host="localhost",
    qdrant_port=6333,
    embedding_model="BAAI/bge-m3"
)

# Create collection
indexer.create_collection("c3_plugins", recreate=True)

# Prepare documents
documents = [
    {
        "text": "The Sprite object is used for animated graphics...",
        "metadata": {
            "source": "plugin-reference/sprite.md",
            "h1_heading": "Sprite",
            "h2_heading": "Overview",
            "collection": "c3_plugins"
        }
    }
]

# Index with automatic embedding and batching
indexer.index_documents("c3_plugins", documents, batch_size=100)

# Search indexed collection
results = indexer.search("c3_plugins", "sprite animation", top_k=5)
for result in results:
    print(f"{result['score']}: {result['text'][:50]}...")
```

### Response
#### Success Response (Various formats depending on method)
- `create_collection`: Returns a boolean indicating success or failure.
- `index_documents`: Returns a response from the Qdrant client, typically indicating the number of points indexed.
- `search`: Returns a list of dictionaries, each containing:
    - **score** (float) - The relevance score of the result.
    - **text** (str) - The content of the indexed document chunk.

#### Response Example (for `search`)
```json
[
  {
    "score": 0.92,
    "text": "The Sprite object is a fundamental element in Construct 3 for displaying and animating graphics..."
  },
  {
    "score": 0.85,
    "text": "Animations for sprites can be created by defining a sequence of frames and setting the animation speed..."
  }
]
```
```

--------------------------------

### Collection Definitions and Mapping (Python)

Source: https://context7.com/xhxiaiein/construct3-rag/llms.txt

This Python code snippet illustrates how to access and utilize collection definitions for organizing data in the vector database. It shows how to get collection names, map directories to collections, and retrieve category information for plugins and behaviors.

```Python
from src.collections import (
    COLLECTIONS, DOC_COLLECTIONS, ALL_COLLECTIONS,
    DIR_TO_COLLECTION, SUBCATEGORY_MAPPING,
    PLUGIN_CATEGORIES, BEHAVIOR_CATEGORIES
)

# Access collection names
print(COLLECTIONS["plugins"])  # "c3_plugins"
print(COLLECTIONS["behaviors"])  # "c3_behaviors"

# Document collections only (excludes examples/terms/ace)
print(DOC_COLLECTIONS)  # ['c3_guide', 'c3_interface', ...]

# Map directory to collection
collection = DIR_TO_COLLECTION["plugin-reference"]  # "c3_plugins"

# Get plugin category
for category, plugins in PLUGIN_CATEGORIES.items():
    if "sprite" in plugins:
        print(f"Sprite is in category: {category}")

# Detect subcategory from path
subcategory = SUBCATEGORY_MAPPING["plugin-reference"]["sprite"]  # "general"
```

--------------------------------

### Parse ACE Schemas and Get Statistics (Python)

Source: https://context7.com/xhxiaiein/construct3-rag/llms.txt

This Python code snippet demonstrates how to use the SchemaParser to parse ACE (Actions/Conditions/Expressions) entries and effects from Construct 3 plugin definitions. It also shows how to retrieve statistics about the parsed data and export it for a vector database.

```Python
from src.data_processing.schema_parser import SchemaParser

# Initialize parser (reads from data/schemas/)
parser = SchemaParser()

# Parse all ACE entries
ace_entries = parser.parse_ace_entries()
for entry in ace_entries[:3]:
    print(f"{entry.plugin_name_zh} ({entry.plugin_name})")
    print(f"  {entry.ace_type}: {entry.name_zh} ({entry.name_en})")
    print(f"  Description: {entry.description_zh}")
    print(f"  Params: {len(entry.params)}")

# Parse effects
effects = parser.parse_effects()
print(f"Found {len(effects)} effects")

# Get statistics
stats = parser.get_stats()
print(f"Total ACEs: {stats['total_aces']}")
print(f"  Conditions: {stats['by_type']['condition']}")
print(f"  Actions: {stats['by_type']['action']}")
print(f"  Expressions: {stats['by_type']['expression']}")
print(f"Plugins: {stats['plugins']}, Behaviors: {stats['behaviors']}")

# Export for vector database
docs = parser.export_ace_for_vectordb(ace_entries)
print(f"Generated {len(docs)} vector documents")
print(docs[0]['text'])  # Bilingual ACE description with parameters
```

--------------------------------

### Data Indexing System in Python

Source: https://context7.com/xhxiaiein/construct3-rag/llms.txt

Indexes Construct 3 data sources into a Qdrant vector database. It supports indexing all data at once or manually creating collections and indexing documents in batches.

```python
from src.data_processing.indexer import Indexer, index_all_data

# Index all data sources (run once or with --rebuild)
index_all_data(rebuild=True)

# Manual indexing workflow
indexer = Indexer(
    qdrant_host="localhost",
    qdrant_port=6333,
    embedding_model="BAAI/bge-m3"
)

# Create collectionindexer.create_collection("c3_plugins", recreate=True)

# Prepare documents
documents = [
    {
        "text": "The Sprite object is used for animated graphics...",
        "metadata": {
            "source": "plugin-reference/sprite.md",
            "h1_heading": "Sprite",
            "h2_heading": "Overview",
            "collection": "c3_plugins"
        }
    }
]

# Index with automatic embedding and batching
indexer.index_documents("c3_plugins", documents, batch_size=100)

# Search indexed collection
results = indexer.search("c3_plugins", "sprite animation", top_k=5)
for result in results:
    print(f"{result['score']}: {result['text'][:50]}...")
```

--------------------------------

### Configure External Repository Path with Python

Source: https://github.com/xhxiaiein/construct3-rag/blob/main/doc/knowledge/manual.md

This Python snippet configures the path for an external repository. It sets the `MANUAL_REPO` variable to 'Construct3-Manual', indicating the location of game engine documentation. This is crucial for integrating external resources into the RAG system.

```python
# https://github.com/XHXIAIEIN/Construct3-Manual
MANUAL_REPO = "Construct3-Manual"
```

--------------------------------

### Configuration Management and Environment Variable Overrides (Python)

Source: https://context7.com/xhxiaiein/construct3-rag/llms.txt

This Python code demonstrates how to access central configuration settings for the RAG system, including service endpoints, model details, and path configurations. It also shows how to override these settings using environment variables.

```Python
from src.config import (
    QDRANT_HOST, QDRANT_PORT,
    EMBEDDING_MODEL, EMBEDDING_DIMENSION,
    LLM_MODEL, LLM_BASE_URL,
    BASE_DIR, DATA_DIR, SCHEMA_DIR,
    MAX_CHUNK_SIZE, TOP_K
)
import os

# Service configuration
print(f"Qdrant: {QDRANT_HOST}:{QDRANT_PORT}")
print(f"LLM: {LLM_MODEL} at {LLM_BASE_URL}")
print(f"Embedding: {EMBEDDING_MODEL} ({EMBEDDING_DIMENSION} dims)")

# Path configuration
print(f"Base directory: {BASE_DIR}")
print(f"Schema directory: {SCHEMA_DIR}")

# RAG parameters
print(f"Max chunk size: {MAX_CHUNK_SIZE}")
print(f"Top K results: {TOP_K}")

# Override with environment variables
os.environ["LLM_MODEL"] = "qwen2.5:14b"
os.environ["QDRANT_HOST"] = "192.168.1.100"
```

--------------------------------

### RAG Query Answering in Python

Source: https://context7.com/xhxiaiein/construct3-rag/llms.txt

Answers questions about Construct 3 using a RAG chain. It supports streaming responses with source citations and provides response metadata including query type and confidence.

```python
from src.rag.chain import RAGChain

# Initialize RAG chain with local services
rag = RAGChain(
    qdrant_host="localhost",
    qdrant_port=6333,
    llm_model="qwen2.5:7b",
    llm_base_url="http://localhost:11434",
    enable_query_rewrite=True
)

# Ask a question and get structured response
response = rag.answer("How do I detect keyboard input in Construct 3?")
print(response.answer)
print(f"Found {len(response.sources)} sources")

# Stream response for real-time output
for chunk in rag.answer_stream("Explain the Sprite object"):
    print(chunk, end="", flush=True)

# Result includes:
# - answer: Generated text with [来源: N] citations
# - sources: List of retrieved documents with scores
# - query_type: "qa", "code", "qa_low_relevance", or "qa_no_results"
```

--------------------------------

### Markdown Documentation Parser API

Source: https://context7.com/xhxiaiein/construct3-rag/llms.txt

This API allows parsing Construct 3 markdown documentation files. It supports parsing individual files or entire directories, with specific capabilities for H2-level semantic chunking and filtering by collection.

```APIDOC
## Markdown Documentation Parser

### Description
Parse Construct 3 markdown documentation with H2-level semantic chunking. Supports parsing single files, entire directories, and filtering by collection.

### Method
`MarkdownParser` class methods

### Endpoint
N/A (Python library)

### Parameters
#### Initialization Parameters
- **manual_dir** (str) - Optional - Path to the Construct3-Manual directory. If not provided, it attempts to auto-detect.

#### `parse_file` method parameters
- **file_path** (str) - Required - The path to the markdown file to parse.

#### `parse_directory` method parameters
- None

#### `parse_by_collection` method parameters
- **collection_name** (str) - Required - The name of the collection to filter chunks by.

### Request Example
```python
from src.data_processing.markdown_parser import MarkdownParser

# Initialize parser (auto-detects Construct3-Manual directory)
parser = MarkdownParser()

# Parse single file
chunks = parser.parse_file("../Construct3-Manual/plugin-reference/sprite.md")
for chunk in chunks:
    print(f"H1: {chunk.metadata['h1_heading']}")
    print(f"H2: {chunk.metadata['h2_heading']}")
    print(f"Collection: {chunk.metadata['collection']}")
    print(f"Section type: {chunk.metadata['section_type']}")
    print(f"Text: {chunk.text[:100]}...\n")

# Parse entire documentation tree
all_chunks = parser.parse_directory()
print(f"Total chunks: {len(all_chunks)}")

# Parse by specific collection
plugin_chunks = parser.parse_by_collection("c3_plugins")
print(f"Plugin chunks: {len(plugin_chunks)}")
```

### Response
#### Success Response (List of chunk objects)
- Each chunk object has:
    - **text** (str) - The parsed content of the chunk.
    - **metadata** (dict) - Metadata associated with the chunk, including:
        - **h1_heading** (str) - The main H1 heading of the section.
        - **h2_heading** (str) - The H2 heading of the section.
        - **collection** (str) - The collection the chunk belongs to.
        - **source** (str) - The source file path.
        - **section_type** (str) - The type of section (e.g., 'overview', 'properties').

#### Response Example
```json
[
  {
    "text": "The Sprite object is used for displaying and animating 2D graphics in your game. It is the fundamental object for visual elements...",
    "metadata": {
      "h1_heading": "Sprite",
      "h2_heading": "Overview",
      "collection": "plugins",
      "source": "plugin-reference/sprite.md",
      "section_type": "overview"
    }
  },
  {
    "text": "Properties of the Sprite object include: 'Width', 'Height', 'X', 'Y', 'Angle', etc. These properties can be accessed and modified via events and actions...",
    "metadata": {
      "h1_heading": "Sprite",
      "h2_heading": "Properties",
      "collection": "plugins",
      "source": "plugin-reference/sprite.md",
      "section_type": "properties"
    }
  }
]
```
```

--------------------------------

### Markdown Documentation Parser in Python

Source: https://context7.com/xhxiaiein/construct3-rag/llms.txt

Parses Construct 3 markdown documentation with H2-level semantic chunking. It can parse single files, entire directory trees, or filter by specific collections.

```python
from src.data_processing.markdown_parser import MarkdownParser

# Initialize parser (auto-detects Construct3-Manual directory)
parser = MarkdownParser()

# Parse single file
chunks = parser.parse_file("../Construct3-Manual/plugin-reference/sprite.md")
for chunk in chunks:
    print(f"H1: {chunk.metadata['h1_heading']}")
    print(f"H2: {chunk.metadata['h2_heading']}")
    print(f"Collection: {chunk.metadata['collection']}")
    print(f"Section type: {chunk.metadata['section_type']}")
    print(f"Text: {chunk.text[:100]}...\n")

# Parse entire documentation tree
all_chunks = parser.parse_directory()
print(f"Total chunks: {len(all_chunks)}")

# Parse by specific collection
plugin_chunks = parser.parse_by_collection("c3_plugins")

```

--------------------------------

### RAG Query Answering API

Source: https://context7.com/xhxiaiein/construct3-rag/llms.txt

This API allows you to ask questions about Construct 3 and receive accurate, citation-backed answers. It supports both direct answers and streaming responses, along with structured results detailing the answer, sources, and query type.

```APIDOC
## RAG Query Answering

### Description
Answer questions about Construct 3 with automatic source attribution and confidence-aware responses. Supports direct answers, streaming, and detailed results.

### Method
`RAGChain` class methods

### Endpoint
N/A (Python library)

### Parameters
#### Initialization Parameters
- **qdrant_host** (str) - Required - Hostname for the Qdrant vector database.
- **qdrant_port** (int) - Required - Port for the Qdrant vector database.
- **llm_model** (str) - Required - Name of the local LLM model to use (e.g., "qwen2.5:7b").
- **llm_base_url** (str) - Required - Base URL for the local LLM service (e.g., "http://localhost:11434").
- **enable_query_rewrite** (bool) - Optional - Whether to enable automatic query rewriting for better search results.

#### `answer` method parameters
- **question** (str) - Required - The question to ask about Construct 3.

#### `answer_stream` method parameters
- **question** (str) - Required - The question to ask about Construct 3.

### Request Example
```python
from src.rag.chain import RAGChain

rag = RAGChain(
    qdrant_host="localhost",
    qdrant_port=6333,
    llm_model="qwen2.5:7b",
    llm_base_url="http://localhost:11434",
    enable_query_rewrite=True
)

response = rag.answer("How do I detect keyboard input in Construct 3?")
print(response.answer)
print(f"Found {len(response.sources)} sources")

for chunk in rag.answer_stream("Explain the Sprite object"):
    print(chunk, end="", flush=True)
```

### Response
#### Success Response (Object with attributes)
- **answer** (str) - The generated answer with `[来源: N]` citations.
- **sources** (list) - A list of retrieved documents, including their scores.
- **query_type** (str) - The type of query executed (e.g., "qa", "code", "qa_low_relevance", "qa_no_results").

#### Response Example
```json
{
  "answer": "To detect keyboard input in Construct 3, you can use the 'On key pressed' event. This event triggers whenever a specified key is pressed on the keyboard. You can access details about the pressed key within the event's actions. [来源: 1]",
  "sources": [
    {
      "score": 0.95,
      "source": "Construct3-Manual/input/keyboard.md",
      "text": "The 'On key pressed' event is a fundamental event for handling keyboard input...",
      "metadata": { ... }
    }
  ],
  "query_type": "qa"
}
```
```

--------------------------------

### Hybrid Retriever Search in Python

Source: https://context7.com/xhxiaiein/construct3-rag/llms.txt

Performs semantic vector searches across multiple specialized collections in Qdrant. It allows searching specific collections or all collections and formatting results for LLM context.

```python
from src.rag.retriever import HybridRetriever

# Initialize retriever
retriever = HybridRetriever(
    qdrant_host="localhost",
    qdrant_port=6333,
    embedding_model_name="BAAI/bge-m3"
)

# Search specific collection
results = retriever.search_plugins("audio playback", top_k=5)
for result in results:
    print(f"Score: {result.score:.2f}")
    print(f"Source: {result.source}")
    print(f"Text: {result.text[:100]}...")
    print(f"Metadata: {result.metadata}")

# Search all collections
all_results = retriever.search_all("how to create animations", top_k_per_collection=3)
for collection, items in all_results.items():
    print(f"\n{collection}: {len(items)} results")

# Format results as LLM context
context = retriever.format_context(all_results)
print(context)  # Formatted with breadcrumbs and source citations
```

--------------------------------

### Hybrid Retriever Search API

Source: https://context7.com/xhxiaiein/construct3-rag/llms.txt

This API enables semantic search across multiple specialized collections within the Construct 3 knowledge base. It supports searching specific collections or all collections and can format the retrieved context for LLM consumption.

```APIDOC
## Hybrid Retriever Search

### Description
Search across multiple specialized collections with semantic vector search. Supports searching specific collections, all collections, and formatting results for LLM context.

### Method
`HybridRetriever` class methods

### Endpoint
N/A (Python library)

### Parameters
#### Initialization Parameters
- **qdrant_host** (str) - Required - Hostname for the Qdrant vector database.
- **qdrant_port** (int) - Required - Port for the Qdrant vector database.
- **embedding_model_name** (str) - Required - The name of the embedding model to use (e.g., "BAAI/bge-m3").

#### `search_plugins` method parameters
- **query** (str) - Required - The search query.
- **top_k** (int) - Optional - The number of top results to return.

#### `search_all` method parameters
- **query** (str) - Required - The search query.
- **top_k_per_collection** (int) - Optional - The number of top results to retrieve from each collection.

#### `format_context` method parameters
- **results** (dict) - Required - The results object returned by `search_all`.

### Request Example
```python
from src.rag.retriever import HybridRetriever

retriever = HybridRetriever(
    qdrant_host="localhost",
    qdrant_port=6333,
    embedding_model_name="BAAI/bge-m3"
)

# Search specific collection
results = retriever.search_plugins("audio playback", top_k=5)
for result in results:
    print(f"Score: {result.score:.2f}")
    print(f"Source: {result.source}")
    print(f"Text: {result.text[:100]}...")
    print(f"Metadata: {result.metadata}")

# Search all collections
all_results = retriever.search_all("how to create animations", top_k_per_collection=3)
for collection, items in all_results.items():
    print(f"\n{collection}: {len(items)} results")

# Format results as LLM context
context = retriever.format_context(all_results)
print(context)
```

### Response
#### Success Response (Various formats depending on method)
- `search_plugins` and `search_all` return a list of result objects, each with:
    - **score** (float) - The relevance score of the result.
    - **source** (str) - The source file or identifier of the document.
    - **text** (str) - The content of the retrieved document chunk.
    - **metadata** (dict) - Associated metadata for the document chunk.
- `format_context` returns a formatted string suitable for LLM input.

#### Response Example (for `search_plugins`)
```json
[
  {
    "score": 0.88,
    "source": "plugin-reference/audio.md",
    "text": "The Audio object allows you to play and manage sound effects and music in your Construct 3 project...",
    "metadata": {
      "h1_heading": "Audio",
      "h2_heading": "Overview",
      "collection": "plugins"
    }
  }
]
```
```
Tokens:
Raw