Oxoria API Reference

10 modules · Complete method reference

Modules

cv_api.py — opencv_convert
std_cv_cmd.py — CvProcessAPI
std_menu_cmd.py — StdMenuCmd
canvas_api.py — CanvasAPI
io_api.py — IoAPI
package_api.py — PackageAPI
app_api.py — AppAPI
config_api.py — Config
resources_api.py — ResourcesAPI
search_api.py — SearchAPI

opencv_convert

cv_api.py

A decorator function that bridges PySide6 canvas items and OpenCV-compatible NumPy arrays. It automatically extracts the pixmap from each selected canvas item, converts it to an RGBA NumPy array, passes it to the decorated function as cv_img, and writes the processed result back to the canvas.

decorator @opencv_convert ▼

@opencv_convert def my_func(*args, cv_img: np.ndarray = None) -> np.ndarray: ...

Step	Description
1	Retrieves all selected items via `CanvasAPI().get_selected()`
2	Converts each item's `base_pixmap` to `QImage.Format_RGBA8888`
3	Casts the image data to a `np.ndarray` of shape `(H, W, 4)`
4	Injects it into the decorated function as the `cv_img` keyword argument
5	Converts the returned `np.ndarray` back to `QPixmap`
6	Writes the result back via `CanvasAPI().set_pixmap()`

The decorated function must accept cv_img: np.ndarray = None and must return a np.ndarray of shape (H, W, 4) in RGBA format. The decorator iterates over all selected items independently. No value is returned from the wrapper.

CvProcessAPI

std_cv_cmd.py

Provides a collection of OpenCV-based image processing operations applied to currently selected canvas items. All methods are decorated with @opencv_convert and @classmethod.

classmethod to_blackwhite ▼

cls.to_blackwhite(cv_img: np.ndarray = None) -> np.ndarray

Converts the selected image(s) to grayscale (black & white).

Argument	Description
cv_img	Injected automatically by `@opencv_convert`; do not pass manually

Returns
np.ndarray	RGBA image converted from grayscale

Uses cv2.COLOR_BGRA2GRAY then cv2.COLOR_GRAY2RGBA for round-trip conversion.

classmethod recover_color ▼

cls.recover_color(cv_img: np.ndarray = None) -> np.ndarray

Returns the image unchanged. Intended to restore a previously processed image to its original state.

Returns
np.ndarray	Original RGBA image as-is

This method is a pass-through; actual restoration depends on base_pixmap holding the original data.

classmethod denoise_img ▼

cls.denoise_img(cv_img: np.ndarray = None) -> np.ndarray

Applies colored non-local means denoising to the selected image(s).

Returns
np.ndarray	Denoised RGBA image

Uses cv2.fastNlMeansDenoisingColored with fixed parameters (h=10, hColor=10, templateWindowSize=7, searchWindowSize=21). These are not currently configurable.

classmethod custom_operation ▼

cls.custom_operation(cv2_cmd: str, cv_img: np.ndarray = None) -> np.ndarray

Executes an arbitrary OpenCV expression string and applies the result to the selected image(s).

Argument	Description
cv2_cmd	A Python expression string; has access to `cv2`, `np`, and `cv_img` in its execution context
cv_img	Injected automatically by `@opencv_convert`

Returns
np.ndarray	Result of the evaluated expression

⚠️ Security Warning: This method uses eval() to execute the expression. Only pass trusted, validated strings. Never expose this to untrusted user input, as it can execute arbitrary code.

StdMenuCmd

std_menu_cmd.py

Implements standard menu-bar commands (File menu operations, window management, etc.) for the Oxoria application. Relies on CanvasAPI, ResourcesAPI, and AppAPI internally.

__init__ ▼

__init__(self)

Initializes the command class and instantiates internal API objects.

save_as ▼

save_as(self) -> None

Opens a Save dialog and saves the current canvas to a new .oxoria file chosen by the user.

Requires UI_Var.MAIN_WINDOW to be set. The .oxoria suffix is enforced regardless of the user's input. Delegates the actual write to IoAPI.save_oxoria_file(). Updates GBVar.OPENED_FILE.

