codenib.integrations.orcaloca

OrcaLoca search-manager compatibility over CodeNib repository views.

The upstream search policy is coupled to several private SearchManager helpers in addition to its six tools. This provider implements that pinned duck-typed surface while keeping OrcaLoca's policy, LlamaIndex wrappers, and queue/scoring types outside CodeNib.

Classes:

Name	Description
OrcaLocation	Dependency-free equivalent of OrcaLoca's Loc named tuple.
OrcaLocationInfo	Dependency-free equivalent of OrcaLoca's LocInfo wrapper.
OrcaLocaSearchProvider	Duck-typed replacement for OrcaLoca's pinned SearchManager.

Functions:

Name	Description
make_orcaloca_search_manager_factory	Build the factory accepted by the proposed upstream injection seam.
orcaloca_bug_location	Translate one CodeNib entity to OrcaLoca's final location schema.

OrcaLocation

Bases: NamedTuple

Dependency-free equivalent of OrcaLoca's Loc named tuple.

OrcaLocationInfo dataclass

OrcaLocationInfo(loc: OrcaLocation, type: str)

Dependency-free equivalent of OrcaLoca's LocInfo wrapper.

OrcaLocaSearchProvider

OrcaLocaSearchProvider(
    context: Any,
    *,
    file_skeleton_threshold: int = 200,
    class_skeleton_threshold: int = 100,
    max_output_chars: int = 48000
)

Duck-typed replacement for OrcaLoca's pinned SearchManager.

Methods:

Name	Description
search_file_tree	Return the repository file tree, optionally rooted at a directory.
search_file_contents	Return one file's content or a graph-derived large-file skeleton.
search_source_code	Find the narrowest graph symbol containing a source fragment.
search_class	Return one class or ask the agent to disambiguate its file.
search_method_in_class	Return a method constrained by class and optional file.
search_callable	Return a class, function, method, or symbol definition.

Source code in codenib/integrations/orcaloca.py

def __init__(
    self,
    context: Any,
    *,
    file_skeleton_threshold: int = 200,
    class_skeleton_threshold: int = 100,
    max_output_chars: int = 48_000,
) -> None:
    self.repository = RepositoryAdapter(context, require_graph=True)
    self.repo_path = str(self.repository.repo_root)
    self.file_skeleton_threshold = max(1, int(file_skeleton_threshold))
    self.class_skeleton_threshold = max(1, int(class_skeleton_threshold))
    self.max_output_chars = max(2_000, int(max_output_chars))
    self.history: list[dict[str, Any]] = []
    self.history_query_set: set[str] = set()
    self._python_outline_cache: dict[str, PythonOutline | None] = {}

search_file_tree

search_file_tree(name: str | None = None, max_depth: int | None = None) -> str

Return the repository file tree, optionally rooted at a directory.

Source code in codenib/integrations/orcaloca.py

def search_file_tree(
    self, name: str | None = None, max_depth: int | None = None
) -> str:
    """Return the repository file tree, optionally rooted at a directory."""

    content = self._search_file_tree(name, max_depth)
    self._record(
        action="search_file_tree",
        search_input=name,
        query=name,
        content=content,
        query_type="file_tree",
    )
    return self._bounded(content)

search_file_contents

search_file_contents(file_name: str, directory_path: str | None = None) -> str

Return one file's content or a graph-derived large-file skeleton.

Source code in codenib/integrations/orcaloca.py

