codenib.integrations

Compatibility providers for external coding-agent runtimes.

Modules:

Name	Description
agentless	Classic Agentless repository context over manifest-backed views.
cosil	CoSIL localization tools over CodeNib manifest-backed source views.
locagent	LocAgent/OpenHands-compatible tools over CodeNib repository views.
orcaloca	OrcaLoca search-manager compatibility over CodeNib repository views.
reponavigator	RepoNavigator's published jump tool over CodeNib repository views.
swe_explore	SWE-Explore's ranked-region contract over CodeNib repository exploration.

Classes:

Name	Description
IntegrationCapabilityError	A required manifest view is missing, stale, or failed to load.
RepositoryAdapter	Read-only repository facts backed by one ServerContext.
RepositoryEntity	A stable adapter-local view of one graph vertex.
RepositoryPathError	A requested path is invalid or escapes the manifest repository.
CodeNibSWEExploreExplorer	Adapt CodeNib's native explorer to SWE-Explore's region protocol.
SWEExploreContextRegion	One source region in SWE-Explore's external coordinate system.
SWEExploreResult	One ranked result compatible with SWE-Explore's explorer protocol.

IntegrationCapabilityError

Bases: RuntimeError

A required manifest view is missing, stale, or failed to load.

RepositoryAdapter

RepositoryAdapter(context: Any, *, require_graph: bool = True)

Read-only repository facts backed by one ServerContext.

Methods:

Name	Description
from_manifest	Load one ServerContext and bind an adapter to it.
require_view	Return a loaded view or raise with manifest-aware diagnostics.
normalize_path	Return a safe repository-relative POSIX path.
read_range	Read an inclusive 0-based range and return its actual bounds.
containing_entity	Return the narrowest symbol containing a 0-based source line.
distance	Return the shorter directed distance, or -1 if unresolved.
file_tree	Render a deterministic tree from files represented in the graph.
skeleton	Render a language-neutral signature skeleton from graph ranges.

Source code in codenib/integrations/_repository.py

def __init__(self, context: Any, *, require_graph: bool = True) -> None:
    self.context = context
    manifest = getattr(context, "manifest", None)
    if manifest is None:
        raise IntegrationCapabilityError("ServerContext has no manifest")

    raw_root = str(getattr(manifest, "repo_path", "") or "").strip()
    if not raw_root:
        raise IntegrationCapabilityError("manifest has no repository path")
    self.repo_root = Path(raw_root).expanduser().resolve()
    if not self.repo_root.is_dir():
        raise IntegrationCapabilityError(
            f"manifest repository is not available: {self.repo_root}"
        )

    self.graph = getattr(context, "symbol_graph", None)
    if require_graph and self.graph is None:
        self.require_view("symbol_graph", "symbol_graph")

    self._entities: tuple[RepositoryEntity, ...] = ()
    self._entity_by_vertex: dict[int, RepositoryEntity] = {}
    self._entity_by_canonical: dict[str, RepositoryEntity] = {}
    self._aliases: dict[str, list[RepositoryEntity]] = {}
    self._aliases_lower: dict[str, list[RepositoryEntity]] = {}
    self._files: tuple[str, ...] = ()
    if self.graph is not None:
        self._build_entity_index()

from_manifest classmethod

from_manifest(
    manifest_path: str | Path, *, require_graph: bool = True
) -> "RepositoryAdapter"

Load one ServerContext and bind an adapter to it.

Source code in codenib/integrations/_repository.py

@classmethod
def from_manifest(
    cls, manifest_path: str | Path, *, require_graph: bool = True
) -> "RepositoryAdapter":
    """Load one ``ServerContext`` and bind an adapter to it."""

    from ..mcp.context import ServerContext

    views = {"symbol_graph"} if require_graph else set()
    return cls(
        ServerContext.load(manifest_path, views=views),
        require_graph=require_graph,
    )

require_view

require_view(index_name: str, attribute: str) -> Any

Return a loaded view or raise with manifest-aware diagnostics.

Source code in codenib/integrations/_repository.py