save_file ▼

save_file(self) -> None

Saves the current canvas to the already-opened file. Falls back to save_as() if no file is currently open.

open_resource ▼

open_resource(self) -> None

Opens a file picker dialog and loads the chosen file onto the canvas as a resource.

Accepts all file types. Requires UI_Var.MAIN_WINDOW to be set.

new_canvas ▼

new_canvas(self) -> None

Saves the current file and then clears the canvas.

Calls save_file() before clearing, so unsaved work is preserved.

open_oxoria_file ▼

open_oxoria_file(self) -> None

Opens a .oxoria project file selected by the user. If a file is already open, new_canvas() is called first.

Requires UI_Var.MAIN_WINDOW to be set. Delegates the actual read to IoAPI.open_oxoria_file().

export_canvas ▼

export_canvas(self) -> None

Exports the current canvas as an .oxoarchive file (zip-based bundle) to a user-selected path.

Requires UI_Var.MAIN_WINDOW to be set. The .oxoarchive suffix is enforced.

new_window ▼

new_window(self) -> None

Opens a new application window.

quit_app ▼

quit_app(self) -> None

Saves the current file and then quits the application.

force_quit_app ▼

force_quit_app(self) -> None

Quits the application immediately without saving.

⚠️ Any unsaved changes will be lost.

open_api_ref ▼

open_api_ref(self) -> None

Opens this API reference HTML file in the system's default browser.

Resolves the path to _resources/docs/api_reference.html relative to the module location and opens it via QDesktopServices.openUrl().

open_settings ▼

open_settings(self) -> None

Opens the application's Settings dialog.

Delegates to AppAPI.open_settings(), which constructs a SettingsDialog, draws it, and shows it modally.

install_plugin ▼

install_plugin(self) -> None

Opens a folder picker for the user to install a plugin.

Delegates to PackageAPI().install_from_browser(). See PackageAPI for details.

test ▼

test(self) -> None

Prints a test message to stdout. Used for development/debugging.

CanvasAPI

canvas_api.py

Provides the primary interface for canvas state management: managing items on the scene, exporting/importing canvas archives, and view control. Note: low-level .oxoria file save/load has moved to IoAPI.

make_oxoria_file ▼

make_oxoria_file(self) -> dict

Serializes the current canvas scene into a dictionary suitable for JSON export.

Returns
dict	Keys are item pointers; values contain `size_h`, `size_w`, `pos_x`, `pos_y`

Only ImageItem instances are included. Returns early if UI_Var.MAIN_CANVAS is None.

open_resource_on_canvas ▼

open_resource_on_canvas(self, img_path: str | Path) -> None

Opens an image file and places it onto the canvas.

Argument	Description
img_path	Path to the image file

clear_canvas ▼

clear_canvas(self) -> None

Removes all items from the canvas scene and resets GBVar.OPENED_FILE.

⚠️ Destructive operation. Call save_file() before invoking if preservation is needed.

wrap_canvas ▼

wrap_canvas(self, archive_path: str | Path) -> None

Packages the current canvas and its associated image resources into an .oxoarchive file.

Argument	Description
archive_path	Destination path for the archive

Creates a temporary directory temp_export/ under GBVar.DATA_DIR, builds a zip archive, then renames it to .oxoarchive. The temp directory is removed after archiving. Only resources referenced by the current canvas are included.

delete_item ▼

delete_item(self, items_to_delete: list[ImageItem]) -> None

Removes a list of ImageItem instances from the canvas scene.

Argument	Description
items_to_delete	List of items to remove

get_selected ▼

get_selected(self) -> list[ImageItem]

Returns a list of currently selected items on the canvas.

Returns
list[ImageItem]	Currently selected scene items

group_selected ▼

group_selected(self) -> None

Groups all currently selected items into a single QGraphicsItemGroup.

is_anything_selected ▼

is_anything_selected(self) -> bool

Returns whether any item is currently selected on the canvas.

Returns
bool	`True` if at least one item is selected

