niamoto.gui.api package

Subpackages

Submodules

niamoto.gui.api.app module

niamoto.gui.api.context module

Shared context for GUI API endpoints.

This module provides utilities to access the Niamoto working directory and database path in a consistent way across all API endpoints.

class niamoto.gui.api.context.DesktopProjectReloadResult(state, project_path, message=None)

Bases: object

Result of reloading the desktop project from the Tauri config.

Parameters:

  • state (Literal['loaded', 'welcome', 'invalid-project'])

  • project_path (Path | None)

  • message (str | None)

state: Literal['loaded', 'welcome', 'invalid-project']
project_path: Path | None
message: str | None = None
niamoto.gui.api.context.set_working_directory(path)

Set the working directory for the GUI session.

This should be called once when the GUI starts, from the CLI command.

Parameters:

path (Path) – Path to the Niamoto project directory

Return type:

None

niamoto.gui.api.context.get_working_directory()

Get the current working directory for the GUI.

Determines the working directory in the following order: 1. Directory set via set_working_directory() (when launched via ‘niamoto gui’) 2. NIAMOTO_HOME environment variable (for development mode) 3. Current working directory (fallback)

Returns:

Path to the Niamoto project directory

Return type:

Path

niamoto.gui.api.context.get_optional_working_directory()

Return the explicit GUI working directory when one is configured.

Desktop startup can legitimately begin without any selected project. In that case, returning None lets the API stay in welcome mode instead of implicitly treating the process cwd as a project root.

Return type:

Path | None

niamoto.gui.api.context.get_database_path()

Return the analytics database path (DuckDB by default).

Search order: 1. Path specified in config/config.yml (defaults to db/niamoto.duckdb) 2. db/niamoto.duckdb 3. niamoto.duckdb 4. data/niamoto.duckdb 5. Legacy SQLite fallbacks (db/niamoto.db, niamoto.db, data/niamoto.db)

Return type:

Path | None

niamoto.gui.api.context.get_config_path(config_file)

Get path to a configuration file.

Parameters:

config_file (str) – Name of the config file (e.g., “transform.yml” or “config/transform.yml”)

Returns:

Path to the configuration file

Return type:

Path

niamoto.gui.api.context.reload_project_from_desktop_config()

Reload the current project from the desktop shell config.

This reads the shared desktop config file written by the active shell to get the current project and updates the global working directory.

Returns:

A structured result describing the resulting desktop state.

Return type:

DesktopProjectReloadResult

niamoto.gui.api.models module

API models package.

Re-exports general API models and templates-specific models.

class niamoto.gui.api.models.ConfigSection

Bases: BaseModel

Base model for configuration sections.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class niamoto.gui.api.models.ImportConfig(*, taxonomy=None, occurrences=None, plots=None, shapes=None)

Bases: ConfigSection

Import configuration model.

Parameters:

  • taxonomy (Dict[str, Any] | None)

  • occurrences (Dict[str, Any] | None)

  • plots (Dict[str, Any] | None)

  • shapes (List[Dict[str, Any]] | None)

taxonomy: Dict[str, Any] | None
occurrences: Dict[str, Any] | None
plots: Dict[str, Any] | None
shapes: List[Dict[str, Any]] | None
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class niamoto.gui.api.models.TransformConfig

Bases: ConfigSection

Transform configuration model.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class niamoto.gui.api.models.ExportConfig(*, site=None, exports=None)

Bases: ConfigSection

Export configuration model.

Parameters:

  • site (Dict[str, str] | None)

  • exports (List[Dict[str, Any]] | None)

site: Dict[str, str] | None
exports: List[Dict[str, Any]] | None
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class niamoto.gui.api.models.NiamotoConfig(*, import_config, transform=None, export=None)

Bases: BaseModel

Complete Niamoto configuration.

Parameters:
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

import_config: ImportConfig
transform: Dict[str, Any] | None
export: ExportConfig | None
class niamoto.gui.api.models.ValidationResponse(*, valid, message=None, errors=None)

Bases: BaseModel

Response model for validation endpoint.

Parameters:

  • valid (bool)

  • message (str | None)

  • errors (List[str] | None)

valid: bool
message: str | None
errors: List[str] | None
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class niamoto.gui.api.models.GenerateResponse(*, import_yaml, transform_yaml, export_yaml)

Bases: BaseModel

Response model for YAML generation.

Parameters:

  • import_yaml (str)

  • transform_yaml (str)

  • export_yaml (str)

import_yaml: str
transform_yaml: str
export_yaml: str
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class niamoto.gui.api.models.TemplateInfo(*, id, name, description, plugin, category, icon, is_recommended, has_auto_detect)

