mnesis.files

files

Large file handling with content-addressed references.

FileHandleResult

Bases: BaseModel

Result of processing a file through the LargeFileHandler.

Exactly one of inline_content or file_ref is set:

• inline_content is present when the file fits within the inline token threshold and its text is safe to embed directly in context.
• file_ref is present when the file exceeds the threshold; a FileRefPart carries the content hash and an exploration summary.

Use :attr:is_inline to branch without inspecting both fields.

path instance-attribute

path: str

Original file path as provided by the caller.

inline_content class-attribute instance-attribute

inline_content: str | None = None

Present when the file fits within the inline threshold.

file_ref class-attribute instance-attribute

file_ref: FileRefPart | None = None

Present when the file exceeds the inline threshold.

is_inline property

is_inline: bool

Return True when the file was inlined rather than stored externally.

LargeFileHandler

LargeFileHandler(
    store: ImmutableStore,
    estimator: TokenEstimator,
    config: FileConfig,
)

Token-gated file inclusion with content-addressed external storage.

Files below FileConfig.inline_threshold are included verbatim. Files at or above the threshold are stored in the file_references table and represented in context as FileRefPart objects.

Content addressing ensures: - Identical file content is summarized only once (cached by SHA-256 hash). - Changed files get a new hash and trigger a fresh exploration summary. - Large file content is never stored directly in the ImmutableStore.

Construction: prefer the :meth:from_session factory to avoid constructing internal objects directly::

async with MnesisSession.open(model="...") as session:
    handler = LargeFileHandler.from_session(session)
    result = await handler.handle_file("/path/to/large.py")
    if result.is_inline:
        print(result.inline_content)
    else:
        print(result.file_ref.exploration_summary)

If you need a standalone handler (e.g. for pre-processing files before starting a session) use the primary constructor directly::

store = ImmutableStore(StoreConfig())
await store.initialize()
handler = LargeFileHandler(store, TokenEstimator(), FileConfig())

from_session classmethod

from_session(session: object) -> LargeFileHandler

Construct a LargeFileHandler from an existing MnesisSession.

This is the recommended factory when a session is already open. It reuses the session's store connection, token estimator, and file config so no additional setup is needed.

Parameters:

Name	Type	Description	Default
session	object	An open :class:~mnesis.session.MnesisSession instance.	required

Returns:

Name	Type	Description
A	LargeFileHandler	class:LargeFileHandler ready to process files.

Example::

async with MnesisSession.open(model="...") as session:
    handler = LargeFileHandler.from_session(session)
    result = await handler.handle_file("/path/to/file.py")

handle_file async

handle_file(
    path: str | Path, *, content: str | bytes | None = None
) -> FileHandleResult

Process a file for inclusion in context.

Parameters:

Name	Type	Description	Default
path	str | Path	File path (used for display and type detection). Accepts both str and :class:pathlib.Path.	required
content	str | bytes | None	Pre-read content. If None, reads from disk.	None

Returns:

Type	Description
FileHandleResult	FileHandleResult with either inline content or a FileRefPart.