databao-context-engine 0.1.1__py3-none-any.whl

databao_context_engine/plugins/unstructured_files_plugin.py

@@ -0,0 +1,68 @@
+import re
+from io import BufferedReader
+from typing import Any, TypedDict
+
+from databao_context_engine.pluginlib.build_plugin import BuildFilePlugin, EmbeddableChunk
+
+
+class FileChunk(TypedDict):
+    chunk_index: int
+    chunk_content: str
+
+
+class InternalUnstructuredFilesPlugin(BuildFilePlugin):
+    id = "jetbrains/unstructured_files"
+    name = "Unstructured Files Plugin"
+
+    _SUPPORTED_FILES_EXTENSIONS = {"txt", "md"}
+
+    _DEFAULT_MAX_TOKENS = 300
+    _DEFAULT_TOKENS_OVERLAP = 50
+
+    def __init__(self, max_tokens: int | None = None, tokens_overlap: int | None = None):
+        self.max_tokens = max_tokens or self._DEFAULT_MAX_TOKENS
+        self.tokens_overlap = tokens_overlap or self._DEFAULT_TOKENS_OVERLAP
+
+    def supported_types(self) -> set[str]:
+        return {f"files/{extension}" for extension in self._SUPPORTED_FILES_EXTENSIONS}
+
+    def build_file_context(self, full_type: str, file_name: str, file_buffer: BufferedReader) -> Any:
+        file_content = self._read_file(file_buffer)
+
+        return {
+            "chunks": self._chunk_file(file_content),
+        }
+
+    def divide_context_into_chunks(self, context: Any) -> list[EmbeddableChunk]:
+        return [self._create_embeddable_chunk_from_file_chunk(file_chunk) for file_chunk in context["chunks"]]
+
+    def _create_embeddable_chunk_from_file_chunk(self, file_chunk: FileChunk) -> EmbeddableChunk:
+        return EmbeddableChunk(
+            embeddable_text=file_chunk["chunk_content"],
+            content=file_chunk,
+        )
+
+    def _read_file(self, file_buffer: BufferedReader) -> str:
+        file_bytes = file_buffer.read()
+        return file_bytes.decode("utf-8")
+
+    def _chunk_file(self, file_content: str) -> list[FileChunk]:
+        words_list = re.split(r"\s+", file_content)
+
+        chunks = []
+
+        chunk_start_index = 0
+        number_of_words = len(words_list)
+        while chunk_start_index < number_of_words:
+            chunk_end_index = min(number_of_words, chunk_start_index + self.max_tokens)
+            chunks.append(
+                FileChunk(
+                    chunk_index=chunk_start_index,
+                    chunk_content=" ".join(words_list[chunk_start_index:chunk_end_index]),
+                )
+            )
+            chunk_start_index = (
+                (chunk_end_index - self.tokens_overlap) if chunk_end_index < number_of_words else number_of_words
+            )
+
+        return chunks

databao_context_engine/project/datasource_discovery.py