set_to_origin ▼

set_to_origin(self) -> None

Resets the canvas view transform, centers on the origin, and applies a default zoom scale of 0.15.

set_pixmap ▼

set_pixmap(self, pixmap: QPixmap, image_item: ImageItem) -> None

Replaces the pixmap of an ImageItem on the canvas, updating both base_pixmap and the displayed scaled version.

Argument	Description
pixmap	New `QPixmap` to assign
image_item	The target canvas item

IoAPI

io_api.py

Handles low-level binary serialization of the canvas to/from the native .oxoria file format using QDataStream. Both methods are @staticmethod. Previously part of CanvasAPI.

staticmethod save_oxoria_file ▼

IoAPI.save_oxoria_file(saving_path: str) -> None

Serializes every QGraphicsPixmapItem on the current canvas into a binary .oxoria file.

Argument	Description
saving_path	Absolute or relative path to write the file

Step	Description
1	Writes a 4-byte magic number (`0x4F584F52`) and format version (`1`)
2	Writes the item count as `Int32`
3	For each item: type tag `"pixmap"`, position, scale, rotation, and z-value as `Double`
4	Converts the pixmap to a PNG byte buffer and writes its length + raw bytes

⚠️ Raises IOError if the target path cannot be opened for writing.

staticmethod open_oxoria_file ▼

IoAPI.open_oxoria_file(opening_path: str | Path) -> None

Reads a binary .oxoria file and rebuilds every pixmap item onto the current canvas.

Argument	Description
opening_path	Path to the `.oxoria` file

Step	Description
1	Validates the magic number; raises `ValueError` if it doesn't match `0x4F584F52`
2	Calls `CanvasAPI().clear_canvas()` to wipe the current scene
3	Reads the item count, then reconstructs each `ImageItem` from its stored position, scale, rotation, z-value, and embedded PNG bytes
4	Adds each reconstructed item to `main_canvas.scene()`

⚠️ Raises IOError if the file can't be opened for reading, and ValueError on an invalid/corrupt header. Unlike the old CanvasAPI-based loader, this always clears the canvas first via CanvasAPI().clear_canvas(), regardless of the current resource profile.

PackageAPI

package_api.py

Manages third-party plugins: installing them into the app's plugin directory and dynamically loading/executing their entry point.

__init__ ▼

__init__(self)

Resolves the plugin root directory to <GBVar.DATA_DIR>/plugins.

launch_plugin ▼

launch_plugin(self, plugin_name: str) -> None

Dynamically imports and executes a plugin's __oxoplugin__.py entry point from the plugin directory.

Argument	Description
plugin_name	Folder name of the plugin under `plugins/`

Uses importlib.util.spec_from_file_location to load __oxoplugin__.py and registers it in sys.modules. Writes an error to the console (via OxoriaConsole) instead of raising if the plugin folder or entry point is missing.

install_plugin ▼

install_plugin(self, plugin_folder: str, plugin_name: str, make_copy: bool = True, force: bool = False) -> None

Copies or moves a plugin folder into the app's plugin directory.

Argument	Description
plugin_folder	Source folder containing the plugin
plugin_name	Destination folder name under `plugins/`
make_copy	If `True`, copies the folder (`shutil.copytree`); if `False`, moves it (`shutil.move`) (default: `True`)
force	If `True`, overwrites an existing plugin folder with the same name (default: `False`)

Writes an error to the console if the source folder doesn't exist, or if the destination already exists and force is False.

install_from_browser ▼

install_from_browser(self) -> None

Opens a folder picker dialog so the user can select a plugin folder to install, then delegates to install_plugin().

The plugin's destination name is taken from the selected folder's basename. Uses default make_copy=True, force=False. Does nothing if the dialog is cancelled.

AppAPI

app_api.py

Handles application-level operations such as launching subprocesses and managing the application lifecycle.

run_capture_monitor ▼

run_capture_monitor(self) -> None

Launches the screen capture monitor as a background process, if not already running.

Checks running processes via psutil before launching to prevent duplicate instances. The monitor script path is resolved relative to the module's location.

