feat: add mkdocs

.github/workflows/gh-pages.yml

@@ -0,0 +1,34 @@
+name: Deploy documentation to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install poetry
+          poetry install --no-root
+
+      - name: Build documentation
+        run: |
+          poetry run mkdocs build
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site

README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="docs/assets/brickllm_logo2.png" alt="BrickLLM" style="width: 100%;">
+  <img src="docs/assets/brickllm_banner.png" alt="BrickLLM" style="width: 100%;">
 </p>
 
 # 🧱 BrickLLM

brickllm/graphs/brickschema_graph.py

@@ -98,8 +98,11 @@ def run(self, prompt, stream=False):
         """Run the graph with the given user prompt.
 
         Args:
-            user_prompt (str): The user-provided natural language prompt.
-            stream (bool): Whether to stream the execution (True) or run without streaming (False).
+            prompt (str): The user prompt to run the graph.
+            stream (bool): Stream the graph execution.
+
+        Returns:
+            result (dict): The result of the graph execution.
         """
         input_data = {"user_prompt": prompt}
 

docs/index.md

@@ -0,0 +1,8 @@
+# Welcome to BrickLLM
+
+BrickLLM is a Python library designed to generate RDF files that comply with the BrickSchema ontology using Large Language Models (LLMs).
+
+- [Overview](overview.md)
+- [Installation](installation.md)
+- [Usage](usage.md)
+- [API Reference](reference/brickllm.md)

docs/installation.md