def search_file_contents(
    self, file_name: str, directory_path: str | None = None
) -> str:
    """Return one file's content or a graph-derived large-file skeleton."""

    search_input = (
        f"{directory_path.rstrip('/')}/{file_name}" if directory_path else file_name
    )
    files = self.repository.find_files(search_input)
    if not directory_path:
        files = self.repository.find_files(file_name)
    if not files:
        return f"Cannot find the file {file_name}"
    if len(files) > 1:
        content = self._disambiguation(
            f"Multiple matches found for file {file_name}.", files=files
        )
        self._record(
            action="search_file_contents",
            search_input=search_input,
            query=file_name,
            content=content,
            query_type="disambiguation",
        )
        return content

    file_path = files[0]
    entity = self.repository.entity_for_file(file_path)
    if entity is None:
        return f"Cannot find the file {file_name}"
    source = self._source(entity)
    line_count = len(source.splitlines())
    is_skeleton = max(0, line_count - 1) > self.file_skeleton_threshold
    content = self._file_skeleton(entity) if is_skeleton else source
    self._record(
        action="search_file_contents",
        search_input=search_input,
        query=entity.orcaloca_id,
        content=content,
        query_type="file",
        file_path=file_path,
        is_skeleton=is_skeleton,
    )
    marker = "File Skeleton" if is_skeleton else "File Content"
    return self._bounded(f"File Path: {file_path} \n{marker}: \n{content}")

search_source_code

search_source_code(file_path: str, source_code: str) -> str

Find the narrowest graph symbol containing a source fragment.

Source code in codenib/integrations/orcaloca.py

def search_source_code(self, file_path: str, source_code: str) -> str:
    """Find the narrowest graph symbol containing a source fragment."""

    content = self._search_source_code(file_path, source_code)
    self._record(
        action="search_source_code",
        search_input=source_code,
        query=source_code,
        content=content,
        query_type="source_code",
        file_path=file_path,
    )
    return self._bounded(f"File Path: {file_path} \nCode Snippet: \n{content}")

search_class

search_class(class_name: str, file_path: str | None = None) -> str

Return one class or ask the agent to disambiguate its file.

Source code in codenib/integrations/orcaloca.py

def search_class(self, class_name: str, file_path: str | None = None) -> str:
    """Return one class or ask the agent to disambiguate its file."""

    search_input = f"{file_path}::{class_name}" if file_path else class_name
    classes = self.repository.find_entities(
        class_name, file_path=file_path, kinds={NODE_TYPE_CLASS}
    )
    classes = [entity for entity in classes if self._is_orcaloca_entity(entity)]
    if not classes:
        suffix = f" in {file_path}" if file_path else ""
        return f"Cannot find the class {class_name}{suffix}"
    if len(classes) > 1:
        content = self._disambiguation(
            f"Multiple matched classes found about class: {class_name}.",
            entities=classes,
        )
        self._record(
            action="search_class",
            search_input=search_input,
            query=class_name,
            content=content,
            query_type="disambiguation",
        )
        return content

    entity = classes[0]
    is_skeleton = self._line_span(entity) > self.class_skeleton_threshold
    content = self._class_skeleton(entity) if is_skeleton else self._source(entity)
    self._record(
        action="search_class",
        search_input=search_input,
        query=entity.orcaloca_id,
        content=content,
        query_type="class",
        file_path=entity.file_path,
        is_skeleton=is_skeleton,
    )
    marker = "Class Skeleton" if is_skeleton else "Class Content"
    return self._bounded(f"File Path: {entity.file_path} \n{marker}: \n{content}")

search_method_in_class

search_method_in_class(
    class_name: str, method_name: str, file_path: str | None = None
) -> str

Return a method constrained by class and optional file.

Source code in codenib/integrations/orcaloca.py

def search_method_in_class(
    self,
    class_name: str,
    method_name: str,
    file_path: str | None = None,
) -> str:
    """Return a method constrained by class and optional file."""

    search_input = (
        f"{file_path}::{class_name}::{method_name}"
        if file_path
        else f"{class_name}::{method_name}"
    )
    methods = self.repository.find_entities(
        method_name,
        file_path=file_path,
        kinds=_METHOD_KINDS,
        class_name=class_name,
    )
    methods = [
        entity
        for entity in methods
        if self._is_orcaloca_entity(entity) and self._query_type(entity) == "method"
    ]
    if not methods:
        suffix = f" in {file_path}" if file_path else ""
        return f"Cannot find the method {method_name} in {class_name}{suffix}"
    if len(methods) > 1:
        content = self._disambiguation(
            f"Multiple matched methods found about method: {method_name} "
            f"in class: {class_name}.",
            entities=methods,
        )
        self._record(
            action="search_method_in_class",
            search_input=search_input,
            query=method_name,
            content=content,
            query_type="disambiguation",
        )
        return content

    entity = methods[0]
    content = self._source(entity)
    self._record(
        action="search_method_in_class",
        search_input=search_input,
        query=entity.orcaloca_id,
        content=content,
        query_type="method",
        file_path=entity.file_path,
    )
    return self._bounded(
        f"File Path: {entity.file_path} \nMethod Content: \n{content}"
    )