@@ -0,0 +1,141 @@
+import logging
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from databao_context_engine.pluginlib.build_plugin import DatasourceType
+from databao_context_engine.project.layout import get_source_dir
+from databao_context_engine.project.types import (
+    DatasourceDescriptor,
+    DatasourceKind,
+    PreparedConfig,
+    PreparedDatasource,
+    PreparedFile,
+    DatasourceId,
+    Datasource,
+)
+from databao_context_engine.templating.renderer import render_template
+
+logger = logging.getLogger(__name__)
+
+
+def get_datasource_list(project_dir: Path) -> list[Datasource]:
+    result = []
+    for discovered_datasource in discover_datasources(project_dir=project_dir):
+        try:
+            prepared_source = prepare_source(discovered_datasource)
+        except Exception as e:
+            logger.debug(str(e), exc_info=True, stack_info=True)
+            logger.info(f"Invalid source at ({discovered_datasource.path}): {str(e)}")
+            continue
+
+        result.append(
+            Datasource(
+                id=DatasourceId.from_datasource_config_file_path(discovered_datasource.path),
+                type=prepared_source.datasource_type,
+            )
+        )
+
+    return result
+
+
+def discover_datasources(project_dir: Path) -> list[DatasourceDescriptor]:
+    """
+    Scan the project's src/ directory and return all discovered sources.
+
+    Rules:
+        - Each first-level directory under src/ is treated as a main_type
+        - Unsupported or unreadable entries are skipped.
+        - The returned list is sorted by directory and then filename
+    """
+    src = get_source_dir(project_dir)
+    if not src.exists() or not src.is_dir():
+        raise ValueError(f"src directory does not exist in {project_dir}")
+
+    datasources: list[DatasourceDescriptor] = []
+    for main_dir in sorted((p for p in src.iterdir() if p.is_dir()), key=lambda p: p.name.lower()):
+        for path in sorted((p for p in main_dir.iterdir() if _is_datasource_file(p)), key=lambda p: p.name.lower()):
+            datasource = load_datasource_descriptor(path)
+            if datasource is not None:
+                datasources.append(datasource)
+
+    return datasources
+
+
+def _is_datasource_file(p: Path) -> bool:
+    # ignore backup files
+    return p.is_file() and not p.suffix.endswith("~")
+
+
+def get_datasource_descriptors(project_dir: Path, datasource_ids: list[DatasourceId]):
+    src = get_source_dir(project_dir)
+    if not src.exists() or not src.is_dir():
+        raise ValueError(f"src directory does not exist in {project_dir}")
+
+    datasources: list[DatasourceDescriptor] = []
+    for datasource_id in datasource_ids:
+        config_file_path = src.joinpath(datasource_id.relative_path_to_config_file())
+        if not config_file_path.is_file():
+            raise ValueError(f"Datasource config file not found: {config_file_path}")
+
+        datasource = load_datasource_descriptor(config_file_path)
+        if datasource is not None:
+            datasources.append(datasource)
+
+    return datasources
+
+
+def load_datasource_descriptor(path: Path) -> DatasourceDescriptor | None:
+    """
+    Load a single file with src/<parent_name>/ into a DatasourceDescriptor
+    """
+    if not path.is_file():
+        return None
+
+    parent_name = path.parent.name
+    extension = path.suffix.lower().lstrip(".")
+
+    if parent_name == "files":
+        return DatasourceDescriptor(path=path.resolve(), main_type=parent_name, kind=DatasourceKind.FILE)
+
+    if extension in {"yaml", "yml"}:
+        return DatasourceDescriptor(path=path.resolve(), main_type=parent_name, kind=DatasourceKind.CONFIG)
+
+    if extension:
+        return DatasourceDescriptor(path=path.resolve(), main_type=parent_name, kind=DatasourceKind.FILE)
+
+    logger.debug("Skipping file without extension: %s", path)
+    return None
+
+
+def prepare_source(datasource: DatasourceDescriptor) -> PreparedDatasource:
+    """
+    Convert a discovered datasource into a prepared datasource ready for plugin execution
+    """
+    if datasource.kind is DatasourceKind.FILE:
+        file_subtype = datasource.path.suffix.lower().lstrip(".")
+        return PreparedFile(
+            datasource_type=DatasourceType.from_main_and_subtypes(main_type=datasource.main_type, subtype=file_subtype),
+            path=datasource.path,
+        )
+
+    else:
+        config = _parse_config_file(datasource.path)
+
+        subtype = config.get("type")
+        if not subtype or not isinstance(subtype, str):
+            raise ValueError("Config missing 'type' at %s - skipping", datasource.path)
+
+        return PreparedConfig(
+            datasource_type=DatasourceType.from_main_and_subtypes(main_type=datasource.main_type, subtype=subtype),
+            path=datasource.path,
+            config=config,
+            datasource_name=datasource.path.stem,
+        )
+
+
+def _parse_config_file(file_path: Path) -> dict[Any, Any]:
+    rendered_file = render_template(file_path.read_text())
+
+    return yaml.safe_load(rendered_file) or {}

databao_context_engine/project/info.py

