slm-graph 0.1.2
Self-contained natural language to Mermaid graph generator using SLMs.
License: MIT
Requires Python: <4.0,>=3.9
Keywords: mermaid, llm, slm, graph, visualization, instructor

# 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:**

    ``` bash
    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:
    ``` bash
    pip install llama-cpp-python --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cpu
    pip install slm-graph
    ```
* For Linux/Mac:
    ``` bash
    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](https://huggingface.co/hugging-quants/Llama-3.2-3B-Instruct-Q4_K_M-GGUF/resolve/main/llama-3.2-3b-instruct-q4_k_m.gguf?download=true)

## 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
``` python
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.