@@ -0,0 +1,19 @@
+# Installation
+
+BrickLLM can be installed using [pip](https://pypi.org/project/brickllm/).
+
+```bash
+pip install brickllm
+```
+
+Alternatively, using [Poetry](https://python-poetry.org/), which handles dependency management.
+
+```bash
+# Clone the repository
+git clone https://github.com/EURAC-EEBgroup/brickllm-lib.git
+cd brickllm-lib
+
+# Install dependencies
+poetry install
+```
+

docs/modules/brickllm.md

@@ -0,0 +1,37 @@
+# BrickLLM Module
+
+The `brickllm` package is the main package containing all modules and components related to generating BrickSchema-compliant RDF files using LLMs.
+
+## Contents
+
+### Edges
+- [validate_condition.py](../reference/edges/validate_condition.md)
+
+### Graphs
+- [brickschema_graph.py](../reference/graphs/brickschema_graph.md)
+
+### Helpers
+- [llm_models.py](../reference/helpers/llm_models.md)
+- [prompts.py](../reference/helpers/prompts.md)
+
+### Nodes
+- [get_elem_children.py](../reference/nodes/get_elem_children.md)
+- [get_elements.py](../reference/nodes/get_elements.md)
+- [get_relationships.py](../reference/nodes/get_relationships.md)
+- [get_sensors.py](../reference/nodes/get_sensors.md)
+- [schema_to_ttl.py](../reference/nodes/schema_to_ttl.md)
+- [validate_schema.py](../reference/nodes/validate_schema.md)
+
+### Ontologies
+- [brick_hierarchy.json](../reference/ontologies/brick_hierarchy.md)
+- [Brick.ttl](../reference/ontologies/Brick.md)
+
+### Utils
+- [get_hierarchy_info.py](../reference/utils/get_hierarchy_info.md)
+- [query_brickschema.py](../reference/utils/query_brickschema.md)
+
+### Root-Level Files
+- [compiled_graphs.py](../reference/compiled_graphs.md)
+- [configs.py](../reference/configs.md)
+- [schemas.py](../reference/schemas.md)
+- [states.py](../reference/states.md)

docs/modules/edges.md

@@ -0,0 +1,8 @@
+
+# Edges Module
+
+The `edges` module contains components related to the validation of relationships (edges) between entities in the graph.
+
+## Contents
+
+- [validate_condition.py](../reference/edges/validate_condition.md)

docs/modules/graphs.md

@@ -0,0 +1,8 @@
+
+# Graphs Module
+
+The `graphs` module contains components that manage and execute the BrickSchema graph operations.
+
+## Contents
+
+- [brickschema_graph.py](../reference/graphs/brickschema_graph.md)

docs/modules/helpers.md

@@ -0,0 +1,9 @@
+
+# Helpers Module
+
+The `helpers` module contains utility functions and prompts that assist in LLM interactions and data processing.
+
+## Contents
+
+- [llm_models.py](../reference/helpers/llm_models.md)
+- [prompts.py](../reference/helpers/prompts.md)

docs/modules/nodes.md

@@ -0,0 +1,13 @@
+
+# Nodes Module
+
+The `nodes` module contains specialized components that perform tasks such as element identification, hierarchy construction, and RDF conversion.
+
+## Contents
+
+- [get_elem_children.py](../reference/nodes/get_elem_children.md)
+- [get_elements.py](../reference/nodes/get_elements.md)
+- [get_relationships.py](../reference/nodes/get_relationships.md)
+- [get_sensors.py](../reference/nodes/get_sensors.md)
+- [schema_to_ttl.py](../reference/nodes/schema_to_ttl.md)
+- [validate_schema.py](../reference/nodes/validate_schema.md)

docs/modules/ontologies.md

@@ -0,0 +1,9 @@
+
+# Ontologies Module
+
+The `ontologies` module contains the BrickSchema and hierarchy files used for representing and managing the building systems.
+
+## Contents
+
+- [brick_hierarchy.json](../reference/ontologies/brick_hierarchy.md)
+- [Brick.ttl](../reference/ontologies/Brick.md)

docs/modules/utils.md

@@ -0,0 +1,9 @@
+
+# Utils Module
+
+The `utils` module contains components related to querying and retrieving data from the BrickSchema.
+
+## Contents
+
+- [get_hierarchy_info.py](../reference/utils/get_hierarchy_info.md)
+- [query_brickschema.py](../reference/utils/query_brickschema.md)

docs/overview.md

@@ -0,0 +1,25 @@
+# Overview
+
+BrickLLM is a Python library designed to generate RDF (Resource Description Framework) files that comply with the BrickSchema ontology using Large Language Models (LLMs). The library leverages advanced natural language processing capabilities to interpret building descriptions and convert them into structured, machine-readable formats suitable for building automation and energy management systems.
+
+## Main Features
+
+- **Multi-provider LLM Support**: Supports multiple LLM providers, including OpenAI, Anthropic, and Fireworks AI.
+- **Natural Language to RDF Conversion**: Converts natural language descriptions of buildings and facilities into BrickSchema-compliant RDF.
+- **Customizable Graph Execution**: Utilizes LangGraph for flexible and customizable graph-based execution of the conversion process.
+- **Ontology Integration**: Incorporates the BrickSchema ontology for accurate and standardized representation of building systems.
+- **Extensible Architecture**: Designed with modularity in mind, allowing for easy extension and customization.
+
+## How It Works
+
+1. **User Input**: The process begins with a natural language description of a building or facility provided by the user.
+
+2. **LLM Processing**: The description is processed by a selected LLM to extract relevant building components and their relationships.
+
+3. **Graph Execution**: The extracted information is passed through a series of nodes in a graph structure:
+   - **Element Identification**: Identifies building elements from the user prompt.
+   - **Hierarchy Construction**: Builds a hierarchical structure of the identified elements.
+   - **Relationship Mapping**: Determines relationships between the components.
+   - **TTL Generation**: Converts the structured data into Turtle (TTL) format, which is a serialization of RDF.
+
+4. **Output Generation**: The final output is a BrickSchema-compliant RDF file in TTL format, representing the building's structure and systems.

docs/reference/brickllm.md

@@ -0,0 +1,32 @@
+# BrickLLM API Reference
+
+Welcome to the API Reference for the `BrickLLM` library. This section of the documentation provides detailed information about the modules, classes, functions, and other components that make up the BrickLLM library.
+
+## Overview
+
+`BrickLLM` is a Python library designed to generate BrickSchema-compliant RDF files using Large Language Models (LLMs). It provides various utilities for parsing natural language building descriptions, extracting relevant components, and constructing a structured graph that represents the building and its systems.
+
+This API reference covers all the essential modules and functions available in the library, including components for:
+
+- **Element identification**
+- **Relationship mapping**
+- **TTL generation** (Turtle format RDF)
+- **Ontology integration** (BrickSchema)
+
+## Key Modules
+
+- **Edges**: Validation of relationships (edges) between entities in the graph.
+- **Graphs**: Handles the orchestration of graph-based operations with the BrickSchema.
+- **Helpers**: Contains utility functions and predefined LLM prompts to aid in the generation process.
+- **Nodes**: Specialized nodes that handle various tasks such as extracting elements, constructing hierarchies, and generating RDF files.
+- **Ontologies**: Includes the BrickSchema ontology and hierarchical data.
+- **Utils**: Utility functions for querying the BrickSchema and handling RDF data.
+
+## How to Use the API Reference
+
+- Navigate to individual modules and components via the side navigation or by clicking on the links in the module overview sections.
+- Each module contains a breakdown of its functions, classes, and attributes, with descriptions and examples where applicable.
+
+For an in-depth guide on how to use the library in practice, see the [Usage](../usage.md) section.
+
+Happy coding!

docs/reference/compiled_graphs.md

@@ -0,0 +1,4 @@
+
+# compiled_graphs.py
+
+::: brickllm.compiled_graphs

docs/reference/configs.md

@@ -0,0 +1,4 @@
+
+# configs.py
+
+::: brickllm.configs

docs/reference/edges/validate_condition.md

@@ -0,0 +1,4 @@
+
+# validate_condition.py
+
+::: brickllm.edges.validate_condition

docs/reference/graphs/brickschema_graph.md

@@ -0,0 +1,4 @@
+
+# brickschema_graph.py
+
+::: brickllm.graphs.brickschema_graph

docs/reference/helpers/llm_models.md

@@ -0,0 +1,4 @@
+
+# llm_models.py
+
+::: brickllm.helpers.llm_models

docs/reference/helpers/prompts.md

@@ -0,0 +1,4 @@
+
+# prompts.py
+
+::: brickllm.helpers.prompts

docs/reference/nodes/get_elem_children.md

@@ -0,0 +1,4 @@
+
+# get_elem_children.py
+
+::: brickllm.nodes.get_elem_children

docs/reference/nodes/get_elements.md

@@ -0,0 +1,4 @@
+
+# get_elements.py
+
+::: brickllm.nodes.get_elements

docs/reference/nodes/get_relationships.md

@@ -0,0 +1,4 @@
+
+# get_relationships.py
+
+::: brickllm.nodes.get_relationships

docs/reference/nodes/get_sensors.md

@@ -0,0 +1,4 @@
+
+# get_sensors.py
+
+::: brickllm.nodes.get_sensors

docs/reference/nodes/schema_to_ttl.md

@@ -0,0 +1,4 @@
+
+# schema_to_ttl.py
+
+::: brickllm.nodes.schema_to_ttl

docs/reference/nodes/validate_schema.md

@@ -0,0 +1,4 @@
+
+# validate_schema.py
+
+::: brickllm.nodes.validate_schema

docs/reference/ontologies/Brick.md

@@ -0,0 +1,4 @@
+
+# Brick.ttl
+
+This file contains the BrickSchema ontology in Turtle (TTL) format.

docs/reference/ontologies/brick_hierarchy.md

@@ -0,0 +1,4 @@
+
+# brick_hierarchy.json
+
+This file contains the hierarchical structure of the BrickSchema entities in JSON format.

docs/reference/schemas.md

@@ -0,0 +1,4 @@
+
+# schemas.py
+
+::: brickllm.schemas

docs/reference/states.md

@@ -0,0 +1,4 @@
+
+# states.py
+
+::: brickllm.states

docs/reference/utils/get_hierarchy_info.md

@@ -0,0 +1,4 @@
+
+# get_hierarchy_info.py
+
+::: brickllm.utils.get_hierarchy_info

docs/reference/utils/query_brickschema.md

@@ -0,0 +1,4 @@
+
+# query_brickschema.py
+
+::: brickllm.utils.query_brickschema

docs/usage.md

@@ -0,0 +1 @@
+# Usage