open_new_window ▼

open_new_window(self) -> None

Opens a new Oxoria application window as an independent subprocess.

Resolves and launches __main__.py in the application root directory. Prints an error to stdout if the entry script is not found.

quit_app ▼

quit_app(self) -> None

Quits the main Qt application.

Calls GBVar.MAIN_APP.quit(). Does nothing if MAIN_APP is None.

get_command_stack ▼

get_command_stack(self, output_length: int = -1) -> list[str]

Retrieves a slice of the global command execution history stack.

Argument	Description
output_length	Number of commands to return from the end of the stack. Pass `-1` (default) to return the entire stack; pass a positive integer to return only the last N commands

Returns
list[str]	List of command strings; empty list if the command stack is empty or output_length is invalid

If output_length exceeds the actual stack size, the entire stack is returned. The stack is accessed via GBVar.COMMAND_STACK.

mycommand ▼

mycommand(self, cmd: str, shortcut_alphabet: str) -> None

Registers a custom shortcut by storing a command string mapped to a shortcut alphabet key.

Argument	Description
cmd	The command string to execute when the shortcut is triggered
shortcut_alphabet	A single character or key name to use as the shortcut trigger

Reads config/app_config.json, updates the "mycommand" section with the new shortcut mapping, and writes the updated config back to disk. Creates the "mycommand" dictionary if it does not exist.

get_mycommand ▼

get_mycommand(self, shortcut_alphabet: str) -> str

Retrieves the command string associated with a registered custom shortcut.

Argument	Description
shortcut_alphabet	The shortcut key to look up

Returns
str	The command string for the given shortcut; empty string `""` if the shortcut does not exist or the `"mycommand"` section is not found

Reads from config/app_config.json. Returns an empty string rather than raising an error if the shortcut is not found.

get_data_dir ▼

get_data_dir(self) -> str

Returns the absolute path to the application data directory.

Returns
str	Path to the data directory, typically containing `resources_lib/`, `profiles/`, and other application data

Reads from GBVar.DATA_DIR. This is a convenience accessor for the global data directory.

get_app_folder_dir ▼

get_app_folder_dir(self) -> str

Returns the absolute path to the parent directory of the data directory (the root application folder).

Returns
str	Path to the application root folder, one level above the data directory

Resolves the data directory, then returns its parent using Path.resolve().parent. Useful for locating configuration files and other app-level resources.

get_gbvar ▼

get_gbvar(self) -> GBVar

Returns a reference to the global GBVar class object.

Returns
GBVar	The `GBVar` class itself, providing access to all global application variables

This is a convenience accessor for obtaining the global variables class. Use this to access module-level config like MAIN_APP, COMMAND_STACK, DATA_DIR, etc.

make_menu_item ▼

make_menu_item(self, new_items: dict) -> None

Registers new entries into the application's menu bar configuration, merging them into editor_config.json.

Argument	Description
new_items	Nested dict of the form `{menu_key: {item_key: item_value, ...}, ...}` to merge into the existing `"menu_bar"` section