def require_view(self, index_name: str, attribute: str) -> Any:
    """Return a loaded view or raise with manifest-aware diagnostics."""

    view = getattr(self.context, attribute, None)
    if view is not None:
        return view

    manifest = self.context.manifest
    entry = getattr(manifest, "indexes", {}).get(index_name)
    errors = getattr(self.context, "errors", {})
    if index_name in errors:
        detail = f"failed to load: {errors[index_name]}"
    elif entry is None:
        detail = "no manifest entry"
    elif not manifest.index_is_current(index_name):
        detail = f"manifest status is {entry.status!r} or source identity is stale"
    else:
        detail = "manifest entry did not produce a runtime view"
    raise IntegrationCapabilityError(
        f"required {index_name!r} view is unavailable ({detail})"
    )

normalize_path

normalize_path(value: str) -> str

Return a safe repository-relative POSIX path.

Source code in codenib/integrations/_repository.py

def normalize_path(self, value: str) -> str:
    """Return a safe repository-relative POSIX path."""

    raw = str(value or "").strip().replace("\\", "/")
    while raw.startswith("./"):
        raw = raw[2:]
    if not raw or raw in {".", "/"}:
        return "."
    if raw.startswith("/") or _WINDOWS_DRIVE.match(raw):
        raise RepositoryPathError(
            f"absolute repository path is not allowed: {value}"
        )

    pure = PurePosixPath(raw)
    if ".." in pure.parts:
        raise RepositoryPathError(
            f"repository path traversal is not allowed: {value}"
        )

    normalized = pure.as_posix()
    candidate = (self.repo_root / normalized).resolve()
    if not candidate.is_relative_to(self.repo_root):
        raise RepositoryPathError(f"repository path escapes the root: {value}")
    return normalized

read_range

read_range(
    file_path: str, start_line: int | None = None, end_line: int | None = None
) -> tuple[str, int, int]

Read an inclusive 0-based range and return its actual bounds.

Source code in codenib/integrations/_repository.py

def read_range(
    self,
    file_path: str,
    start_line: int | None = None,
    end_line: int | None = None,
) -> tuple[str, int, int]:
    """Read an inclusive 0-based range and return its actual bounds."""

    lines = self.source_lines(file_path)
    if not lines:
        return "", 0, 0
    start = 0 if start_line is None else max(0, int(start_line))
    end = len(lines) - 1 if end_line is None else min(len(lines) - 1, int(end_line))
    if end < start:
        return "", start, start
    return "\n".join(lines[start : end + 1]), start, end

containing_entity

containing_entity(file_path: str, line: int) -> RepositoryEntity | None

Return the narrowest symbol containing a 0-based source line.

Source code in codenib/integrations/_repository.py

def containing_entity(self, file_path: str, line: int) -> RepositoryEntity | None:
    """Return the narrowest symbol containing a 0-based source line."""

    files = self.find_files(file_path)
    if len(files) != 1:
        return None
    matches = [
        entity
        for entity in self.symbols
        if entity.file_path == files[0]
        and entity.start_line is not None
        and entity.end_line is not None
        and entity.start_line <= line <= entity.end_line
    ]
    if not matches:
        return None
    return min(
        matches,
        key=lambda entity: (
            (entity.end_line or 0) - (entity.start_line or 0),
            -(entity.start_line or 0),
            entity.locagent_id,
        ),
    )

distance

distance(first: str, second: str) -> int

Return the shorter directed distance, or -1 if unresolved.

Source code in codenib/integrations/_repository.py

def distance(self, first: str, second: str) -> int:
    """Return the shorter directed distance, or ``-1`` if unresolved."""

    if self.graph is None:
        self.require_view("symbol_graph", "symbol_graph")
    left = self.find_entities(first)
    right = self.find_entities(second)
    if len(left) != 1 or len(right) != 1:
        return -1
    forward = self.graph.graph.distances(
        [left[0].vertex_id], [right[0].vertex_id], mode="out"
    )[0][0]
    backward = self.graph.graph.distances(
        [right[0].vertex_id], [left[0].vertex_id], mode="out"
    )[0][0]
    finite = [
        distance
        for distance in (forward, backward)
        if not (isinstance(distance, float) and math.isinf(distance))
    ]
    if not finite:
        return -1
    return int(min(finite))

file_tree

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

Render a deterministic tree from files represented in the graph.

Source code in codenib/integrations/_repository.py