search_callable

search_callable(query_name: str, file_path: str | None = None) -> str

Return a class, function, method, or symbol definition.

Source code in codenib/integrations/orcaloca.py

def search_callable(self, query_name: str, file_path: str | None = None) -> str:
    """Return a class, function, method, or symbol definition."""

    search_input = f"{file_path}::{query_name}" if file_path else query_name
    entities = self.repository.find_entities(
        query_name, file_path=file_path, kinds=_CALLABLE_KINDS
    )
    entities = [entity for entity in entities if self._is_orcaloca_entity(entity)]
    if not entities:
        suffix = f" in {file_path}" if file_path else ""
        return f"Cannot find the definition of {query_name}{suffix}"
    if len(entities) > 1:
        content = self._disambiguation(
            f"Multiple matched callables found about query {query_name}.",
            entities=entities,
        )
        self._record(
            action="search_callable",
            search_input=search_input,
            query=query_name,
            content=content,
            query_type="disambiguation",
            file_path=file_path or "",
        )
        return content

    entity = entities[0]
    query_type = self._query_type(entity)
    if query_type == "class":
        content = self.search_class(query_name, file_path)
        is_skeleton = self._line_span(entity) > self.class_skeleton_threshold
        self._record(
            action="search_callable",
            search_input=search_input,
            query=entity.orcaloca_id,
            content=content,
            query_type=query_type,
            file_path=entity.file_path,
            is_skeleton=is_skeleton,
        )
        return content

    content = self._source(entity)
    self._record(
        action="search_callable",
        search_input=search_input,
        query=entity.orcaloca_id,
        content=content,
        query_type=query_type,
        file_path=entity.file_path,
        is_skeleton=False,
    )
    return self._bounded(
        f"File Path: {entity.file_path} \n"
        f"Query Type: {query_type} \nCode Snippet: \n{content}"
    )

make_orcaloca_search_manager_factory

make_orcaloca_search_manager_factory(
    manifest_path: str | Path, **provider_options: Any
) -> Callable[[str], OrcaLocaSearchProvider]

Build the factory accepted by the proposed upstream injection seam.

Source code in codenib/integrations/orcaloca.py

def make_orcaloca_search_manager_factory(
    manifest_path: str | Path,
    **provider_options: Any,
) -> Callable[[str], OrcaLocaSearchProvider]:
    """Build the factory accepted by the proposed upstream injection seam."""

    resolved_manifest = Path(manifest_path).expanduser().resolve()

    def factory(repo_path: str) -> OrcaLocaSearchProvider:
        provider = OrcaLocaSearchProvider.from_manifest(
            resolved_manifest, **provider_options
        )
        requested = Path(repo_path).expanduser().resolve()
        if requested != provider.repository.repo_root:
            raise ValueError(
                "OrcaLoca repo_path does not match the CodeNib manifest: "
                f"{requested} != {provider.repository.repo_root}"
            )
        return provider

    return factory

orcaloca_bug_location

orcaloca_bug_location(entity: RepositoryEntity) -> dict[str, str]

Translate one CodeNib entity to OrcaLoca's final location schema.

Source code in codenib/integrations/orcaloca.py

def orcaloca_bug_location(
    entity: RepositoryEntity,
) -> dict[str, str]:
    """Translate one CodeNib entity to OrcaLoca's final location schema."""

    query_type = OrcaLocaSearchProvider._graph_query_type(entity)
    return {
        "file_path": entity.file_path,
        "class_name": (
            entity.simple_name if query_type == "class" else entity.class_name or ""
        ),
        "method_name": (
            entity.simple_name if query_type in {"method", "function"} else ""
        ),
    }