@@ -0,0 +1,44 @@
+from dataclasses import dataclass
+from importlib.metadata import version
+from pathlib import Path
+from uuid import UUID
+
+from databao_context_engine.project.layout import validate_project_dir
+from databao_context_engine.system.properties import get_dce_path
+
+
+@dataclass(kw_only=True, frozen=True)
+class DceProjectInfo:
+    project_path: Path
+    is_initialised: bool
+    project_id: UUID | None
+
+
+@dataclass(kw_only=True, frozen=True)
+class DceInfo:
+    version: str
+    dce_path: Path
+
+    project_info: DceProjectInfo
+
+
+def get_databao_context_engine_info(project_dir: Path) -> DceInfo:
+    return DceInfo(
+        version=get_dce_version(),
+        dce_path=get_dce_path(),
+        project_info=_get_project_info(project_dir),
+    )
+
+
+def _get_project_info(project_dir: Path) -> DceProjectInfo:
+    project_layout = validate_project_dir(project_dir)
+
+    return DceProjectInfo(
+        project_path=project_dir,
+        is_initialised=project_layout is not None,
+        project_id=project_layout.read_config_file().project_id if project_layout is not None else None,
+    )
+
+
+def get_dce_version() -> str:
+    return version("databao_context_engine")

databao_context_engine/project/init_project.py

@@ -0,0 +1,102 @@
+import shutil
+from enum import Enum
+from pathlib import Path
+
+from databao_context_engine.project.layout import (
+    get_config_file,
+    get_deprecated_config_file,
+    get_examples_dir,
+    get_logs_dir,
+    get_source_dir,
+)
+from databao_context_engine.project.project_config import ProjectConfig
+
+
+class InitErrorReason(Enum):
+    PROJECT_DIR_DOESNT_EXIST = "PROJECT_DIR_DOESNT_EXIST"
+    PROJECT_DIR_NOT_DIRECTORY = "PROJECT_DIR_NOT_DIRECTORY"
+    PROJECT_DIR_ALREADY_INITIALISED = "PROJECT_DIR_ALREADY_INITIALISED"
+
+
+class InitProjectError(Exception):
+    reason: InitErrorReason
+
+    def __init__(self, reason: InitErrorReason, message: str | None):
+        super().__init__(message or "")
+
+        self.reason = reason
+
+
+def init_project_dir(project_dir: Path) -> Path:
+    project_creator = _ProjectCreator(project_dir=project_dir)
+    project_creator.create()
+
+    return project_dir
+
+
+class _ProjectCreator:
+    def __init__(self, project_dir: Path):
+        self.project_dir = project_dir
+        self.deprecated_config_file = get_deprecated_config_file(project_dir)
+        self.config_file = get_config_file(project_dir)
+        self.src_dir = get_source_dir(project_dir)
+        self.examples_dir = get_examples_dir(project_dir)
+        self.logs_dir = get_logs_dir(project_dir)
+
+    def create(self):
+        self.ensure_can_init_project()
+
+        self.create_default_src_dir()
+        self.create_logs_dir()
+        self.create_examples_dir()
+        self.create_dce_config_file()
+
+    def ensure_can_init_project(self) -> bool:
+        if not self.project_dir.exists():
+            raise InitProjectError(
+                message=f"{self.project_dir.resolve()} does not exist", reason=InitErrorReason.PROJECT_DIR_DOESNT_EXIST
+            )
+
+        if not self.project_dir.is_dir():
+            raise InitProjectError(
+                message=f"{self.project_dir.resolve()} is not a directory",
+                reason=InitErrorReason.PROJECT_DIR_NOT_DIRECTORY,
+            )
+
+        if self.config_file.is_file() or self.deprecated_config_file.is_file():
+            raise InitProjectError(
+                message=f"Can't initialise a Databao Context Engine project in a folder that already contains a config file. [project_dir: {self.project_dir.resolve()}]",
+                reason=InitErrorReason.PROJECT_DIR_ALREADY_INITIALISED,
+            )
+
+        if self.src_dir.is_dir():
+            raise InitProjectError(
+                message=f"Can't initialise a Databao Context Engine project in a folder that already contains a src directory. [project_dir: {self.project_dir.resolve()}]",
+                reason=InitErrorReason.PROJECT_DIR_ALREADY_INITIALISED,
+            )
+
+        if self.examples_dir.is_file():
+            raise InitProjectError(
+                message=f"Can't initialise a Databao Context Engine project in a folder that already contains an examples dir. [project_dir: {self.project_dir.resolve()}]",
+                reason=InitErrorReason.PROJECT_DIR_ALREADY_INITIALISED,
+            )
+
+        return True
+
+    def create_default_src_dir(self) -> None:
+        self.src_dir.mkdir(parents=False, exist_ok=False)
+
+        self.src_dir.joinpath("databases").mkdir(parents=False, exist_ok=False)
+        self.src_dir.joinpath("files").mkdir(parents=False, exist_ok=False)
+
+    def create_logs_dir(self) -> None:
+        self.logs_dir.mkdir(exist_ok=True)
+
+    def create_examples_dir(self) -> None:
+        examples_to_copy = Path(__file__).parent.joinpath("resources").joinpath("examples")
+
+        shutil.copytree(str(examples_to_copy), str(self.examples_dir))
+
+    def create_dce_config_file(self) -> None:
+        self.config_file.touch()
+        ProjectConfig().save(self.config_file)