Reads config/editor_config.json, merges new_items two levels deep into the existing "menu_bar" dict (creating menu keys that don't already exist), and writes the file back. Existing item keys under a matching menu key are overwritten.

oxoprint ▼

oxoprint(self, msg: str) -> None

Writes a message to the in-app Oxoria console.

Argument	Description
msg	Text to display in the console

Thin wrapper around OxoriaConsole.write_console(). Useful for plugins and custom commands to surface output to the user.

Config (AppConfigAPI / EditorConfigAPI / UseConfigData)

config_api.py

Defines the app's two configuration dataclasses (AppConfigAPI, EditorConfigAPI) backed by JSON files under config/, plus UseConfigData, a cached accessor layer, and the ConfigType enum used to select which config to target.

enum ConfigType ▼

class ConfigType(StrEnum): APP = "app" EDITOR = "editor"

String enum identifying which configuration sector to read/write.

Member	Value	Description
APP	`"app"`	Targets `AppConfigAPI` / `app_config.json`
EDITOR	`"editor"`	Targets `EditorConfigAPI` / `editor_config.json`

dataclass AppConfigAPI ▼

@dataclasses.dataclass class AppConfigAPI: ...

Dataclass holding application-level settings, persisted to config/app_config.json under the "app" key.

Field	Type	Default	Description
semantic_search_length	int	`2`	Default number of results for semantic search
semantic_search_cutoff	float	`0.65`	Default similarity cutoff for semantic search
distance_search_length	int	`1`	Default number of results for fuzzy/distance search
distance_search_cutoff	float	`0.5`	Default similarity cutoff for fuzzy/distance search
command_stack_length	int	`15`	Maximum size of the command history stack
ide_executable_path	str	`""`	Path to an external IDE executable, if configured

Method	Description
`init_config()` classmethod	Loads `config/app_config.json`, extracts the `"app"` key, and returns a new `AppConfigAPI` instance built from it
`set_config(attr, new_value)` classmethod	Sets `attr` on the class, then updates and rewrites the `"app"` section of `app_config.json` with the new value

These field defaults mirror the semantic/distance search defaults used in SearchAPI; note that SearchAPI's methods do not currently read from this config automatically — the values must be passed in explicitly.

dataclass EditorConfigAPI ▼

@dataclasses.dataclass class EditorConfigAPI: ...

Dataclass holding canvas/editor appearance and behavior settings, persisted to config/editor_config.json under the "editor" key.

Field	Type	Default	Description
handle_size	int	`40`	Size of item resize/rotate handles
handle_color	str	`"#4A90D9"`	Fill color of item handles
handle_outline_thickness	float	`1.5`	Outline stroke width of item handles
handle_outline_color	str	`"#FFFFFF"`	Outline color of item handles
min_item_size	int	`40`	Minimum allowed size (px) for a resizable item
canvas_height	int	`800`	Default canvas height
sidebar_default	int	`200`	Default sidebar width
sidebar_min	int	`200`	Minimum sidebar width
sidebar_standby	int	`300`	Sidebar width in standby/collapsed-adjacent state
sidebar_max	int	`700`	Maximum sidebar width
is_draw_ruled_lines	bool	`True`	Whether ruled grid lines are drawn on the canvas
ruled_line_interval	int	`100`	Spacing (px) between ruled lines
ruled_line_thin_thickness	float	`1.0`	Stroke width of minor ruled lines
ruled_line_thick_thickness	float	`1.5`	Stroke width of major ruled lines
ruled_line_thich_color	str	`"#505050"`	Color of major ruled lines (note: field name is spelled "thich", not "thick")
ruled_line_thin_color	str	`"#3C3C3C"`	Color of minor ruled lines
scaling_step	float	`0.1`	Increment used when scaling items via keyboard/shortcut
canvas_bg_color	str	`"#1E1E1E"`	Canvas background color
image_item_frame_color	str	`"#4A90D9"`	Border color drawn around selected image items
image_item_frame_thickness	float	`4.0`	Border stroke width around selected image items
memo_paper_color	str	`"#FFFDF0"`	Background color of memo notes
memo_text_color	str	`"#333333"`	Text color of memo notes
memo_text_font_size	int	`180`	Font size of memo note text
memo_text_font	str	`"Yu Gothic"`	Font family of memo note text
memo_text_margin	int	`20`	Inner padding of memo notes
command_line_text_color	str	`"#FFFFFF"`	Text color of the command line widget
command_line_bg_color	str	`"#303030"`	Background color of the command line widget
splitter_handle_width	int	`10`	Width of draggable splitter handles

Method	Description
`init_config()` classmethod	Loads `config/editor_config.json`, extracts the `"editor"` key, and returns a new `EditorConfigAPI` instance built from it
`set_config(attr, new_value)` classmethod	Sets `attr` on the class, then updates and rewrites the `"editor"` section of `editor_config.json` with the new value

UseConfigData ▼

UseConfigData.app_config() -> AppConfigAPI UseConfigData.editor_config() -> EditorConfigAPI UseConfigData.set_config(sector: ConfigType, attr_name: str, new_value: Any) -> None

Cached accessor layer sitting in front of AppConfigAPI / EditorConfigAPI, so config files are only read from disk once per session.

Method	Description
`app_config()` classmethod	Returns the cached `AppConfigAPI` instance, lazily calling `AppConfigAPI.init_config()` on first access
`editor_config()` classmethod	Returns the cached `EditorConfigAPI` instance, lazily calling `EditorConfigAPI.init_config()` on first access
`set_config(sector, attr_name, new_value)` classmethod	Dispatches to `AppConfigAPI.set_config()` or `EditorConfigAPI.set_config()` based on `sector` (a `ConfigType`); does nothing (returns `None`) for an unrecognized sector

Once _app_config_instance / _editor_config_instance is cached, subsequent calls to app_config() / editor_config() do not re-read the JSON file — only set_config() writes changes back to disk.

ResourcesAPI

resources_api.py

Manages the local image resource library: importing, profiling, tagging, and searching image assets identified by perceptual hash pointers.

__init__ ▼

__init__(self, data_path: str | None = None)

Argument	Description
data_path	Override for the data directory; defaults to `GBVar.DATA_DIR`

On macOS (Darwin), sets OMP_NUM_THREADS=1 to avoid OpenMP conflicts.

clone_resource_to_repo ▼

clone_resource_to_repo(self, original_path: str, new_path: str) -> None

Copies an image file into the local resource library directory.

Argument	Description
original_path	Source file path
new_path	Destination filename (relative to `resources_lib/`)

Skips the copy if the destination already exists.

check_exists ▼

check_exists(self, img_hash: str | None, img_path: str | None, tolerance: float = 0) -> tuple[str | None, bool | None]

Checks whether an image (by hash or path) already exists in the resource library.

Argument	Description
img_hash	Precomputed hash; if `None`, computed from `img_path`
img_path	Image file path; used to compute hash if `img_hash` is `None`
tolerance	Similarity tolerance for fuzzy matching; `0` = exact match (default: `0`)

Returns
tuple	`(hash_value, exists_flag)`; both `None` if neither argument is provided

get_resources_profile ▼

get_resources_profile(self) -> dict

Returns the full resource profile dictionary from resources_profile.json.

Returns
dict	All resource entries; empty dict if the profile file does not exist

make_resource_profile ▼

make_resource_profile(self, img_path: str, name: str = None, memo: str = None, tags: list[str] = None, make_clone_path: bool = True) -> dict

Constructs a profile dictionary for a new resource (does not write to disk).

Argument	Description
img_path	Path to the image
name	Display name; defaults to the filename stem
memo	Free-text memo; defaults to `""`
tags	List of tag strings; defaults to `[]`
make_clone_path	If `True`, stores only the filename (not the full path) in the profile (default: `True`)

Returns
dict	Profile with keys `path`, `name`, `memo`, `tags`

write_resource_profile ▼

write_resource_profile(self, pointer: str, profile: dict, merge: bool = False) -> bool

Writes or updates a single resource entry in resources_profile.json.

Argument	Description
pointer	Unique hash identifier for the resource
profile	Profile data; must contain a `"path"` key
merge	If `True`, merges with the existing profile instead of replacing (default: `False`)

Returns
bool	`True` on success; `False` if `"path"` is missing from `profile`

import_resource ▼

import_resource(self, img_hash: str | None, img_path: str | None, profile: dict, skip_existencce_check: bool = True, tolerance: float = 0, make_clone: bool = True) -> bool

Imports an image into the resource library: adds its hash, writes its profile, and optionally copies the file.

Argument	Description
img_hash	Precomputed hash; computed from `img_path` if `None`
img_path	Source image path
profile	Resource profile dictionary
skip_existencce_check	If `True`, skips duplicate detection (default: `True`)
tolerance	Hash similarity tolerance for duplicate check (default: `0`)
make_clone	If `True`, copies the file into the repository (default: `True`)

Returns
bool	`True` on success; `False` if the resource already exists (when check is enabled) or if both hash and path are `None`

Note: The parameter name skip_existencce_check contains a typo (existencce). Use it as-is in your code.

pointer_to_path ▼

pointer_to_path(self, pointer: str) -> str | None

Resolves a resource pointer (hash) to its absolute file path.

Returns
str \| None	Absolute path string, or `None` if not found

path_to_pointer ▼

path_to_pointer(self, path: str) -> str | None

Finds the resource pointer associated with a stored relative path.

Returns
str \| None	Pointer string, or `None` if not found

name_to_path ▼

name_to_path(self, name: str) -> str | None

Looks up the relative path for a resource by its display name.

Returns
str \| None	Relative path string, or `None` if not found

filter_pointer_with_tag ▼

filter_pointer_with_tag(self, tag: str) -> list[str]

Returns all resource pointers that have the specified tag.

Returns
list[str]	List of matching pointer strings

filter_pointer_with_category ▼

filter_pointer_with_category(self, category: str) -> list[str]

Returns all resource pointers matching the specified category.

Returns
list[str]	List of matching pointer strings

filter_pointer_with_memo ▼

filter_pointer_with_memo(self, kw: str)

⚠️ Not implemented: Method body is pass. Not yet available.

edit_memo ▼

edit_memo(self, pointer: str, memo_text: str) -> None

Updates the memo field of a resource profile in place.

Argument	Description
pointer	Resource hash
memo_text	New memo content

edit_tags ▼

edit_tags(self, pointer: str, tags: list[str], mode: str = "append") -> None

Appends or removes tags from a resource's profile.

Argument	Description
pointer	Resource hash
tags	Tags to add or remove
mode	`"append"` adds new tags (deduplicates); `"remove"` removes specified tags (default: `"append"`)

Silently returns if pointer is not in the current profile or if mode is unrecognized.

SearchAPI

search_api.py

Provides both semantic (vector-based) and fuzzy string-based search over the resource library's keywords and names.

__init__ ▼

__init__(self)

Initializes UseVector, SearchBase, and FaissIndexBase internally.

append_search_base ▼

append_search_base(self, kw: str) -> None

Adds a keyword to the FAISS vector index and the in-memory search base.

Argument	Description
kw	Keyword string to index

semantic_search_kw ▼

semantic_search_kw(self, kw: str, return_num: int = 3, cutoff: float = 0.65) -> list[str]

Searches for the most semantically similar keywords to the query using the FAISS index.

Argument	Description
kw	Query keyword
return_num	Maximum number of results to return (default: `3`)
cutoff	Minimum similarity score required for a result to be included (default: `0.65`) — newly exposed as an argument; previously hardcoded

Returns
list[str]	List of matching keyword strings; may be shorter than `return_num` if the search base is small or the cutoff excludes matches

Results below the given cutoff are excluded.

semantic_search_kw_to_pointer ▼

semantic_search_kw_to_pointer(self, kw: str, return_num: int = 3, cutoff: float = 0.65) -> list[str]

Performs semantic search and maps the results back to resource pointers.

Argument	Description
kw	Query keyword
return_num	Number of results to return (default: `3`)
cutoff	Minimum similarity score passed through to `semantic_search_kw()` (default: `0.65`)

Returns
list[str \| None]	List of length `return_num`; positions without a matching pointer contain `None`

Matches are made by comparing search results against the "memo" field of each resource profile.

distance_search_kw ▼

distance_search_kw(self, kw: str, return_num: int = 3, cutoff: float = 0.5) -> list[str]

Searches for resources by fuzzy string matching on display names using difflib.

Argument	Description
kw	Query string
return_num	Maximum number of results (default: `3`)
cutoff	Minimum similarity score `[0.0, 1.0]`; results below this are discarded (default: `0.5`)

Returns
list[str]	List of resource pointer strings matching the name query

Fixed: the cutoff argument is now correctly forwarded to difflib.get_close_matches(). (Previously this was hardcoded to 0.5 internally and the passed value was ignored — that bug has been resolved.)