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>)[源代码]

基类：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

```

参数:
type_default: ClassVar[str] = 'resource'
classmethod from_path(path, name=None, keep_path=True, **updates)[源代码]

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.

参数:

  • 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.

返回:

New ResourceUKFT instance with pre-configured composers:

  • diagram: diagram_composer for LLM-friendly folder structure diagram

返回类型:

ResourceUKFT

示例

>>> 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)[源代码]

Create a ResourceUKFT instance from serialized data.

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

参数:

  • 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.

返回:

New ResourceUKFT instance with pre-configured composers.

返回类型:

ResourceUKFT

示例

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

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.

参数:

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

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

返回:

A new ResourceUKFT instance with the annotation added.

返回类型:

ResourceUKFT

示例

>>> 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)[源代码]

Extract the resource contents to a specified path.

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

参数:

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

示例

>>> 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)[源代码]

Return a context manager that extracts the resource to disk.

参数:

  • 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.

返回:

Context manager handling extraction and optional cleanup.

返回类型:

_ResourceTempContext

__enter__()[源代码]

Extract the resource to a temporary directory using default settings.

返回:

Self with _temp_path set during the context lifetime.

返回类型:

ResourceUKFT

__exit__(exc_type, exc_val, exc_tb)[源代码]

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.

参数:

  • self (BaseModel) -- The BaseModel instance.

  • context (Any) -- The context.

返回类型:

None

ahvn.ukf.templates.basic.resource.diagram_composer(kl, **kwargs)[源代码]

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

参数:

  • 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.

返回:

Formatted tree structure diagram with optional annotations.

返回类型:

str

示例

>>> 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)[源代码]

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

参数:

  • 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.

返回:

Formatted list of file paths with annotations.

返回类型:

str

示例

>>> 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
'''