databao_context_engine/project/layout.py

@@ -0,0 +1,127 @@
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+
+from databao_context_engine.project.project_config import ProjectConfig
+from databao_context_engine.project.types import DatasourceId
+
+SOURCE_FOLDER_NAME = "src"
+OUTPUT_FOLDER_NAME = "output"
+EXAMPLES_FOLDER_NAME = "examples"
+LOGS_FOLDER_NAME = "logs"
+DEPRECATED_CONFIG_FILE_NAME = "nemory.ini"
+CONFIG_FILE_NAME = "dce.ini"
+ALL_RESULTS_FILE_NAME = "all_results.yaml"
+
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class ProjectLayout:
+    project_dir: Path
+    config_file: Path
+
+    def read_config_file(self) -> ProjectConfig:
+        return ProjectConfig.from_file(self.config_file)
+
+
+def ensure_project_dir(project_dir: Path) -> ProjectLayout:
+    return _ProjectValidator(project_dir).ensure_project_dir_valid()
+
+
+def is_project_dir_valid(project_dir: Path) -> bool:
+    return validate_project_dir(project_dir) is not None
+
+
+def validate_project_dir(project_dir: Path) -> ProjectLayout | None:
+    return _ProjectValidator(project_dir).validate()
+
+
+def get_source_dir(project_dir: Path) -> Path:
+    return project_dir.joinpath(SOURCE_FOLDER_NAME)
+
+
+def get_output_dir(project_dir: Path) -> Path:
+    return project_dir.joinpath(OUTPUT_FOLDER_NAME)
+
+
+def get_examples_dir(project_dir: Path) -> Path:
+    return project_dir.joinpath(EXAMPLES_FOLDER_NAME)
+
+
+def get_deprecated_config_file(project_dir: Path) -> Path:
+    return project_dir.joinpath(DEPRECATED_CONFIG_FILE_NAME)
+
+
+def get_config_file(project_dir: Path) -> Path:
+    return project_dir.joinpath(CONFIG_FILE_NAME)
+
+
+def get_logs_dir(project_dir: Path) -> Path:
+    return project_dir.joinpath(LOGS_FOLDER_NAME)
+
+
+def ensure_datasource_config_file_doesnt_exist(project_dir: Path, datasource_id: DatasourceId) -> Path:
+    config_file = get_source_dir(project_dir).joinpath(datasource_id.relative_path_to_config_file())
+
+    if config_file.is_file():
+        raise ValueError(f"A config file already exists for {str(datasource_id)}")
+
+    return config_file
+
+
+def create_datasource_config_file(
+    project_dir: Path, datasource_id: DatasourceId, config_content: str, overwrite_existing: bool
+) -> Path:
+    if not overwrite_existing:
+        ensure_datasource_config_file_doesnt_exist(project_dir, datasource_id)
+
+    config_file = get_source_dir(project_dir).joinpath(datasource_id.relative_path_to_config_file())
+    config_file.parent.mkdir(parents=True, exist_ok=True)
+
+    config_file.write_text(config_content)
+
+    return config_file
+
+
+class _ProjectValidator:
+    def __init__(self, project_dir: Path):
+        self.project_dir = project_dir
+        self.config_file = self.get_config_file()
+
+    def ensure_project_dir_valid(self) -> ProjectLayout:
+        if not self.project_dir.is_dir():
+            raise ValueError(f"The current project directory is not valid: {self.project_dir.resolve()}")
+
+        if self.config_file is None:
+            raise ValueError(
+                f"The current project directory has not been initialised. It should contain a config file. [project_dir: {self.project_dir.resolve()}]"
+            )
+
+        if not self.is_src_valid():
+            raise ValueError(
+                f"The current project directory has not been initialised. It should contain a src directory. [project_dir: {self.project_dir.resolve()}]"
+            )
+
+        return ProjectLayout(project_dir=self.project_dir, config_file=self.config_file)
+
+    def validate(self) -> ProjectLayout | None:
+        if self.config_file is not None and self.is_src_valid():
+            return ProjectLayout(project_dir=self.project_dir, config_file=self.config_file)
+        return None
+
+    def is_src_valid(self) -> bool:
+        return get_source_dir(self.project_dir).is_dir()
+
+    def get_config_file(self) -> Path | None:
+        deprecated_config_file = get_deprecated_config_file(self.project_dir)
+        if deprecated_config_file.is_file():
+            logger.warning(
+                f"{DEPRECATED_CONFIG_FILE_NAME} project config file is deprecated, please rename this file to {CONFIG_FILE_NAME}"
+            )
+            return deprecated_config_file.resolve()
+        config_file = get_config_file(self.project_dir)
+        if config_file.is_file():
+            return config_file.resolve()
+        return None

