ahvn.ukf.templates.basic.resource module

class ahvn.ukf.templates.basic.resource.ResourceUKFT(*, name, notes='', short_description='', description='', type='general', version='v0.1.0', version_notes='', variant='default', variant_notes='', content='', content_resources=<factory>, content_composers=<factory>, source='unknown', parents=<factory>, creator='unknown', owner='unknown', workspace='unknown', collection='general', tags=<factory>, synonyms=<factory>, triggers=<factory>, priority=0, related=<factory>, auths=<factory>, timefluid=False, timestamp=<factory>, last_verified=<factory>, expiration=-1, inactive_mark=False, metadata=<factory>, profile=<factory>)[source]

Bases: BaseUKF

Resource class for storing file/folder contents as base64 encoded data.

UKF Type: resource Recommended Components of content_resources:

  • path (str): The original file/directory path.

  • data (Dict[str, Optional[str]]): Serialized file/directory structure from serialize_path.

  • annotations (Dict[str, str]): File-level annotations for context.

Recommended Composers:
diagram:

Examples: ``` project/ ├── README.md ├── src/ │ ├── main.py │ └── utils.py └── tests/

└── test_main.py # Unit tests for main functionality

```

Parameters:
type_default: ClassVar[str] = 'resource'
classmethod from_path(path, name=None, keep_path=True, **updates)[source]

Create a ResourceUKFT instance from a file or directory path.

Serializes the file or directory contents using serialize_path and automatically configures the resource with appropriate metadata and composers. Only stores essential information (file names and paths) without redundant metadata.

Parameters:

  • path (str) – Path to the file or directory to serialize.

  • name (str, optional) – ResourceUKFT name. If None and path is a directory, generates name from the basename of the path. Required if path is a file.

  • keep_path (bool) – Whether to keep the original path in content_resources. Defaults to True.

  • **updates – Additional keyword arguments to update the ResourceUKFT instance attributes.

Returns:

New ResourceUKFT instance with pre-configured composers:

  • diagram: diagram_composer for LLM-friendly folder structure diagram

Return type:

ResourceUKFT

Example

>>> resource = ResourceUKFT.from_path("/path/to/project")
>>> resource.name
"project"
>>> resource.text("diagram")
'''            project/
├── file1.py
└── src/
    └── main.py
'''
classmethod from_data(data, name=None, path=None, **updates)[source]

Create a ResourceUKFT instance from serialized data.

Allows creating a ResourceUKFT from pre-serialized data without requiring the original file/directory to exist.

Parameters:

  • data (Dict[str, Any]) – Serialized file/directory structure from serialize_path.

  • name (str, optional) – ResourceUKFT name. If None, generates from path or uses “resource”.

  • path (str, optional) – Original path for reference. Used in diagram generation.

  • **updates – Additional keyword arguments to update the ResourceUKFT instance attributes.

Returns:

New ResourceUKFT instance with pre-configured composers.

Return type:

ResourceUKFT

Example

>>> data = {"file.txt": "base64content", "folder/": None}
>>> resource = ResourceUKFT.from_data(data, name="my_resource")
>>> resource.name
"my_resource"
annotate(file_path, annotation)[source]

Add an annotation to a specific file in the resource.

Allows adding contextual information about files that will appear in the diagram tree, making it more useful for LLM consumption.

Parameters:

  • file_path (str) – Relative path to the file within the resource.

  • annotation (str) – Annotation text to display after the file name.

Returns:

A new ResourceUKFT instance with the annotation added.

Return type:

ResourceUKFT

Example

>>> resource = ResourceUKFT.from_path("/path/to/project")
>>> annotated = resource.annotate("src/main.py", "Main entry point")
>>> annotated.text("diagram")
'''            project/
└── src/
    └── main.py  # Main entry point
'''
to_path(path)[source]

Extract the resource contents to a specified path.

Deserializes the stored data and recreates the original file or directory structure at the specified destination.

Parameters:

path (str) – Path where the resource should be extracted.

Example

>>> resource = ResourceUKFT.from_path("/source/data/")
>>> resource.to_path("/destination/restored_data/")
# Recreates the original directory structure at destination
__call__(path=None, overwrite=False, cleanup=False)[source]

Return a context manager that extracts the resource to disk.

Parameters:

  • path (str, optional) – Destination directory for the extracted files. Defaults to a temp location.

  • overwrite (bool) – Whether to overwrite existing files at the destination. Defaults to False.

  • cleanup (bool) – Whether to delete the extracted files upon exiting the context. Defaults to False. Notice that when a user-specified path is provided and the path already exists, cleanup will not delete the existing path to avoid data loss.

Returns:

Context manager handling extraction and optional cleanup.

Return type:

_ResourceTempContext

__enter__()[source]

Extract the resource to a temporary directory using default settings.

Returns:

Self with _temp_path set during the context lifetime.

Return type:

ResourceUKFT

__exit__(exc_type, exc_val, exc_tb)[source]

Delegate cleanup to the active temporary context.

model_config = {'validate_assignment': True, 'validate_default': True}

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

model_post_init(context, /)

This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

  • self (BaseModel) – The BaseModel instance.

  • context (Any) – The context.

Return type:

None

ahvn.ukf.templates.basic.resource.diagram_composer(kl, **kwargs)[source]

Compose a well-structured folder/tree diagram for LLM consumption.

Creates a hierarchical tree structure showing the file/folder organization with optional annotations using the folder_diagram utility.

Recommended Knowledge Types:

Resource

Parameters:

  • kl (BaseUKF) – Knowledge object containing resource data.

  • **kwargs – Optional keyword arguments to override content_resources: - path (str): Original file/directory path. - annotations (Dict): File-level annotations.

Returns:

Formatted tree structure diagram with optional annotations.

Return type:

str

Example

>>> kl.content_resources = {
...     "path": "project",
...     "annotations": {"src/main.py": "Main entry point"}
... }
>>> diagram_composer(kl)
'''
project/
├── src/
│   └── main.py  # Main entry point
'''
ahvn.ukf.templates.basic.resource.list_composer(kl, ext=None, **kwargs)[source]

Compose a simple list of file paths in the resource with optional extension filtering.

Creates a flat listing of files (not directories) in the resource, with optional annotations and extension filtering.

Recommended Knowledge Types:

ResourceUKFT

Parameters:

  • kl (BaseUKF) – Knowledge object containing resource data.

  • ext (Union[None, str, List[str]]) – File extension filter. Defaults to None. - If None (default): List all files. - If a string: Filter by that extension (e.g., “py”, “md”). - If a list: Filter by any of the extensions in the list. Multiple extensions can be separated by commas or semicolons.

  • **kwargs – Optional keyword arguments to override content_resources: - data (Dict): Serialized file/directory structure. - annotations (Dict): File-level annotations.

Returns:

Formatted list of file paths with annotations.

Return type:

str

Example

>>> kl.content_resources = {
...     "data": {"file1.py": "...", "src/main.py": "...", "src/": None},
...     "annotations": {"src/main.py": "Main entry point"}
... }
>>> list_composer(kl)
'''
- file1.py
- src/main.py  # Main entry point
'''
>>> list_composer(kl, ext="py")
'''
- file1.py
- src/main.py  # Main entry point
'''