Bases: BaseModel

Basic template information.

Parameters:

  • id (str)

  • name (str)

  • description (str)

  • plugin (str)

  • category (str)

  • icon (str)

  • is_recommended (bool)

  • has_auto_detect (bool)

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

id: str
name: str
description: str
plugin: str
category: str
icon: str
has_auto_detect: bool
class niamoto.gui.api.models.TemplateSuggestionResponse(*, template_id, name, description, plugin, category, icon, confidence, source, source_name, matched_column=None, match_reason=None, is_recommended, config, widget_plugin=None, widget_params=None, alternatives=[])

Bases: BaseModel

A template suggestion with confidence.

Parameters:

  • template_id (str)

  • name (str)

  • description (str)

  • plugin (str)

  • category (str)

  • icon (str)

  • confidence (float)

  • source (str)

  • source_name (str)

  • matched_column (str | None)

  • match_reason (str | None)

  • is_recommended (bool)

  • config (Dict[str, Any])

  • widget_plugin (str | None)

  • widget_params (Dict[str, Any] | None)

  • alternatives (List[str])

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

template_id: str
name: str
description: str
plugin: str
category: str
icon: str
confidence: float
source: str
source_name: str
matched_column: str | None
match_reason: str | None
config: Dict[str, Any]
widget_plugin: str | None
widget_params: Dict[str, Any] | None
alternatives: List[str]
class niamoto.gui.api.models.TemplatesListResponse(*, templates, categories, total)

Bases: BaseModel

Response for listing templates.

Parameters:

  • templates (List[TemplateInfo])

  • categories (List[str])

  • total (int)

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

templates: List[TemplateInfo]
categories: List[str]
total: int
class niamoto.gui.api.models.SuggestionsResponse(*, suggestions, entity_type, columns_analyzed, total_suggestions)

Bases: BaseModel

Response for template suggestions.

Parameters:
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

suggestions: List[TemplateSuggestionResponse]
entity_type: str
columns_analyzed: int
total_suggestions: int
class niamoto.gui.api.models.SelectedTemplate(*, template_id, plugin, config={}, widget_plugin=None, widget_params=None)

Bases: BaseModel

A selected template with its configuration.

Parameters:

  • template_id (str)

  • plugin (str)

  • config (Dict[str, Any])

  • widget_plugin (str | None)

  • widget_params (Dict[str, Any] | None)

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

template_id: str
plugin: str
config: Dict[str, Any]
widget_plugin: str | None
widget_params: Dict[str, Any] | None
class niamoto.gui.api.models.GenerateConfigRequest(*, templates, group_by, reference_kind='generic')

Bases: BaseModel

Request to generate transform config.

Parameters:
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

templates: List[SelectedTemplate]
group_by: str
reference_kind: str
class niamoto.gui.api.models.GenerateConfigResponse(*, group_by, sources, widgets_data)

Bases: BaseModel

Response with generated config.

Parameters:

  • group_by (str)

  • sources (List[Dict[str, Any]])

  • widgets_data (Dict[str, Any])

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

group_by: str
sources: List[Dict[str, Any]]
widgets_data: Dict[str, Any]
class niamoto.gui.api.models.SaveConfigRequest(*, group_by, sources, widgets_data, mode='replace')

Bases: BaseModel

Request to save generated config to transform.yml.

Parameters:

  • group_by (str)

  • sources (List[Dict[str, Any]])

  • widgets_data (Dict[str, Any])

  • mode (Literal['merge', 'replace'])

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

group_by: str
sources: List[Dict[str, Any]]
widgets_data: Dict[str, Any]
mode: Literal['merge', 'replace']
class niamoto.gui.api.models.SaveConfigResponse(*, success, message, file_path, widgets_added, widgets_updated)

Bases: BaseModel

Response after saving config.

Parameters:

  • success (bool)

  • message (str)

  • file_path (str)

  • widgets_added (int)

  • widgets_updated (int)

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

success: bool
message: str
file_path: str
widgets_added: int
widgets_updated: int
class niamoto.gui.api.models.ClassObjectSuggestion(*, name, category, cardinality, class_names, value_type, suggested_plugin, confidence, auto_config, mapping_hints, related_class_objects, pattern_group)

Bases: BaseModel

A single class_object with its analysis and suggested configuration.