databao_context_engine/project/project_config.py

@@ -0,0 +1,32 @@
+import configparser
+import uuid
+from pathlib import Path
+
+
+class ProjectConfig:
+    # Since we're supporting Python 3.10, we have to add a section
+    # configparser.UNNAMED_SECTION was only introduced in Python 3.13
+    _DEFAULT_SECTION = "DEFAULT"
+    _PROJECT_ID_PROPERTY_NAME = "project-id"
+
+    project_id: uuid.UUID
+
+    @staticmethod
+    def from_file(project_config_file: Path) -> "ProjectConfig":
+        with open(project_config_file, "r") as file_stream:
+            config = configparser.ConfigParser()
+            config.read_file(file_stream)
+
+            return ProjectConfig(
+                project_id=uuid.UUID(config[ProjectConfig._DEFAULT_SECTION][ProjectConfig._PROJECT_ID_PROPERTY_NAME])
+            )
+
+    def __init__(self, project_id: uuid.UUID | None = None):
+        self.project_id = project_id or uuid.uuid4()
+
+    def save(self, project_config_file: Path) -> None:
+        config = configparser.ConfigParser()
+        config[self._DEFAULT_SECTION][self._PROJECT_ID_PROPERTY_NAME] = str(self.project_id)
+
+        with open(project_config_file, "w") as file_stream:
+            config.write(file_stream)

databao_context_engine/project/resources/examples/src/databases/example_postgres.yaml

@@ -0,0 +1,7 @@
+type: postgres
+connection:
+  # your database connection configurations
+  host: localhost
+  port: 5432
+  user: username
+  password: password

databao_context_engine/project/resources/examples/src/files/documentation.md

@@ -0,0 +1,30 @@
+# Project Notes — September 2025
+
+## Overview
+
+This project integrates database introspection, dbt metadata, and document embeddings to create a unified data context
+engine.
+
+## Goals
+
+- Enable users to search and reason about their data environment in natural language.
+- Extend support to plain text and PDF documents to capture unstructured knowledge.
+- Provide consistent output structure under the `/output/run-<timestamp>` folders.
+
+## Next Steps
+
+1. Finish the file ingestion subsystem (loader, service, exporter).
+2. Add PDF parsing and chunking support.
+3. Implement caching for large document embeddings.
+4. Evaluate chunking strategies for better recall during querying.
+
+## Open Questions
+
+- Should we embed entire paragraphs or split by sentence boundaries?
+- How do we handle private/sensitive data inside document chunks?
+- Could the system use source control metadata (e.g., Git history) to enrich document context?
+
+## Summary
+
+Once completed, the system will allow querying across databases, dbt models, and raw files — a single interface for
+exploring data knowledge.

databao_context_engine/project/resources/examples/src/files/notes.txt

