nld-core 0.1.1a1__py3-none-any.whl

nld/business/__init__.py

@@ -0,0 +1,16 @@
+from .dictionary import (
+    BusinessDictionary,
+    NamespacedBusinessDictionary,
+    Term,
+)
+from .lookup import FindMatch, find_by_synonym, find_terms, resolve_term
+
+__all__ = [
+    "BusinessDictionary",
+    "FindMatch",
+    "NamespacedBusinessDictionary",
+    "Term",
+    "find_by_synonym",
+    "find_terms",
+    "resolve_term",
+]

nld/business/dictionary.py

@@ -0,0 +1,37 @@
+from pydantic import Field as PydanticField
+
+from nld.pydantic import NldBaseModel, NldNamedBaseModel, NldNamespacedBaseModelWrapper
+
+
+class Term(NldBaseModel):
+    """A single business term with synonyms, description, and cross-references."""
+
+    name: str = PydanticField(description="Canonical term name")
+    description: str = PydanticField(
+        description="Detailed description of the business meaning",
+    )
+    synonyms: list[str] = PydanticField(
+        default_factory=list,
+        description="Alternative names referring to the same concept",
+    )
+    examples: list[str] = PydanticField(
+        default_factory=list,
+        description="Example usages, e.g. sample column or table names",
+    )
+    related_terms: list[str] = PydanticField(
+        default_factory=list,
+        description="Names of related terms in the dictionary",
+    )
+
+
+class BusinessDictionary(NldNamedBaseModel):
+    """Namespaced business vocabulary used by agents to name tables and fields."""
+
+    terms: dict[str, Term] = PydanticField(
+        default_factory=dict,
+        description="Terms indexed by canonical term name",
+    )
+
+
+class NamespacedBusinessDictionary(NldNamespacedBaseModelWrapper[BusinessDictionary]):
+    """BusinessDictionary wrapped with namespace information."""

nld/business/lookup.py

@@ -0,0 +1,146 @@
+from typing import TYPE_CHECKING, Literal
+
+from nld.pydantic import NldBaseModel, NldNamespace
+
+from .dictionary import BusinessDictionary, Term
+
+if TYPE_CHECKING:
+    from nld.service.nld_entity_registry import NldEntityRegistry
+
+
+BUSINESS_DICTIONARY_ENTITY_TYPE = "business_dictionary"
+
+MatchedOn = Literal["name", "synonym", "related_term"]
+
+
+class FindMatch(NldBaseModel):
+    """A single term match produced by `find_terms`."""
+
+    term: Term
+    matched_on: MatchedOn
+    source_namespace: str
+
+
+def _get_dictionaries_in_hierarchy(
+    registry: "NldEntityRegistry",
+    namespace: str | None,
+) -> list[tuple[NldNamespace, BusinessDictionary]]:
+    """Return `(namespace, dictionary)` pairs along the namespace hierarchy.
+
+    Ordered from deepest (closest to the given namespace) to root so that
+    namespace overrides are consumed before the general dictionary.
+    """
+    target = NldNamespace(namespace) if namespace is not None else NldNamespace(".")
+
+    if BUSINESS_DICTIONARY_ENTITY_TYPE not in registry.entities:
+        return []
+
+    storage = registry.entities[BUSINESS_DICTIONARY_ENTITY_TYPE]
+
+    pairs: list[tuple[NldNamespace, BusinessDictionary]] = []
+    for level_namespace in target.hierarchy:
+        namespace_entries = storage.get(level_namespace, {})
+        for model in namespace_entries.values():
+            if isinstance(model, BusinessDictionary):
+                pairs.append((level_namespace, model))
+
+    pairs.sort(key=lambda item: item[0].depth, reverse=True)
+    return pairs
+
+
+def resolve_term(
+    registry: "NldEntityRegistry",
+    term_name: str,
+    namespace: str | None = None,
+) -> Term | None:
+    """Resolve a term by name, walking the namespace hierarchy upward.
+
+    The closest namespace definition wins; the root dictionary acts as the
+    general fallback.
+    """
+    for _, dictionary in _get_dictionaries_in_hierarchy(
+        registry=registry,
+        namespace=namespace,
+    ):
+        term = dictionary.terms.get(term_name)
+        if term is not None:
+            return term
+    return None
+
+
+def find_by_synonym(
+    registry: "NldEntityRegistry",
+    synonym: str,
+    namespace: str | None = None,
+) -> Term | None:
+    """Find a term by matching one of its synonyms or its canonical name.
+
+    Walks the namespace hierarchy from the given namespace up to root and
+    returns the first match found, so namespace overrides win over general.
+    """
+    normalized = synonym.lower()
+    for _, dictionary in _get_dictionaries_in_hierarchy(
+        registry=registry,
+        namespace=namespace,
+    ):
+        for term in dictionary.terms.values():
+            if term.name.lower() == normalized:
+                return term
+            if any(candidate.lower() == normalized for candidate in term.synonyms):
+                return term
+    return None
+
+
+def find_terms(
+    registry: "NldEntityRegistry",
+    query: str,
+    match_name: bool = True,
+    match_synonym: bool = False,
+    match_related: bool = False,
+    namespace: str | None = None,
+) -> list[FindMatch]:
+    """Search dictionaries in the hierarchy and return every term matching `query`.
+
+    The scope flags control which Term fields participate in the match:
+    canonical `name`, `synonyms`, and/or `related_terms`. Matching is a
+    case-insensitive exact string equality against each enabled field.
+
+    When the same term name appears in multiple namespaces the deepest
+    (most specific) definition wins, preserving the `parents` override
+    semantics used by `resolve_term` and `find_by_synonym`.
+    """
+    normalized = query.lower()
+    seen_names: set[str] = set()
+    results: list[FindMatch] = []
+
+    for source_namespace, dictionary in _get_dictionaries_in_hierarchy(
+        registry=registry,
+        namespace=namespace,
+    ):
+        for term in dictionary.terms.values():
+            if term.name in seen_names:
+                continue
+
+            matched_on: MatchedOn | None = None
+            if match_name and term.name.lower() == normalized:
+                matched_on = "name"
+            elif match_synonym and any(
+                candidate.lower() == normalized for candidate in term.synonyms
+            ):
+                matched_on = "synonym"
+            elif match_related and any(
+                candidate.lower() == normalized for candidate in term.related_terms
+            ):
+                matched_on = "related_term"
+
+            if matched_on is not None:
+                results.append(
+                    FindMatch(
+                        term=term,
+                        matched_on=matched_on,
+                        source_namespace=str(source_namespace),
+                    ),
+                )
+                seen_names.add(term.name)
+
+    return results

