orchestrata_ultimate.context.providers.semantic_context

Reference › orchestrata_ultimate › context › providers › semantic_context

This provider adds semantic-search context: chunks of code found by keyword search in the semantic-graph store, mapped back to File entities in the operational graph. It is now a thin renderer over orchestrata_ultimate.knowledge_graph.semantic_bridge, where the reusable search lives. The assembler and context_tools import it; tests/context/test_assembler.py covers it. render_semantic_context carries @traces for REQ-107-015.

Semantic recall runs only for the subjects in SEMANTIC_SUBJECTS: implement, fix_issues, review_and_test and design_review. For other subjects the result is an empty string. The provider builds a query from the user message plus the target files' base names, extracts up to max_terms keywords, calls search_semantic_roots with a per-term limit, and renders the roots with render_semantic_roots, capped by max_lines. Backend access is synchronous. If either graph is unreachable the provider returns an empty string and assembly goes on.

At a glance

Class diagram

No classes; see Functions.

Dependency diagram

API

Functions

Source

Permalink: https://gitlab.com/MSamy/orchestrata-ultimate-architecture/-/blob/a4cbc2bdf/src/orchestrata_ultimate/context/providers/semantic_context.py

"""Semantic-search context provider for volk prompts.

Bridges the Memgraph semantic-graph chunk store with the operational Neo4j
knowledge graph. For a user message and target files, it extracts keyword
terms, searches Memgraph chunks by content, maps the chunks' file paths back
to ``File`` root entities in the graph, and renders a compact markdown block.

This module is now a thin renderer over
``orchestrata_ultimate.knowledge_graph.semantic_bridge``; the reusable
search logic lives there so ``ContextInjector`` and other consumers can use
it without importing the provider package.

All backend access is synchronous: the unified assembler and kernel pipeline
are synchronous, and the Memgraph adapter normally exposes an async interface.
The provider therefore uses the sync Neo4j Bolt driver directly (Memgraph
speaks Bolt) and the operational graph's ``SyncGraphRepository`` seam for
Neo4j lookups.

If either graph is unreachable, the provider degrades to an empty string
rather than failing context assembly.
"""

from __future__ import annotations

import logging
from typing import TYPE_CHECKING

from orchestrata_ultimate.core.base.traces import traces
from orchestrata_ultimate.knowledge_graph.semantic_bridge import (
    _file_name_terms,
    render_semantic_roots,
    search_semantic_roots,
)
from orchestrata_ultimate.semantic_graph.config import SemanticGraphConfig
from orchestrata_ultimate.semantic_graph.ingestion import _extract_query_terms

if TYPE_CHECKING:
    from orchestrata_ultimate.core.graph.interfaces import SyncGraphRepository

_logger = logging.getLogger(__name__)

# Subjects where code-like semantic recall is useful. Kept in lockstep with
# ``context_injector.INJECT_SUBJECTS`` but intentionally narrower: semantic
# chunks are most valuable when the volk is about to read or modify code.
SEMANTIC_SUBJECTS = frozenset(
    {"implement", "fix_issues", "review_and_test", "design_review"}
)


@traces(spec="107", reqs=["REQ-107-015"])
def render_semantic_context(
    user_message: str,
    target_files: list[str],
    *,
    subject: str = "",
    project_id: str | None = None,
    config: SemanticGraphConfig | None = None,
    graph_repo: SyncGraphRepository | None = None,
    max_terms: int = 6,
    limit_per_term: int = 5,
    max_lines: int = 30,
) -> str:
    """Render a compact semantic-search context block.

    Args:
        user_message: Raw user/intent text used to extract keyword terms.
        target_files: Files the volk is being asked to act on; their basenames
            are also used as search terms.
        subject: CXP packet subject. Semantic recall only runs for subjects
            in ``SEMANTIC_SUBJECTS``.
        project_id: Optional project scope for Neo4j ``File`` lookups.
        config: Semantic-graph config (Memgraph URI, chunk label). Defaults to
            ``SemanticGraphConfig.from_env()``.
        neo4j_repo: Optional operational-graph repository for mapping chunk
            file paths back to ``File`` root entities. When omitted, a default
            repository is created lazily.
        max_terms: Maximum keyword terms extracted from the combined query.
        limit_per_term: Maximum chunks returned per term.
        max_lines: Hard line cap to keep the block inside its token budget.

    Returns:
        Markdown semantic context block, or "" when no relevant chunks are
        found or any backend is unreachable.
    """
    if subject and subject not in SEMANTIC_SUBJECTS:
        return ""

    query_text = user_message + " " + " ".join(_file_name_terms(target_files))
    terms = _extract_query_terms(query_text, max_terms=max_terms)
    if not terms:
        return ""

    roots = search_semantic_roots(
        query=user_message,
        target_files=target_files,
        project_id=project_id,
        config=config,
        graph_repo=graph_repo,
        max_terms=max_terms,
        limit_per_term=limit_per_term,
    )
    return render_semantic_roots(roots, terms, max_lines=max_lines)