@@ -0,0 +1,20 @@
+The Vision: To empower developers worldwide with a seamless AI‑powered collaborative code editor that blends real‑time collaboration with intelligent assistance, debugging, and predictive coding suggestions.
+The project, dubbed "CoDev‑AI," is an open‑source, web‑based platform built on a microservices architecture that allows plug‑ins, language models, and cloud storage to interoperate efficiently.
+
+At its core, the editor is built on the powerful CodeMirror engine, which offers a lightweight, feature‑rich API for syntax highlighting, bracket matching, and refactoring. Users can open a shared workspace, add collaborators, and start writing code together. The AI layer sits beneath the UI, listening to every keystroke, providing real‑time code completions based on a fine‑tuned GPT‑4 architecture, as well as contextual insights into project dependencies.
+
+The architecture is designed to scale horizontally. Microservices such as the "CodeAssist" service, "CollabSync," and "RepoSync" run in separate containers, each exposing a RESTful API. The frontend communicates through a WebSocket channel for low‑latency updates, while the services process requests asynchronously to keep the UI fluid.
+
+The data layer stores all changes in an event‑sourced database, enabling audit trails and replay of entire sessions. Each change is tagged with a unique ID, timestamp, and the user responsible. This approach guarantees that any rollback or conflict resolution is trivial.
+
+The core AI capabilities are integrated via the "CodeAssist" microservice. It leverages a fine‑tuned transformer model trained on millions of lines of open‑source code, and supports multiple languages, including JavaScript, Python, Rust, Go, and TypeScript. The model offers features such as autocomplete, context‑aware refactoring, and automated unit‑test generation. Moreover, it can analyze the entire repository to spot deprecated APIs, suggest migration paths, and produce a compliance report.
+
+The collaboration engine is built on CRDTs (Conflict‑Free Replicated Data Types), ensuring eventual consistency across all clients without locking mechanisms. Users can chat, annotate, and review code inline, all changes instantly visible to the entire team. A sophisticated permission system allows owners to define roles, read/write access, and integrate with existing identity providers like SAML and OAuth2.
+
+Beyond the editor, the platform includes a build pipeline runner that automatically triggers when a merge request is opened. It compiles, runs tests, collects coverage data, and reports metrics to the UI. This feature encourages best practices by providing instant feedback on code quality.
+
+Future roadmap highlights the addition of a visual debugger that can step through TypeScript transpilation, highlight stack traces, and enable live breakpoints. Additionally, the team is exploring a self‑hosted variant that ships as a single Docker image, appealing to enterprises with stricter compliance requirements.
+
+The project is hosted on GitHub under a permissive MIT license. Contributions are welcomed in the form of pull requests for new features, bug fixes, or educational material. A dedicated discussion forum guides developers in onboarding, code best practices, and architectural design. The team maintains a comprehensive documentation portal featuring tutorials, sample projects, and a robust FAQ.
+
+In summary, CoDev‑AI aspires to transform the software development landscape, bridging creativity with artificial intelligence, reducing how developers collaborate, enabling global collaboration across distributed teams seamlessly.

databao_context_engine/project/runs.py

@@ -0,0 +1,39 @@
+from pathlib import Path
+
+from databao_context_engine.project.layout import ProjectLayout, get_output_dir
+from databao_context_engine.storage.connection import open_duckdb_connection
+from databao_context_engine.storage.repositories.factories import create_run_repository
+from databao_context_engine.storage.repositories.run_repository import RunRepository
+from databao_context_engine.system.properties import get_db_path
+
+
+def resolve_run_name(*, project_layout: ProjectLayout, run_name: str | None) -> str:
+    project_id = str(project_layout.read_config_file().project_id)
+
+    with open_duckdb_connection(get_db_path()) as conn:
+        run_repository = create_run_repository(conn)
+
+        return resolve_run_name_from_repo(run_repository=run_repository, project_id=project_id, run_name=run_name)
+
+
+def resolve_run_name_from_repo(*, run_repository: RunRepository, project_id: str, run_name: str | None) -> str:
+    if run_name is None:
+        latest = run_repository.get_latest_run_for_project(project_id=project_id)
+        if latest is None:
+            raise LookupError(f"No runs found for project '{project_id}'. Run a build first.")
+        return latest.run_name
+    else:
+        run = run_repository.get_by_run_name(project_id=project_id, run_name=run_name)
+        if run is None:
+            raise LookupError(f"Run '{run_name}' not found for project '{project_id}'.")
+        return run.run_name
+
+
+def get_run_dir(project_dir: Path, run_name: str) -> Path:
+    run_dir = get_output_dir(project_dir).joinpath(run_name)
+    if not run_dir.is_dir():
+        raise ValueError(
+            f"The run with name {run_name} doesn't exist in the project. [project_dir: {project_dir.resolve()}]"
+        )
+
+    return run_dir