offagent 0.10.0__py3-none-any.whl

offagent/domain/models.py

@@ -0,0 +1,477 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from pathlib import Path
+from typing import Any, Literal
+
+FileType = Literal["docx", "pptx", "xlsx"]
+OperationType = Literal["replace_text", "append_text", "write_value"]
+SearchMode = Literal["keyword", "semantic", "hybrid"]
+MatchMode = Literal["keyword", "semantic", "hybrid"]
+
+
+class Capability(StrEnum):
+    READ = "read"
+    UPDATE = "update"
+    DELETE = "delete"
+    ADD_CHILD = "add_child"
+    MOVE = "move"
+    COPY = "copy"
+    STYLE = "style"
+
+
+@dataclass(frozen=True)
+class DocumentRef:
+    document_id: str
+    path: Path
+    file_type: FileType
+    display_name: str
+    modified_time: float
+    content_hash: str | None = None
+    item_count: int | None = None
+
+
+@dataclass(frozen=True)
+class ItemRef:
+    document_id: str
+    item_id: str
+    item_type: str
+    locator: str
+    preview: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+    content_text: str | None = None
+
+
+@dataclass(frozen=True)
+class SearchHit:
+    document_id: str
+    item_id: str
+    score: float
+    matched_text: str
+    locator: str
+    item_type: str
+    preview: str
+    document_path: Path | None = None
+    display_name: str | None = None
+    match_mode: MatchMode | None = None
+    scores: dict[str, float] | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class IndexedItem:
+    item_id: str
+    item_type: str
+    locator: str
+    preview: str
+    content_text: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class XlsxRowEmbeddingCell:
+    item_id: str
+    coordinate: str
+    display_text: str
+    preview: str
+
+
+@dataclass(frozen=True)
+class XlsxRowEmbedding:
+    sheet_name: str
+    row_number: int
+    text: str
+    preview: str
+    representative_item_id: str
+    contributing_cells: tuple[XlsxRowEmbeddingCell, ...]
+
+
+@dataclass(frozen=True)
+class InlineStyle:
+    bold: bool | None = None
+    italic: bool | None = None
+    underline: bool | None = None
+    strike: bool | None = None
+    font_name: str | None = None
+    font_size: float | None = None
+    font_color: str | None = None
+    highlight: str | None = None
+
+
+@dataclass(frozen=True)
+class VisibleTextRange:
+    start: int
+    end: int
+
+
+@dataclass(frozen=True)
+class InlineFragment:
+    text: str
+    style: InlineStyle = field(default_factory=InlineStyle)
+
+
+@dataclass(frozen=True)
+class TextContainerSnapshot:
+    locator: str
+    object_type: str
+    text: str
+    fragments: tuple[InlineFragment, ...]
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class BlockStyle:
+    alignment: str | None = None
+    indent_level: int | None = None
+    left_indent: float | None = None
+    right_indent: float | None = None
+    spacing_before: float | None = None
+    spacing_after: float | None = None
+    line_spacing: float | None = None
+    wrap_text: bool | None = None
+    vertical_alignment: str | None = None
+    fill_color: str | None = None
+    number_format: str | None = None
+
+
+@dataclass(frozen=True)
+class PatchOperation:
+    patch_id: str
+    document_id: str
+    item_id: str
+    operation_type: OperationType
+    payload: dict[str, Any] = field(default_factory=dict)
+    dry_run: bool = False
+    output_path: Path | None = None
+
+
+@dataclass(frozen=True)
+class StructureUnit:
+    position: int
+    unit_type: str
+    preview: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class DocumentStructure:
+    document: DocumentRef
+    units: tuple[StructureUnit, ...]
+
+
+@dataclass(frozen=True)
+class PresentationSlideSummary:
+    slide_number: int
+    preview: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class PresentationStructure:
+    document: DocumentRef
+    slides: tuple[PresentationSlideSummary, ...]
+
+
+@dataclass(frozen=True)
+class SlideTextBlock:
+    position: int
+    shape_id: int
+    shape_name: str | None
+    preview: str
+    text: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class SlideBundle:
+    document: DocumentRef
+    slide_number: int
+    preview: str
+    notes_text: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+    text_blocks: tuple[SlideTextBlock, ...] = ()
+
+
+@dataclass(frozen=True)
+class SlideNotes:
+    document_id: str
+    slide_number: int
+    notes_text: str
+
+
+@dataclass(frozen=True)
+class DocxParagraph:
+    block_index: int
+    paragraph_index: int
+    text: str
+    style_name: str | None
+    is_heading: bool
+    preview: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class DocxTable:
+    block_index: int
+    table_index: int
+    rows: tuple[tuple[str, ...], ...]
+    preview: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class DocumentBlock:
+    block_index: int
+    block_type: str
+    preview: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class DocumentBlocks:
+    document: DocumentRef
+    blocks: tuple[DocumentBlock, ...]
+
+
+@dataclass(frozen=True)
+class ParagraphCollection:
+    document: DocumentRef
+    paragraphs: tuple[DocxParagraph, ...]
+
+
+@dataclass(frozen=True)
+class TableCollection:
+    document: DocumentRef
+    tables: tuple[DocxTable, ...]
+
+
+@dataclass(frozen=True)
+class BlockBundle:
+    document: DocumentRef
+    block: DocumentBlock
+    paragraph: DocxParagraph | None = None
+    table: DocxTable | None = None
+
+
+@dataclass(frozen=True)
+class WorksheetSummary:
+    position: int
+    sheet_name: str
+    preview: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class WorkbookStructure:
+    document: DocumentRef
+    sheets: tuple[WorksheetSummary, ...]
+
+
+@dataclass(frozen=True)
+class SheetCell:
+    coordinate: str
+    row: int
+    column: int
+    display_value: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class SheetSnapshot:
+    document: DocumentRef
+    sheet_name: str
+    cells: tuple[SheetCell, ...]
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class StructuredTarget:
+    target_type: str
+    identifier: str
+    preview: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class StructuredWriteResult:
+    document_path: Path
+    output_path: Path
+    target: StructuredTarget
+    summary: str
+
+
+@dataclass(frozen=True)
+class StructureSection:
+    locator: str
+    section_type: str
+    preview: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class StructureCollection:
+    document: DocumentRef
+    sections: tuple[StructureSection, ...]
+
+
+@dataclass(frozen=True)
+class DocxRun:
+    text: str
+    bold: bool | None
+    italic: bool | None
+    underline: bool | None
+    strike: bool | None
+    font_name: str | None
+    font_size: int | None
+    color_rgb: str | None
+
+
+@dataclass(frozen=True)
+class DocxTableCell:
+    locator: str
+    row_index: int
+    column_index: int
+    text: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class PptxTextBlockNode:
+    locator: str
+    position: int
+    shape_id: int
+    shape_name: str | None
+    preview: str
+    text: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class XlsxSectionCell:
+    locator: str
+    coordinate: str
+    row: int
+    column: int
+    display_value: str
+    formula: str | None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class SectionPayload:
+    document: DocumentRef
+    locator: str
+    section_type: str
+    preview: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+    block_type: str | None = None
+    text: str | None = None
+    style_name: str | None = None
+    is_heading: bool | None = None
+    runs: tuple[DocxRun, ...] = ()
+    rows: tuple[tuple[str, ...], ...] = ()
+    table_cells: tuple[DocxTableCell, ...] = ()
+    slide_number: int | None = None
+    notes_text: str | None = None
+    text_blocks: tuple[PptxTextBlockNode, ...] = ()
+    sheet_name: str | None = None
+    cells: tuple[XlsxSectionCell, ...] = ()
+
+
+@dataclass(frozen=True)
+class NodePayload:
+    document_id: str
+    node_id: str
+    item_type: str
+    text: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class NodeWriteResult:
+    document_path: Path
+    output_path: Path
+    document_id: str
+    node_id: str
+    new_text: str
+    previous_text: str
+
+
+@dataclass(frozen=True)
+class InsertContentResult:
+    document_path: Path
+    output_path: Path
+    document_id: str
+    new_node_id: str
+    preview: str
+
+
+@dataclass(frozen=True)
+class XlsxInsertRowsResult:
+    document_path: Path
+    output_path: Path
+    document_id: str
+    rows_inserted: int
+    first_row_locator: str
+
+
+@dataclass(frozen=True)
+class DocxTableEntry:
+    locator: str
+    table_index: int
+    rows: tuple[tuple[str, ...], ...]
+    preview: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class DocxTablesResult:
+    document: DocumentRef
+    tables: tuple[DocxTableEntry, ...]
+
+
+@dataclass(frozen=True)
+class ChildSummary:
+    locator: str
+    object_type: str
+    preview: str
+    capabilities: tuple[Capability, ...] = ()
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ObjectPayload:
+    document: DocumentRef
+    locator: str
+    object_type: str
+    preview: str
+    properties: dict[str, Any] = field(default_factory=dict)
+    capabilities: tuple[Capability, ...] = ()
+    parent_locator: str | None = None
+    child_summary: tuple[ChildSummary, ...] = ()
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class MutationResult:
+    document_path: Path
+    output_path: Path | None
+    document_id: str
+    locator: str | None
+    object_type: str
+    summary: str
+    capabilities: tuple[Capability, ...] = ()
+    parent_locator: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class BatchResult:
+    document_path: Path
+    output_path: Path | None
+    document_id: str
+    summary: str
+    dry_run: bool = False
+    operations: tuple[MutationResult, ...] = ()
+    metadata: dict[str, Any] = field(default_factory=dict)