Parameters:

  • name (str)

  • category (str)

  • cardinality (int)

  • class_names (List[str])

  • value_type (str)

  • suggested_plugin (str)

  • confidence (float)

  • auto_config (Dict[str, Any])

  • mapping_hints (Dict[str, str])

  • related_class_objects (List[str])

  • pattern_group (str | None)

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str
category: str
cardinality: int
class_names: List[str]
value_type: str
suggested_plugin: str
confidence: float
auto_config: Dict[str, Any]
mapping_hints: Dict[str, str]
related_class_objects: List[str]
pattern_group: str | None
class niamoto.gui.api.models.WidgetTemplate(*, name, description, plugin, complexity, example_config, applicable_categories, variables=[])

Bases: BaseModel

A predefined widget template for complex configurations.

Parameters:

  • name (str)

  • description (str)

  • plugin (str)

  • complexity (str)

  • example_config (Dict[str, Any])

  • applicable_categories (List[str])

  • variables (List[Dict[str, str]])

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str
description: str
plugin: str
complexity: str
example_config: Dict[str, Any]
applicable_categories: List[str]
variables: List[Dict[str, str]]
class niamoto.gui.api.models.PluginParameter(*, name, type, label, filter_category, required=True, min_items=None)

Bases: BaseModel

A parameter definition for a plugin wizard.

Parameters:

  • name (str)

  • type (str)

  • label (str)

  • filter_category (Any)

  • required (bool)

  • min_items (int | None)

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str
type: str
label: str
filter_category: Any
required: bool
min_items: int | None
class niamoto.gui.api.models.PluginSchema(*, name, description, complexity, applicable_categories, parameters)

Bases: BaseModel

Schema describing a plugin’s parameters for wizard UI.

Parameters:

  • name (str)

  • description (str)

  • complexity (str)

  • applicable_categories (List[str])

  • parameters (List[PluginParameter])

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str
description: str
complexity: str
applicable_categories: List[str]
parameters: List[PluginParameter]
class niamoto.gui.api.models.WidgetSuggestionsResponse(*, source_name, source_path, class_objects, pattern_groups, plugin_schemas, categories_summary)

Bases: BaseModel

Response for class_object-based widget suggestions.

Parameters:

  • source_name (str)

  • source_path (str)

  • class_objects (List[ClassObjectSuggestion])

  • pattern_groups (Dict[str, List[str]])

  • plugin_schemas (Dict[str, PluginSchema])

  • categories_summary (Dict[str, int])

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

source_name: str
source_path: str
class_objects: List[ClassObjectSuggestion]
pattern_groups: Dict[str, List[str]]
plugin_schemas: Dict[str, PluginSchema]
categories_summary: Dict[str, int]
class niamoto.gui.api.models.CombinedWidgetRequest(*, selected_fields, source_name='occurrences')

Bases: BaseModel

Request for combined widget suggestions based on selected fields.

Parameters:

  • selected_fields (List[str])

  • source_name (str)

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

selected_fields: List[str]
source_name: str
class niamoto.gui.api.models.CombinedWidgetSuggestion(*, pattern_type, name, description, fields, field_roles, confidence, is_recommended, transformer_config, widget_config)

Bases: BaseModel

A suggested combined widget configuration.

Parameters:

  • pattern_type (str)

  • name (str)

  • description (str)

  • fields (List[str])

  • field_roles (Dict[str, str])

  • confidence (float)

  • is_recommended (bool)

  • transformer_config (Dict[str, Any])

  • widget_config (Dict[str, Any])

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pattern_type: str
name: str
description: str
fields: List[str]
field_roles: Dict[str, str]
confidence: float
transformer_config: Dict[str, Any]
widget_config: Dict[str, Any]
class niamoto.gui.api.models.CombinedWidgetResponse(*, suggestions, semantic_groups)

Bases: BaseModel

Response with combined widget suggestions.

Parameters:
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

suggestions: List[CombinedWidgetSuggestion]
semantic_groups: List[Dict[str, Any]]
class niamoto.gui.api.models.SemanticGroupsResponse(*, groups)

Bases: BaseModel

Response with detected semantic groups for proactive suggestions.

Parameters:

groups (List[Dict[str, Any]])

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

groups: List[Dict[str, Any]]
class niamoto.gui.api.models.InlinePreviewRequest(*, group_by, transformer_plugin, transformer_params={}, widget_plugin, widget_params=None, widget_title='Preview')

Bases: BaseModel

Request for generating an inline widget preview (POST).

Parameters:

  • group_by (str)

  • transformer_plugin (str)

  • transformer_params (Dict[str, Any])

  • widget_plugin (str)

  • widget_params (Dict[str, Any] | None)

  • widget_title (str)

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

group_by: str
transformer_plugin: str
transformer_params: Dict[str, Any]
widget_plugin: str
widget_params: Dict[str, Any] | None
widget_title: str

Module contents

API module for Niamoto GUI.