def file_tree(self, name: str | None = None, max_depth: int | None = None) -> str:
    """Render a deterministic tree from files represented in the graph."""

    prefix = str(name or "").strip().replace("\\", "/").strip("/")
    files = list(self._files)
    if prefix:
        exact_files = self.find_files(prefix)
        if exact_files:
            files = exact_files
            prefix = str(PurePosixPath(exact_files[0]).parent)
            if prefix == ".":
                prefix = ""
        else:
            files = [
                file_path
                for file_path in files
                if file_path == prefix or file_path.startswith(prefix + "/")
            ]
    if not files:
        return f"Cannot find the file tree rooted at {name}"

    root: dict[str, Any] = {}
    for file_path in files:
        parts = PurePosixPath(file_path).parts
        if prefix:
            prefix_parts = PurePosixPath(prefix).parts
            if tuple(parts[: len(prefix_parts)]) == prefix_parts:
                parts = parts[len(prefix_parts) :]
        node = root
        for part in parts:
            node = node.setdefault(part, {})

    limit = (
        None
        if max_depth is None or int(max_depth) == -1
        else max(0, int(max_depth))
    )
    lines = [prefix or "/"]

    def render(tree: Mapping[str, Any], indent: str, level: int) -> None:
        if limit is not None and level >= limit:
            return
        items = sorted(tree.items(), key=lambda item: (bool(item[1]), item[0]))
        for index, (label, children) in enumerate(items):
            last = index == len(items) - 1
            lines.append(f"{indent}{'`-- ' if last else '|-- '}{label}")
            render(
                children,
                indent + ("    " if last else "|   "),
                level + 1,
            )

    render(root, "", 0)
    return "\n".join(lines)

skeleton

skeleton(entity: RepositoryEntity) -> str

Render a language-neutral signature skeleton from graph ranges.

Source code in codenib/integrations/_repository.py

def skeleton(self, entity: RepositoryEntity) -> str:
    """Render a language-neutral signature skeleton from graph ranges."""

    children = self.children(entity)
    records = [entity] if entity.kind != NODE_TYPE_FILE else []
    records.extend(children)
    signatures: list[str] = []
    for record in records:
        if not record.file_path or record.start_line is None:
            continue
        content, _, _ = self.read_range(
            record.file_path, record.start_line, record.start_line
        )
        signature = content.strip()
        if not signature:
            signature = record.qualified_name or record.simple_name
        if record is not entity:
            signature = "    " + signature
        signatures.append(signature)
    return "\n".join(signatures)

RepositoryEntity dataclass

RepositoryEntity(
    vertex_id: int,
    canonical_name: str,
    display_name: str,
    kind: str,
    file_path: str,
    qualified_name: str,
    simple_name: str,
    start_line: int | None,
    end_line: int | None,
    parent_name: str | None = None,
    class_name: str | None = None,
)

A stable adapter-local view of one graph vertex.

Lines remain 0-based internally. Integrations convert them exactly once while formatting results for their external agent contract.

RepositoryPathError

Bases: ValueError

A requested path is invalid or escapes the manifest repository.

CodeNibSWEExploreExplorer

CodeNibSWEExploreExplorer(
    explorer: RepositoryContextExplorer, *, include_snippets: bool = False
)

Adapt CodeNib's native explorer to SWE-Explore's region protocol.

Methods:

Name	Description
from_manifest	Bind the protocol adapter to an existing CodeNib manifest.
from_repository	Resolve and validate the manifest bound to one checkout.
prepare	Load the native views selected for a benchmark query.
explore	Return at most top_k ranked, valid source regions.

Source code in codenib/integrations/swe_explore.py

def __init__(
    self,
    explorer: RepositoryContextExplorer,
    *,
    include_snippets: bool = False,
) -> None:
    self.runtime = explorer
    self.include_snippets = bool(include_snippets)
    self.last_trace: RepositoryExploreTrace | None = None

from_manifest classmethod

from_manifest(
    manifest_path: str | Path,
    *,
    include_snippets: bool = False,
    policy: str = "auto",
    budget: BudgetInput = "balanced",
    level: str = "l2"
) -> "CodeNibSWEExploreExplorer"

Bind the protocol adapter to an existing CodeNib manifest.

Source code in codenib/integrations/swe_explore.py