offagent/domain/text_fragments.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+from dataclasses import replace
+
+from offagent.domain.models import InlineFragment, InlineStyle, VisibleTextRange
+from offagent.errors import InvalidArgumentsError
+
+
+def normalize_fragments(
+    fragments: list[InlineFragment] | tuple[InlineFragment, ...],
+) -> tuple[InlineFragment, ...]:
+    merged: list[InlineFragment] = []
+    for fragment in fragments:
+        if not fragment.text:
+            continue
+        if merged and merged[-1].style == fragment.style:
+            previous = merged[-1]
+            merged[-1] = InlineFragment(
+                text=f"{previous.text}{fragment.text}", style=previous.style
+            )
+            continue
+        merged.append(fragment)
+    return tuple(merged)
+
+
+def split_fragments_at_offsets(
+    fragments: list[InlineFragment] | tuple[InlineFragment, ...],
+    offsets: list[int] | tuple[int, ...],
+) -> tuple[InlineFragment, ...]:
+    normalized_offsets = sorted({offset for offset in offsets if offset > 0})
+    if not normalized_offsets:
+        return normalize_fragments(fragments)
+
+    split: list[InlineFragment] = []
+    current_offset = 0
+    offset_index = 0
+    for fragment in normalize_fragments(fragments):
+        fragment_start = current_offset
+        fragment_end = current_offset + len(fragment.text)
+        start = 0
+        while (
+            offset_index < len(normalized_offsets)
+            and normalized_offsets[offset_index] < fragment_end
+        ):
+            split_at = normalized_offsets[offset_index]
+            if split_at > fragment_start:
+                relative = split_at - fragment_start
+                if relative > start:
+                    split.append(
+                        InlineFragment(
+                            text=fragment.text[start:relative], style=fragment.style
+                        )
+                    )
+                start = relative
+            offset_index += 1
+        if start < len(fragment.text):
+            split.append(
+                InlineFragment(text=fragment.text[start:], style=fragment.style)
+            )
+        current_offset = fragment_end
+    return tuple(split)
+
+
+def validate_visible_text_range(
+    text_range: VisibleTextRange, *, text_length: int
+) -> None:
+    if text_range.start < 0 or text_range.end < 0:
+        raise InvalidArgumentsError(
+            "Visible-text ranges must use non-negative offsets."
+        )
+    if text_range.end <= text_range.start:
+        raise InvalidArgumentsError("Visible-text ranges must have end > start.")
+    if text_range.end > text_length:
+        raise InvalidArgumentsError(
+            f"Visible-text range {text_range.start}:{text_range.end} exceeds container length {text_length}."
+        )
+
+
+def apply_style_to_range(
+    fragments: list[InlineFragment] | tuple[InlineFragment, ...],
+    text_range: VisibleTextRange,
+    *,
+    style: InlineStyle,
+    clear_fields: list[str] | tuple[str, ...],
+) -> tuple[InlineFragment, ...]:
+    normalized = normalize_fragments(fragments)
+    text_length = sum(len(fragment.text) for fragment in normalized)
+    validate_visible_text_range(text_range, text_length=text_length)
+    split = split_fragments_at_offsets(normalized, (text_range.start, text_range.end))
+
+    updated: list[InlineFragment] = []
+    cursor = 0
+    for fragment in split:
+        next_cursor = cursor + len(fragment.text)
+        if cursor >= text_range.start and next_cursor <= text_range.end:
+            updated.append(
+                InlineFragment(
+                    text=fragment.text,
+                    style=merge_inline_style(fragment.style, style, clear_fields),
+                )
+            )
+        else:
+            updated.append(fragment)
+        cursor = next_cursor
+    return normalize_fragments(updated)
+
+
+def merge_inline_style(
+    base: InlineStyle,
+    patch: InlineStyle,
+    clear_fields: list[str] | tuple[str, ...],
+) -> InlineStyle:
+    values = base.__dict__.copy()
+    clear_set = set(clear_fields)
+    for field_name in clear_set:
+        values[field_name] = None
+    for field_name, value in patch.__dict__.items():
+        if field_name in clear_set:
+            continue
+        if value is not None:
+            values[field_name] = value
+    return InlineStyle(**values)
+
+
+def style_is_empty(style: InlineStyle) -> bool:
+    return all(value is None for value in style.__dict__.values())
+
+
+def fragment_text(
+    fragments: list[InlineFragment] | tuple[InlineFragment, ...],
+) -> str:
+    return "".join(fragment.text for fragment in fragments)
+
+
+def clone_fragment(fragment: InlineFragment) -> InlineFragment:
+    return InlineFragment(text=fragment.text, style=replace(fragment.style))

offagent/errors.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+
+class OffagentError(RuntimeError):
+    """Base runtime error for Office Agent failures."""
+
+
+class InvalidArgumentsError(ValueError):
+    """Raised when user input is syntactically or semantically invalid."""
+
+
+class TargetNotFoundError(LookupError):
+    """Raised when a document, item, or indexed target cannot be resolved."""
+
+
+class TargetNotEditableError(OffagentError):
+    """Raised when a target exists but the requested edit is unsupported."""
+
+
+class PolicyRefusedError(OffagentError):
+    """Raised when a configured path policy refuses an operation."""
+
+
+class StaleLocatorError(TargetNotFoundError):
+    """Raised when a previously indexed target no longer resolves safely."""
+
+
+class NoEmbeddingsError(TargetNotFoundError):
+    """Raised when semantic retrieval is requested without indexed embeddings."""

offagent/indexing/__init__.py

@@ -0,0 +1 @@
+"""Index storage primitives."""