nld/business/task/__init__.py

@@ -0,0 +1,5 @@
+from .business_dictionary_find_task import BusinessDictionaryFindTask
+
+__all__ = [
+    "BusinessDictionaryFindTask",
+]

nld/business/task/business_dictionary_find_task.py

@@ -0,0 +1,112 @@
+import json
+import os
+import sys
+from typing import Any
+
+from nld.business import find_terms
+from nld.parameters.execution_params_def import ExecutionParameterDefinition
+from nld.service import FileOutputService
+from nld.task import BaseRunStatus, StandardTask
+from nld.task.context import NldExecutionContext
+
+BUSINESS_DICTIONARY_FIND_FILE_NAME = "business_dictionary_find.json"
+
+
+class BusinessDictionaryFindTask(StandardTask):
+    """Look up business dictionary terms and emit the results as JSON.
+
+    The scope flags (`match_name`, `match_synonym`, `match_related`) control
+    which Term fields participate in the match. At least one scope must be
+    enabled; defaults to name-only matching.
+    """
+
+    init_params = [
+        ExecutionParameterDefinition(name="term", mandatory=True),
+        ExecutionParameterDefinition(name="synonym", mandatory=False, data_type="bool"),
+        ExecutionParameterDefinition(
+            name="related_terms",
+            mandatory=False,
+            data_type="bool",
+        ),
+        ExecutionParameterDefinition(name="namespace", mandatory=False),
+        ExecutionParameterDefinition(
+            name="output",
+            mandatory=False,
+            data_type="bool",
+        ),
+        ExecutionParameterDefinition(
+            name="override_output_folder_path",
+            mandatory=False,
+        ),
+    ]
+    run_params = []
+
+    def __init__(
+        self,
+        term: str,
+        synonym: bool = False,
+        related_terms: bool = False,
+        namespace: str | None = None,
+        output: bool = False,
+        override_output_folder_path: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(**kwargs)
+        self.execution_context = NldExecutionContext.require_current()
+        self.namespace = namespace
+        self.output = output
+        self.override_output_folder_path = override_output_folder_path
+        self.query = term
+        self.scope_name = True
+        self.scope_related = related_terms
+        self.scope_synonym = synonym
+
+    def run(self, **kwargs: Any) -> bool:
+        run_status = BaseRunStatus.SUCCESS.value
+
+        self.execution_context.load_entities()
+        registry = self.execution_context.entity_registry
+
+        matches = find_terms(
+            registry=registry,
+            query=self.query,
+            match_name=self.scope_name,
+            match_synonym=self.scope_synonym,
+            match_related=self.scope_related,
+            namespace=self.namespace,
+        )
+
+        payload = {
+            "query": self.query,
+            "namespace": self.namespace or ".",
+            "scope": {
+                "term": self.scope_name,
+                "synonym": self.scope_synonym,
+                "related_terms": self.scope_related,
+            },
+            "matches": [match.model_dump() for match in matches],
+        }
+
+        if self.output or self.override_output_folder_path is not None:
+            file_output_service = FileOutputService(
+                root_folder_path=self.execution_context.get_nld_root_folder_path(),
+                override_output_folder_path=self.override_output_folder_path,
+            )
+            file_output_service.write_json_file(
+                file_name=BUSINESS_DICTIONARY_FIND_FILE_NAME,
+                data=payload,
+            )
+            output_path = os.path.join(
+                file_output_service.determine_output_folder_path(),
+                BUSINESS_DICTIONARY_FIND_FILE_NAME,
+            )
+            self.log_info(
+                f"Wrote {len(matches)} match(es) to {output_path}",
+            )
+        else:
+            sys.stdout.write(
+                json.dumps(payload, indent=2, ensure_ascii=False) + "\n",
+            )
+            sys.stdout.flush()
+
+        return run_status

nld/cli/business/main_business.py

@@ -0,0 +1,47 @@
+from typing import Any
+
+import click
+
+from nld.business.task import BusinessDictionaryFindTask
+from nld.cli import params, requires_wrapper
+from nld.cli.business import params_business
+from nld.task.task_utils import execute_task
+
+
+@click.group(name="dict", no_args_is_help=True)
+@click.pass_context
+def dictionary(ctx: click.Context, /, **kwargs: Any) -> None:
+    """Business dictionary commands."""
+
+
+@requires_wrapper.nld_command(
+    group=dictionary,
+    command_name="find",
+    with_project=True,
+)
+@params.nld_root_folder_path
+@params_business.term
+@params_business.synonym
+@params_business.related_terms
+@params_business.namespace
+@params_business.output
+@params_business.override_output_folder_path
+def find(ctx: click.Context, **kwargs: Any) -> bool:
+    """Look up business dictionary terms and emit the results as JSON.
+
+    By default the query is matched against each term's canonical name.
+    Add `--synonym` to also match against synonyms, and `--related-terms`
+    to also match against related_terms. The flags compose.
+
+    Examples:
+
+        nld business dict find --term customer
+
+        nld business dict find --term counterparty --synonym --namespace finance
+
+        nld business dict find --term customer --synonym --output
+
+        nld business dict find --term customer --synonym --related-terms \\
+            --override-output-folder-path ./out
+    """
+    return execute_task(BusinessDictionaryFindTask)  # type: ignore[no-any-return]

nld/cli/business/params_business.py

@@ -0,0 +1,54 @@
+import click
+
+term = click.option(
+    "--term",
+    type=str,
+    required=True,
+    help="Query string to look up in the business dictionary.",
+)
+
+synonym = click.option(
+    "--synonym",
+    is_flag=True,
+    default=False,
+    help="Also match the query against each term's synonyms.",
+)
+
+related_terms = click.option(
+    "--related-terms",
+    "related_terms",
+    is_flag=True,
+    default=False,
+    help="Also match the query against each term's related_terms.",
+)
+
+namespace = click.option(
+    "--namespace",
+    type=str,
+    required=False,
+    default=None,
+    help="Namespace to scope the lookup; walks parents up to root.",
+)
+
+output = click.option(
+    "--output",
+    is_flag=True,
+    default=False,
+    help=(
+        "Write the JSON result to a file instead of printing to stdout. "
+        "When set without `--override-output-folder-path`, the file is "
+        "written to a timestamped folder under `output/`."
+    ),
+)
+
+override_output_folder_path = click.option(
+    "--override-output-folder-path",
+    "override_output_folder_path",
+    type=click.Path(file_okay=False, writable=True),
+    required=False,
+    default=None,
+    help=(
+        "Folder to write the JSON result into; implies `--output`. The "
+        "file is named `business_dictionary_find.json`."
+    ),
+)

nld/cli/cli_events.py

@@ -0,0 +1,28 @@
+from nld.logging import ErrorEvent, InfoEvent
+from nld.task import ExecutionInfo
+
+
+class CommandCompleted(InfoEvent):
+    def __init__(self, exec_info: ExecutionInfo):
+        super().__init__()
+        self.exec_info = exec_info
+
+    def code(self) -> str:
+        return "CMD-002"
+
+    def message(self) -> str:
+        return self.exec_info.get_completion_message()
+
+
+class CommandRuntimeError(ErrorEvent):
+    def __init__(self, e: Exception):
+        self.e = e
+
+    def code(self) -> str:
+        return "CMD-091"
+
+    def message(self) -> str:
+        error_message = (
+            str(self.e.message) if hasattr(self.e, "message") else str(self.e)
+        )
+        return f"Runtime Error: {error_message}"

nld/cli/cli_exceptions.py

@@ -0,0 +1,9 @@
+from click.exceptions import ClickException
+
+
+class ExceptionExit(ClickException):
+    """Wraps exceptions without results thrown while invoking nld commands."""
+
+    def __init__(self, exception: Exception) -> None:
+        super().__init__(exception.__str__())
+        self.exception = exception

nld/cli/cli_utils.py

@@ -0,0 +1,24 @@
+from types import ModuleType
+
+import click
+import click.core
+
+from nld.utils.inspect_utils import (
+    extract_functions_from_command_module,
+)
+
+
+def add_commands_from_modules(
+    cli: click.core.Group, command_module: ModuleType, command_prefix: str = ""
+) -> None:
+    commands = extract_functions_from_command_module(
+        command_module, command_prefix, click.core.Command
+    )
+    groups = extract_functions_from_command_module(
+        command_module, command_prefix, click.core.Group
+    )
+
+    for method in commands + groups:
+        if method.name == cli.name:
+            continue
+        cli.add_command(method)

nld/cli/connection/main_connection.py

@@ -0,0 +1,69 @@
+from typing import Any
+
+import click
+
+from nld.cli import params, requires_wrapper
+from nld.cli.connection import params_connection
+from nld.connector.task import (
+    ConnectionDebugTask,
+    ConnectionExportEnvironmentVariablesTask,
+    ConnectionGetStructureTask,
+    ConnectionListTask,
+)
+from nld.task.task_utils import execute_task
+
+
+@requires_wrapper.nld_command("debug")
+@params.specific_connection_params
+def debug(ctx: click.Context, **kwargs: Any) -> bool:
+    """Test the connection availability and status"""
+    return execute_task(ConnectionDebugTask)  # type: ignore[no-any-return]
+
+
+@requires_wrapper.nld_command("export-env-var")
+@params.specific_connection_params
+def export_env_var(ctx: click.Context, **kwargs: Any) -> bool:
+    """
+    Export environment variables for a connection to the parent terminal.
+
+    To load variables into your current shell, use eval:
+
+        eval "$(nld connection export-env-var --connection-name <name>)"
+
+    With a specific profile:
+
+        eval "$(nld connection export-env-var \
+        --connection-name <name> --profile-name <profile>)"
+    """
+    return execute_task(ConnectionExportEnvironmentVariablesTask)  # type: ignore[no-any-return]
+
+
+@requires_wrapper.nld_command("get-structure")
+@params.specific_connection_params
+@params_connection.database
+@params.namespace
+@params_connection.schema
+@params_connection.object_name
+def get_structure(ctx: click.Context, **kwargs: Any) -> bool:
+    """Extract database structure from a connection.
+
+    Extracts metadata about tables, views, columns, primary keys, and
+    unique constraints. Output is in YAML format.
+
+    Examples:
+
+        nld connection get-structure --connection-name my_conn
+
+        nld connection get-structure --connection-name my_conn --schema public
+
+        nld connection get-structure --connection-name my_conn --namespace source.raw
+
+        nld connection get-structure --connection-name my_conn --object users
+    """
+    return execute_task(ConnectionGetStructureTask)  # type: ignore[no-any-return]
+
+
+@requires_wrapper.nld_command("list")
+def list_connections(ctx: click.Context, **kwargs: Any) -> bool:
+    """List all available connections"""
+    return execute_task(ConnectionListTask)  # type: ignore[no-any-return]

nld/cli/connection/params_connection.py

@@ -0,0 +1,25 @@
+import click
+
+database = click.option(
+    "--database",
+    type=str,
+    required=False,
+    default=None,
+    help="Database name (validates against connection, uses connection DB if omitted)",
+)
+
+schema = click.option(
+    "--schema",
+    type=str,
+    required=False,
+    default=None,
+    help="Filter by schema name",
+)
+
+object_name = click.option(
+    "--object",
+    type=str,
+    required=False,
+    default=None,
+    help="Filter by table/view name",
+)