@classmethod
def from_manifest(
    cls,
    manifest_path: str | Path,
    *,
    include_snippets: bool = False,
    policy: str = "auto",
    budget: BudgetInput = "balanced",
    level: str = "l2",
) -> "CodeNibSWEExploreExplorer":
    """Bind the protocol adapter to an existing CodeNib manifest."""

    runtime = RepositoryContextExplorer.from_manifest(
        manifest_path,
        policy=policy,
        budget=budget,
        level=level,
    )
    return cls(runtime, include_snippets=include_snippets)

from_repository classmethod

from_repository(
    repo_path: str | Path,
    *,
    manifest_path: str | Path | None = None,
    include_snippets: bool = False,
    policy: str = "auto",
    budget: BudgetInput = "balanced",
    level: str = "l2"
) -> "CodeNibSWEExploreExplorer"

Resolve and validate the manifest bound to one checkout.

Source code in codenib/integrations/swe_explore.py

@classmethod
def from_repository(
    cls,
    repo_path: str | Path,
    *,
    manifest_path: str | Path | None = None,
    include_snippets: bool = False,
    policy: str = "auto",
    budget: BudgetInput = "balanced",
    level: str = "l2",
) -> "CodeNibSWEExploreExplorer":
    """Resolve and validate the manifest bound to one checkout."""

    runtime = RepositoryContextExplorer.from_repository(
        repo_path,
        manifest_path=manifest_path,
        policy=policy,
        budget=budget,
        level=level,
    )
    return cls(
        runtime,
        include_snippets=include_snippets,
    )

prepare

prepare(query: str) -> RepositoryExplorePreparation

Load the native views selected for a benchmark query.

Source code in codenib/integrations/swe_explore.py

def prepare(self, query: str) -> RepositoryExplorePreparation:
    """Load the native views selected for a benchmark query."""

    return self.runtime.prepare(query)

explore

explore(*, instance_id: str, query: str, top_k: int = 5) -> list[SWEExploreResult]

Return at most top_k ranked, valid source regions.

top_k is a region-count cutoff. SWE-Explore's Recall@100/300/500 metrics apply a separate cumulative-line budget in the scorer.

Source code in codenib/integrations/swe_explore.py

def explore(
    self,
    *,
    instance_id: str,
    query: str,
    top_k: int = 5,
) -> list[SWEExploreResult]:
    """Return at most ``top_k`` ranked, valid source regions.

    ``top_k`` is a region-count cutoff.  SWE-Explore's Recall@100/300/500
    metrics apply a separate cumulative-line budget in the scorer.
    """

    result = self.runtime.explore(
        str(query or ""),
        top_k=top_k,
        include_content=self.include_snippets,
    )
    self.last_trace = result.trace
    return [
        SWEExploreResult(
            instance_id=str(instance_id),
            score=item.score,
            regions=(
                SWEExploreContextRegion(
                    path=item.path,
                    start=item.start_line + 1,
                    end=item.end_line + 1,
                    snippet=item.content,
                ),
            ),
        )
        for item in result.evidence
    ]

SWEExploreContextRegion dataclass

SWEExploreContextRegion(path: str, start: int, end: int, snippet: str | None = None)

One source region in SWE-Explore's external coordinate system.

Methods:

Name	Description
to_record	Return the official JSON-compatible region representation.

to_record

to_record() -> dict[str, str | int | None]

Return the official JSON-compatible region representation.

Source code in codenib/integrations/swe_explore.py

def to_record(self) -> dict[str, str | int | None]:
    """Return the official JSON-compatible region representation."""

    return {
        "path": self.path,
        "start": self.start,
        "end": self.end,
        "snippet": self.snippet,
    }

SWEExploreResult dataclass

SWEExploreResult(
    instance_id: str, score: float, regions: tuple[SWEExploreContextRegion, ...]
)

One ranked result compatible with SWE-Explore's explorer protocol.

Methods:

Name	Description
to_record	Return a stable JSON-ready result.

to_record

to_record() -> dict[str, Any]

Return a stable JSON-ready result.

Source code in codenib/integrations/swe_explore.py

def to_record(self) -> dict[str, Any]:
    """Return a stable JSON-ready result."""

    return {
        "instance_id": self.instance_id,
        "score": self.score,
        "regions": [region.to_record() for region in self.regions],
    }