orchestrata_ultimate.core.graph_directives

Reference › orchestrata_ultimate › core › graph_directives

A 40-line helper in the core package that lets a volk pass knowledge-graph context to its language-model call. extract_graph_context reads the graph_context entry that the context injector places in a CXP packet payload and returns it as a string, or None when the entry is absent or empty. The volk hands the result to call_llm(graph_context=...), and the LLM client prepends it to the user message, so the graph data is part of the prompt tokens. The module also keeps GRAPH_CONTEXT_DIRECTIVE, an empty string retained so that volks which still import it keep working.

At a glance

Class diagram

No classes; see Functions.

Dependency diagram

API

Constants

Functions

Source

Permalink: https://gitlab.com/MSamy/orchestrata-ultimate-architecture/-/blob/a4cbc2bdf/src/orchestrata_ultimate/core/graph_directives.py

"""Knowledge graph context extraction for LLM injection.

Every volk extracts graph_context from the CXP payload and passes it
to call_llm(graph_context=...). The LLM client prepends it to the user
message so the LLM processes it as part of the prompt tokens — the LLM
has no choice, the data is in its input.

Usage in volk process()::

    from orchestrata_ultimate.core.graph_directives import extract_graph_context

    async def process(self, packet):
        gc = extract_graph_context(packet.payload)
        ...
        response = await call_llm(SYSTEM_PROMPT, prompt, graph_context=gc)
"""

from typing import Any


def extract_graph_context(payload: dict[str, Any]) -> str | None:
    """Extract graph_context from a CXP packet payload.

    The ContextInjector puts pre-formatted graph data into
    payload["graph_context"]. This function extracts it for
    passing to call_llm(graph_context=...).

    Args:
        payload: CXP packet payload dict.

    Returns:
        The graph context string, or None if not present/empty.
    """
    gc = payload.get("graph_context", "")
    return gc if gc else None


# Kept for backward compatibility with volks that already import this.
# New code uses extract_graph_context() + call_llm(graph_context=...).
GRAPH_CONTEXT_DIRECTIVE: str = ""