slm-graph 0.1.2

Self-contained natural language to Mermaid graph generator using SLMs.

SLM-Graph

SLM-Graph is a lightweight, production-grade Python library that transforms natural language descriptions into professional Mermaid.js diagrams. By embedding llama-cpp-python and using the Instructor pattern, it provides a reliable, self-contained way to generate structured graphs without external API dependencies or local server installations like Ollama.

Key Features

• Self-Contained Inference: Uses llama-cpp-python directly in your Python process.

• Strict Schema Validation: Leverages Pydantic and Instructor to prevent AI hallucinations and ensure valid Mermaid syntax.

• Multi-Format Export: Generates SVG, PNG, and PDF exports in parallel.

• Professional Aesthetics: Automatically maps SLM output to optimized Mermaid flowchart layouts.

Installation

1. System Rendering Dependency

   You must have the Mermaid CLI installed for image and PDF generation:

   npm install -g @mermaid-js/mermaid-cli
   

2. Python Library

User Warning (Windows Users): Installing llama-cpp-python often triggers a long C++ compilation process that can take 10-20 minutes or fail if build tools are missing. To skip this and ensure a smooth installation, use the pre-compiled binaries:

• For windows:

  pip install llama-cpp-python --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cpu
  pip install slm-graph
  

• For Linux/Mac:

  pip install slm-graph
  

3. Model Weight

   To use the library, you need to download a Small Language Model in GGUF format.

   Recommended Model:

   • Llama-3.2-3B-Instruct-GGUF

Setup Instructions:

1. Create a folder named models in your project root directory.

2. Download the .gguf file (e.g., Llama-3.2-1B-Instruct-Q4_K_M.gguf) from the links above.

3. Paste the file into the models/ folder.

Quick Start

from slm_graph import EasyGraph
import asyncio

async def main():
    # Initialize with the path to your downloaded GGUF model
    eg = EasyGraph(model_path="models/Llama-3.2-1B-Instruct-Q4_K_M.gguf")

    # Generate graph files from a prompt
    await eg.generate(
        prompt="A customer places an order. If payment is successful, the warehouse ships it. If it fails, the order is cancelled.",
        output_name="order_process",
        formats=["svg", "png", "pdf"]
    )

if __name__ == "__main__":
    asyncio.run(main())

Disclaimers & Limitations

• First-Time Install Delay: As mentioned, the first installation of llama-cpp-python may hang at "Building Wheel." This is expected behavior as it compiles C++ code for your specific CPU.

• Inference Speed: Generation speed depends on your CPU/GPU. A 3B model typically takes 5-15 seconds to "think" before rendering begins.

• Model Accuracy: While 3B models are highly accurate, they may occasionally hallucinate. We use Pydantic aliases (name -> label, from -> source) to automatically correct common SLM naming mistakes.

Project Architecture

• core.py: Orchestrates local inference and Instructor patching.

• schema.py: Defines the data contract for nodes, edges, and graph types.

• renderer.py: Compiles Pydantic objects to Mermaid and handles CLI subprocesses.

License

Distributed under the MIT License.