Prompt-based Knowledge Graph Construction API

Small Flask API that accepts text, combines it with prompt templates, asks Ollama to generate RDF/Turtle, validates the result with rdflib, and returns the generated RDF. The project ships with a system prompt and a few-shot prompt for knowledge-graph construction.

Process Flow

Project Layout

• src/kg_construction/ - installable Python package using the standard src layout, with controller, application, domain, and infrastructure layers.
• prompt/system/ - System prompts that define LLM behavior and output constraints.
• prompt/prompts/ - User prompt templates. The default template includes the ${USER_TEXT} placeholder.
• docs/ - Endpoint, run, test, and sequence documentation.
• tests/ - Unit and integration tests.

Sequence Diagram

API Summary

GET /health

Returns service status and Ollama/model availability.

POST /analyze

Receives text and returns valid RDF/Turtle generated by the configured Ollama model.

Request body:

{
  "text": "Alice knows Bob.",
  "prompt_name": "prompts/few-shot.txt",
  "system_prompt_name": "system/knowledge_graph.txt",
  "max_rdf_attempts": 3
}

Only text is required. Prompt names are resolved inside the prompt/ directory. max_rdf_attempts is capped at 3 and controls how many times the service asks the model to repair invalid Turtle before returning an error.

Success response:

{
  "text": "Alice knows Bob.",
  "rdf": "@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .\n..."
}

See docs/analyze.md for the full endpoint contract.

See docs/prompt.md for an explanation of the system prompt, few-shot prompt, placeholders, prefixes, and prompt editing guidelines.

Development quality checks

Install the development dependencies with python -m pip install -r requirements-dev.txt, then run python -m ruff format --check ., python -m ruff check ., python -m pyright, and python -m pytest. GitHub Actions runs the same checks on pushes and pull requests with Python 3.10 and 3.13.

LLM Configuration

Variable	Description	Type	Default/Example Value
DEFAULT_PROMPT_NAME	Path to the few-shot prompt	String	prompts/few-shot.txt
DEFAULT_SYSTEM_PROMPT_NAME	Path to the system prompt	String	system/knowledge_graph.txt
OLLAMA_API_URL	Ollama API URL	String	http://localhost:11434
OLLAMA_MODEL	LLM model name	String	llama3:8b
OLLAMA_CSV_PATH	Path to the response log CSV file	String	data/ollama_responses.csv
OLLAMA_SEED	Seed for reproducibility	Integer (optional)	-
OLLAMA_TEMPERATURE	Sampling temperature	Float (optional)	-
OLLAMA_TOP_K	Top-K sampling	Integer (optional)	-
OLLAMA_TOP_P	Top-P (nucleus sampling)	Float (optional)	-
OLLAMA_MIN_P	Minimum probability threshold	Float (optional)	-
OLLAMA_STOP	Stop sequence	String (optional)	-
OLLAMA_NUM_CTX	Context window size	Integer (optional)	-
OLLAMA_NUM_PREDICT	Maximum number of tokens to generate	Integer (optional)	-
OLLAMA_TIMEOUT_SECONDS	HTTP timeout for Ollama requests	Integer	180

Generated Output and Logs

• The model is called through Ollama /api/generate with stream:false.
• Generated text is trimmed to the RDF/Turtle portion, repaired when possible, and parsed with rdflib.Graph.parse(format="turtle").
• Successful generations are written to the CSV configured by OLLAMA_CSV_PATH.
• The public API returns only the original text and the validated rdf string.