mcp docs

docs/index.md

@@ -1,3 +1,4 @@
 # omniread
 
 ::: omniread
+- [Omniread](omniread/)

mcp_docs/modules/omniread.core.content.json

@@ -2,7 +2,7 @@
   "module": "omniread.core.content",
   "content": {
     "path": "omniread.core.content",
-    "docstring": "Canonical content models for OmniRead.\n\nThis module defines the **format-agnostic content representation** used across\nall parsers and scrapers in OmniRead.\n\nThe models defined here represent *what* was extracted, not *how* it was\nretrieved or parsed. Format-specific behavior and metadata must not alter\nthe semantic meaning of these models.",
+    "docstring": "Canonical content models for OmniRead.\n\n---\n\n## Summary\n\nThis module defines the **format-agnostic content representation** used across\nall parsers and scrapers in OmniRead.\n\nThe models defined here represent *what* was extracted, not *how* it was\nretrieved or parsed. Format-specific behavior and metadata must not alter\nthe semantic meaning of these models.",
     "objects": {
       "Enum": {
         "name": "Enum",
@@ -43,8 +43,8 @@
         "name": "ContentType",
         "kind": "class",
         "path": "omniread.core.content.ContentType",
-        "signature": "<bound method Class.signature of Class('ContentType', 17, 36)>",
+        "signature": "<bound method Class.signature of Class('ContentType', 21, 42)>",
-        "docstring": "Supported MIME types for extracted content.\n\nThis enum represents the declared or inferred media type of the content\nsource. It is primarily used for routing content to the appropriate\nparser or downstream consumer.",
+        "docstring": "Supported MIME types for extracted content.\n\nNotes:\n    **Guarantees:**\n\n        - This enum represents the declared or inferred media type of the content source\n        - It is primarily used for routing content to the appropriate parser or downstream consumer",
         "members": {
           "HTML": {
             "name": "HTML",
@@ -80,36 +80,36 @@
         "name": "Content",
         "kind": "class",
         "path": "omniread.core.content.Content",
-        "signature": "<bound method Class.signature of Class('Content', 39, 63)>",
+        "signature": "<bound method Class.signature of Class('Content', 45, 75)>",
-        "docstring": "Normalized representation of extracted content.\n\nA `Content` instance represents a raw content payload along with minimal\ncontextual metadata describing its origin and type.\n\nThis class is the **primary exchange format** between:\n- Scrapers\n- Parsers\n- Downstream consumers\n\nAttributes:\n    raw: Raw content bytes as retrieved from the source.\n    source: Identifier of the content origin (URL, file path, or logical name).\n    content_type: Optional MIME type of the content, if known.\n    metadata: Optional, implementation-defined metadata associated with\n        the content (e.g., headers, encoding hints, extraction notes).",
+        "docstring": "Normalized representation of extracted content.\n\nNotes:\n    **Responsibilities:**\n\n        - A `Content` instance represents a raw content payload along with minimal contextual metadata describing its origin and type\n        - This class is the primary exchange format between Scrapers, Parsers, and Downstream consumers",
         "members": {
           "raw": {
             "name": "raw",
             "kind": "attribute",
             "path": "omniread.core.content.Content.raw",
             "signature": null,
-            "docstring": null
+            "docstring": "Raw content bytes as retrieved from the source."
           },
           "source": {
             "name": "source",
             "kind": "attribute",
             "path": "omniread.core.content.Content.source",
             "signature": null,
-            "docstring": null
+            "docstring": "Identifier of the content origin (URL, file path, or logical name)."
           },
           "content_type": {
             "name": "content_type",
             "kind": "attribute",
             "path": "omniread.core.content.Content.content_type",
             "signature": null,
-            "docstring": null
+            "docstring": "Optional MIME type of the content, if known."
           },
           "metadata": {
             "name": "metadata",
             "kind": "attribute",
             "path": "omniread.core.content.Content.metadata",
             "signature": null,
-            "docstring": null
+            "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)."
           }
         }
       }

mcp_docs/modules/omniread.core.json

@@ -2,42 +2,42 @@
   "module": "omniread.core",
   "content": {
     "path": "omniread.core",
-    "docstring": "Core domain contracts for OmniRead.\n\nThis package defines the **format-agnostic domain layer** of OmniRead.\nIt exposes canonical content models and abstract interfaces that are\nimplemented by format-specific modules (HTML, PDF, etc.).\n\nPublic exports from this package are considered **stable contracts** and\nare safe for downstream consumers to depend on.\n\nSubmodules:\n- content: Canonical content models and enums\n- parser: Abstract parsing contracts\n- scraper: Abstract scraping contracts\n\nFormat-specific behavior must not be introduced at this layer.",
+    "docstring": "Core domain contracts for OmniRead.\n\n---\n\n## Summary\n\nThis package defines the **format-agnostic domain layer** of OmniRead.\nIt exposes canonical content models and abstract interfaces that are\nimplemented by format-specific modules (HTML, PDF, etc.).\n\nPublic exports from this package are considered **stable contracts** and\nare safe for downstream consumers to depend on.\n\nSubmodules:\n- content: Canonical content models and enums\n- parser: Abstract parsing contracts\n- scraper: Abstract scraping contracts\n\nFormat-specific behavior must not be introduced at this layer.\n\n---\n\n## Public API\n\n    Content\n    ContentType\n\n---",
     "objects": {
       "Content": {
         "name": "Content",
         "kind": "class",
         "path": "omniread.core.Content",
         "signature": "<bound method Alias.signature of Alias('Content', 'omniread.core.content.Content')>",
-        "docstring": "Normalized representation of extracted content.\n\nA `Content` instance represents a raw content payload along with minimal\ncontextual metadata describing its origin and type.\n\nThis class is the **primary exchange format** between:\n- Scrapers\n- Parsers\n- Downstream consumers\n\nAttributes:\n    raw: Raw content bytes as retrieved from the source.\n    source: Identifier of the content origin (URL, file path, or logical name).\n    content_type: Optional MIME type of the content, if known.\n    metadata: Optional, implementation-defined metadata associated with\n        the content (e.g., headers, encoding hints, extraction notes).",
+        "docstring": "Normalized representation of extracted content.\n\nNotes:\n    **Responsibilities:**\n\n        - A `Content` instance represents a raw content payload along with minimal contextual metadata describing its origin and type\n        - This class is the primary exchange format between Scrapers, Parsers, and Downstream consumers",
         "members": {
           "raw": {
             "name": "raw",
             "kind": "attribute",
             "path": "omniread.core.Content.raw",
             "signature": "<bound method Alias.signature of Alias('raw', 'omniread.core.content.Content.raw')>",
-            "docstring": null
+            "docstring": "Raw content bytes as retrieved from the source."
           },
           "source": {
             "name": "source",
             "kind": "attribute",
             "path": "omniread.core.Content.source",
             "signature": "<bound method Alias.signature of Alias('source', 'omniread.core.content.Content.source')>",
-            "docstring": null
+            "docstring": "Identifier of the content origin (URL, file path, or logical name)."
           },
           "content_type": {
             "name": "content_type",
             "kind": "attribute",
             "path": "omniread.core.Content.content_type",
             "signature": "<bound method Alias.signature of Alias('content_type', 'omniread.core.content.Content.content_type')>",
-            "docstring": null
+            "docstring": "Optional MIME type of the content, if known."
           },
           "metadata": {
             "name": "metadata",
             "kind": "attribute",
             "path": "omniread.core.Content.metadata",
             "signature": "<bound method Alias.signature of Alias('metadata', 'omniread.core.content.Content.metadata')>",
-            "docstring": null
+            "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)."
           }
         }
       },
@@ -46,7 +46,7 @@
         "kind": "class",
         "path": "omniread.core.ContentType",
         "signature": "<bound method Alias.signature of Alias('ContentType', 'omniread.core.content.ContentType')>",
-        "docstring": "Supported MIME types for extracted content.\n\nThis enum represents the declared or inferred media type of the content\nsource. It is primarily used for routing content to the appropriate\nparser or downstream consumer.",
+        "docstring": "Supported MIME types for extracted content.\n\nNotes:\n    **Guarantees:**\n\n        - This enum represents the declared or inferred media type of the content source\n        - It is primarily used for routing content to the appropriate parser or downstream consumer",
         "members": {
           "HTML": {
             "name": "HTML",
@@ -83,14 +83,14 @@
         "kind": "class",
         "path": "omniread.core.BaseParser",
         "signature": "<bound method Alias.signature of Alias('BaseParser', 'omniread.core.parser.BaseParser')>",
-        "docstring": "Base interface for all parsers.\n\nA parser is a self-contained object that owns the Content\nit is responsible for interpreting.\n\nImplementations must:\n- Declare supported content types via `supported_types`\n- Raise parsing-specific exceptions from `parse()`\n- Remain deterministic for a given input\n\nConsumers may rely on:\n- Early validation of content compatibility\n- Type-stable return values from `parse()`",
+        "docstring": "Base interface for all parsers.\n\nNotes:\n    **Guarantees:**\n\n        - A parser is a self-contained object that owns the Content it is responsible for interpreting\n        - Consumers may rely on early validation of content compatibility and type-stable return values from `parse()`\n\n    **Responsibilities:**\n\n        - Implementations must declare supported content types via `supported_types`\n        - Implementations must raise parsing-specific exceptions from `parse()`\n        - Implementations must remain deterministic for a given input",
         "members": {
           "supported_types": {
             "name": "supported_types",
             "kind": "attribute",
             "path": "omniread.core.BaseParser.supported_types",
             "signature": "<bound method Alias.signature of Alias('supported_types', 'omniread.core.parser.BaseParser.supported_types')>",
-            "docstring": "Set of content types supported by this parser.\n\nAn empty set indicates that the parser is content-type agnostic."
+            "docstring": "Set of content types supported by this parser. An empty set indicates that the parser is content-type agnostic."
           },
           "content": {
             "name": "content",
@@ -104,14 +104,14 @@
             "kind": "function",
             "path": "omniread.core.BaseParser.parse",
             "signature": "<bound method Alias.signature of Alias('parse', 'omniread.core.parser.BaseParser.parse')>",
-            "docstring": "Parse the owned content into structured output.\n\nImplementations must fully consume the provided content and\nreturn a deterministic, structured output.\n\nReturns:\n    Parsed, structured representation.\n\nRaises:\n    Exception: Parsing-specific errors as defined by the implementation."
+            "docstring": "Parse the owned content into structured output.\n\nReturns:\n    T:\n        Parsed, structured representation.\n\nRaises:\n    Exception:\n        Parsing-specific errors as defined by the implementation.\n\nNotes:\n    **Responsibilities:**\n\n        - Implementations must fully consume the provided content and return a deterministic, structured output"
           },
           "supports": {
             "name": "supports",
             "kind": "function",
             "path": "omniread.core.BaseParser.supports",
             "signature": "<bound method Alias.signature of Alias('supports', 'omniread.core.parser.BaseParser.supports')>",
-            "docstring": "Check whether this parser supports the content's type.\n\nReturns:\n    True if the content type is supported; False otherwise."
+            "docstring": "Check whether this parser supports the content's type.\n\nReturns:\n    bool:\n        True if the content type is supported; False otherwise."
           }
         }
       },
@@ -120,14 +120,14 @@
         "kind": "class",
         "path": "omniread.core.BaseScraper",
         "signature": "<bound method Alias.signature of Alias('BaseScraper', 'omniread.core.scraper.BaseScraper')>",
-        "docstring": "Base interface for all scrapers.\n\nA scraper is responsible ONLY for fetching raw content\n(bytes) from a source. It must not interpret or parse it.\n\nA scraper is a **stateless acquisition component** that retrieves raw\ncontent from a source and returns it as a `Content` object.\n\nScrapers define *how content is obtained*, not *what the content means*.\n\nImplementations may vary in:\n- Transport mechanism (HTTP, filesystem, cloud storage)\n- Authentication strategy\n- Retry and backoff behavior\n\nImplementations must not:\n- Parse content\n- Modify content semantics\n- Couple scraping logic to a specific parser",
+        "docstring": "Base interface for all scrapers.\n\nNotes:\n    **Responsibilities:**\n\n        - A scraper is responsible ONLY for fetching raw content (bytes) from a source. It must not interpret or parse it\n        - A scraper is a stateless acquisition component that retrieves raw content from a source and returns it as a `Content` object\n        - Scrapers define how content is obtained, not what the content means\n        - Implementations may vary in transport mechanism, authentication strategy, retry and backoff behavior\n\n    **Constraints:**\n\n        - Implementations must not parse content, modify content semantics, or couple scraping logic to a specific parser",
         "members": {
           "fetch": {
             "name": "fetch",
             "kind": "function",
             "path": "omniread.core.BaseScraper.fetch",
             "signature": "<bound method Alias.signature of Alias('fetch', 'omniread.core.scraper.BaseScraper.fetch')>",
-            "docstring": "Fetch raw content from the given source.\n\nImplementations must retrieve the content referenced by `source`\nand return it as raw bytes wrapped in a `Content` object.\n\nArgs:\n    source: Location identifier (URL, file path, S3 URI, etc.)\n    metadata: Optional hints for the scraper (headers, auth, etc.)\n\nReturns:\n    Content object containing raw bytes and metadata.\n    - Raw content bytes\n    - Source identifier\n    - Optional metadata\n\nRaises:\n    Exception: Retrieval-specific errors as defined by the implementation."
+            "docstring": "Fetch raw content from the given source.\n\nArgs:\n    source (str):\n        Location identifier (URL, file path, S3 URI, etc.)\n    metadata (Optional[Mapping[str, Any]], optional):\n        Optional hints for the scraper (headers, auth, etc.)\n\nReturns:\n    Content:\n        Content object containing raw bytes and metadata.\n\nRaises:\n    Exception:\n        Retrieval-specific errors as defined by the implementation.\n\nNotes:\n    **Responsibilities:**\n\n        - Implementations must retrieve the content referenced by `source` and return it as raw bytes wrapped in a `Content` object"
           }
         }
       },
@@ -136,7 +136,7 @@
         "kind": "module",
         "path": "omniread.core.content",
         "signature": null,
-        "docstring": "Canonical content models for OmniRead.\n\nThis module defines the **format-agnostic content representation** used across\nall parsers and scrapers in OmniRead.\n\nThe models defined here represent *what* was extracted, not *how* it was\nretrieved or parsed. Format-specific behavior and metadata must not alter\nthe semantic meaning of these models.",
+        "docstring": "Canonical content models for OmniRead.\n\n---\n\n## Summary\n\nThis module defines the **format-agnostic content representation** used across\nall parsers and scrapers in OmniRead.\n\nThe models defined here represent *what* was extracted, not *how* it was\nretrieved or parsed. Format-specific behavior and metadata must not alter\nthe semantic meaning of these models.",
         "members": {
           "Enum": {
             "name": "Enum",
@@ -177,8 +177,8 @@
             "name": "ContentType",
             "kind": "class",
             "path": "omniread.core.content.ContentType",
-            "signature": "<bound method Class.signature of Class('ContentType', 17, 36)>",
+            "signature": "<bound method Class.signature of Class('ContentType', 21, 42)>",
-            "docstring": "Supported MIME types for extracted content.\n\nThis enum represents the declared or inferred media type of the content\nsource. It is primarily used for routing content to the appropriate\nparser or downstream consumer.",
+            "docstring": "Supported MIME types for extracted content.\n\nNotes:\n    **Guarantees:**\n\n        - This enum represents the declared or inferred media type of the content source\n        - It is primarily used for routing content to the appropriate parser or downstream consumer",
             "members": {
               "HTML": {
                 "name": "HTML",
@@ -214,36 +214,36 @@
             "name": "Content",
             "kind": "class",
             "path": "omniread.core.content.Content",
-            "signature": "<bound method Class.signature of Class('Content', 39, 63)>",
+            "signature": "<bound method Class.signature of Class('Content', 45, 75)>",
-            "docstring": "Normalized representation of extracted content.\n\nA `Content` instance represents a raw content payload along with minimal\ncontextual metadata describing its origin and type.\n\nThis class is the **primary exchange format** between:\n- Scrapers\n- Parsers\n- Downstream consumers\n\nAttributes:\n    raw: Raw content bytes as retrieved from the source.\n    source: Identifier of the content origin (URL, file path, or logical name).\n    content_type: Optional MIME type of the content, if known.\n    metadata: Optional, implementation-defined metadata associated with\n        the content (e.g., headers, encoding hints, extraction notes).",
+            "docstring": "Normalized representation of extracted content.\n\nNotes:\n    **Responsibilities:**\n\n        - A `Content` instance represents a raw content payload along with minimal contextual metadata describing its origin and type\n        - This class is the primary exchange format between Scrapers, Parsers, and Downstream consumers",
             "members": {
               "raw": {
                 "name": "raw",
                 "kind": "attribute",
                 "path": "omniread.core.content.Content.raw",
                 "signature": null,
-                "docstring": null
+                "docstring": "Raw content bytes as retrieved from the source."
               },
               "source": {
                 "name": "source",
                 "kind": "attribute",
                 "path": "omniread.core.content.Content.source",
                 "signature": null,
-                "docstring": null
+                "docstring": "Identifier of the content origin (URL, file path, or logical name)."
               },
               "content_type": {
                 "name": "content_type",
                 "kind": "attribute",
                 "path": "omniread.core.content.Content.content_type",
                 "signature": null,
-                "docstring": null
+                "docstring": "Optional MIME type of the content, if known."
               },
               "metadata": {
                 "name": "metadata",
                 "kind": "attribute",
                 "path": "omniread.core.content.Content.metadata",
                 "signature": null,
-                "docstring": null
+                "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)."
               }
             }
           }
@@ -254,7 +254,7 @@
         "kind": "module",
         "path": "omniread.core.parser",
         "signature": null,
-        "docstring": "Abstract parsing contracts for OmniRead.\n\nThis module defines the **format-agnostic parser interface** used to transform\nraw content into structured, typed representations.\n\nParsers are responsible for:\n- Interpreting a single `Content` instance\n- Validating compatibility with the content type\n- Producing a structured output suitable for downstream consumers\n\nParsers are not responsible for:\n- Fetching or acquiring content\n- Performing retries or error recovery\n- Managing multiple content sources",
+        "docstring": "Abstract parsing contracts for OmniRead.\n\n---\n\n## Summary\n\nThis module defines the **format-agnostic parser interface** used to transform\nraw content into structured, typed representations.\n\nParsers are responsible for:\n- Interpreting a single `Content` instance\n- Validating compatibility with the content type\n- Producing a structured output suitable for downstream consumers\n\nParsers are not responsible for:\n- Fetching or acquiring content\n- Performing retries or error recovery\n- Managing multiple content sources",
         "members": {
           "ABC": {
             "name": "ABC",
@@ -296,35 +296,35 @@
             "kind": "class",
             "path": "omniread.core.parser.Content",
             "signature": "<bound method Alias.signature of Alias('Content', 'omniread.core.content.Content')>",
-            "docstring": "Normalized representation of extracted content.\n\nA `Content` instance represents a raw content payload along with minimal\ncontextual metadata describing its origin and type.\n\nThis class is the **primary exchange format** between:\n- Scrapers\n- Parsers\n- Downstream consumers\n\nAttributes:\n    raw: Raw content bytes as retrieved from the source.\n    source: Identifier of the content origin (URL, file path, or logical name).\n    content_type: Optional MIME type of the content, if known.\n    metadata: Optional, implementation-defined metadata associated with\n        the content (e.g., headers, encoding hints, extraction notes).",
+            "docstring": "Normalized representation of extracted content.\n\nNotes:\n    **Responsibilities:**\n\n        - A `Content` instance represents a raw content payload along with minimal contextual metadata describing its origin and type\n        - This class is the primary exchange format between Scrapers, Parsers, and Downstream consumers",
             "members": {
               "raw": {
                 "name": "raw",
                 "kind": "attribute",
                 "path": "omniread.core.parser.Content.raw",
                 "signature": "<bound method Alias.signature of Alias('raw', 'omniread.core.content.Content.raw')>",
-                "docstring": null
+                "docstring": "Raw content bytes as retrieved from the source."
               },
               "source": {
                 "name": "source",
                 "kind": "attribute",
                 "path": "omniread.core.parser.Content.source",
                 "signature": "<bound method Alias.signature of Alias('source', 'omniread.core.content.Content.source')>",
-                "docstring": null
+                "docstring": "Identifier of the content origin (URL, file path, or logical name)."
               },
               "content_type": {
                 "name": "content_type",
                 "kind": "attribute",
                 "path": "omniread.core.parser.Content.content_type",
                 "signature": "<bound method Alias.signature of Alias('content_type', 'omniread.core.content.Content.content_type')>",
-                "docstring": null
+                "docstring": "Optional MIME type of the content, if known."
               },
               "metadata": {
                 "name": "metadata",
                 "kind": "attribute",
                 "path": "omniread.core.parser.Content.metadata",
                 "signature": "<bound method Alias.signature of Alias('metadata', 'omniread.core.content.Content.metadata')>",
-                "docstring": null
+                "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)."
               }
             }
           },
@@ -333,7 +333,7 @@
             "kind": "class",
             "path": "omniread.core.parser.ContentType",
             "signature": "<bound method Alias.signature of Alias('ContentType', 'omniread.core.content.ContentType')>",
-            "docstring": "Supported MIME types for extracted content.\n\nThis enum represents the declared or inferred media type of the content\nsource. It is primarily used for routing content to the appropriate\nparser or downstream consumer.",
+            "docstring": "Supported MIME types for extracted content.\n\nNotes:\n    **Guarantees:**\n\n        - This enum represents the declared or inferred media type of the content source\n        - It is primarily used for routing content to the appropriate parser or downstream consumer",
             "members": {
               "HTML": {
                 "name": "HTML",
@@ -376,15 +376,15 @@
             "name": "BaseParser",
             "kind": "class",
             "path": "omniread.core.parser.BaseParser",
-            "signature": "<bound method Class.signature of Class('BaseParser', 26, 98)>",
+            "signature": "<bound method Class.signature of Class('BaseParser', 30, 108)>",
-            "docstring": "Base interface for all parsers.\n\nA parser is a self-contained object that owns the Content\nit is responsible for interpreting.\n\nImplementations must:\n- Declare supported content types via `supported_types`\n- Raise parsing-specific exceptions from `parse()`\n- Remain deterministic for a given input\n\nConsumers may rely on:\n- Early validation of content compatibility\n- Type-stable return values from `parse()`",
+            "docstring": "Base interface for all parsers.\n\nNotes:\n    **Guarantees:**\n\n        - A parser is a self-contained object that owns the Content it is responsible for interpreting\n        - Consumers may rely on early validation of content compatibility and type-stable return values from `parse()`\n\n    **Responsibilities:**\n\n        - Implementations must declare supported content types via `supported_types`\n        - Implementations must raise parsing-specific exceptions from `parse()`\n        - Implementations must remain deterministic for a given input",
             "members": {
               "supported_types": {
                 "name": "supported_types",
                 "kind": "attribute",
                 "path": "omniread.core.parser.BaseParser.supported_types",
                 "signature": null,
-                "docstring": "Set of content types supported by this parser.\n\nAn empty set indicates that the parser is content-type agnostic."
+                "docstring": "Set of content types supported by this parser. An empty set indicates that the parser is content-type agnostic."
               },
               "content": {
                 "name": "content",
@@ -397,15 +397,15 @@
                 "name": "parse",
                 "kind": "function",
                 "path": "omniread.core.parser.BaseParser.parse",
-                "signature": "<bound method Function.signature of Function('parse', 68, 82)>",
+                "signature": "<bound method Function.signature of Function('parse', 73, 91)>",
-                "docstring": "Parse the owned content into structured output.\n\nImplementations must fully consume the provided content and\nreturn a deterministic, structured output.\n\nReturns:\n    Parsed, structured representation.\n\nRaises:\n    Exception: Parsing-specific errors as defined by the implementation."
+                "docstring": "Parse the owned content into structured output.\n\nReturns:\n    T:\n        Parsed, structured representation.\n\nRaises:\n    Exception:\n        Parsing-specific errors as defined by the implementation.\n\nNotes:\n    **Responsibilities:**\n\n        - Implementations must fully consume the provided content and return a deterministic, structured output"
               },
               "supports": {
                 "name": "supports",
                 "kind": "function",
                 "path": "omniread.core.parser.BaseParser.supports",
-                "signature": "<bound method Function.signature of Function('supports', 84, 98)>",
+                "signature": "<bound method Function.signature of Function('supports', 93, 108)>",
-                "docstring": "Check whether this parser supports the content's type.\n\nReturns:\n    True if the content type is supported; False otherwise."
+                "docstring": "Check whether this parser supports the content's type.\n\nReturns:\n    bool:\n        True if the content type is supported; False otherwise."
               }
             }
           }
@@ -416,7 +416,7 @@
         "kind": "module",
         "path": "omniread.core.scraper",
         "signature": null,
-        "docstring": "Abstract scraping contracts for OmniRead.\n\nThis module defines the **format-agnostic scraper interface** responsible for\nacquiring raw content from external sources.\n\nScrapers are responsible for:\n- Locating and retrieving raw content bytes\n- Attaching minimal contextual metadata\n- Returning normalized `Content` objects\n\nScrapers are explicitly NOT responsible for:\n- Parsing or interpreting content\n- Inferring structure or semantics\n- Performing content-type specific processing\n\nAll interpretation must be delegated to parsers.",
+        "docstring": "Abstract scraping contracts for OmniRead.\n\n---\n\n## Summary\n\nThis module defines the **format-agnostic scraper interface** responsible for\nacquiring raw content from external sources.\n\nScrapers are responsible for:\n- Locating and retrieving raw content bytes\n- Attaching minimal contextual metadata\n- Returning normalized `Content` objects\n\nScrapers are explicitly NOT responsible for:\n- Parsing or interpreting content\n- Inferring structure or semantics\n- Performing content-type specific processing\n\nAll interpretation must be delegated to parsers.",
         "members": {
           "ABC": {
             "name": "ABC",
@@ -458,35 +458,35 @@
             "kind": "class",
             "path": "omniread.core.scraper.Content",
             "signature": "<bound method Alias.signature of Alias('Content', 'omniread.core.content.Content')>",
-            "docstring": "Normalized representation of extracted content.\n\nA `Content` instance represents a raw content payload along with minimal\ncontextual metadata describing its origin and type.\n\nThis class is the **primary exchange format** between:\n- Scrapers\n- Parsers\n- Downstream consumers\n\nAttributes:\n    raw: Raw content bytes as retrieved from the source.\n    source: Identifier of the content origin (URL, file path, or logical name).\n    content_type: Optional MIME type of the content, if known.\n    metadata: Optional, implementation-defined metadata associated with\n        the content (e.g., headers, encoding hints, extraction notes).",
+            "docstring": "Normalized representation of extracted content.\n\nNotes:\n    **Responsibilities:**\n\n        - A `Content` instance represents a raw content payload along with minimal contextual metadata describing its origin and type\n        - This class is the primary exchange format between Scrapers, Parsers, and Downstream consumers",
             "members": {
               "raw": {
                 "name": "raw",
                 "kind": "attribute",
                 "path": "omniread.core.scraper.Content.raw",
                 "signature": "<bound method Alias.signature of Alias('raw', 'omniread.core.content.Content.raw')>",
-                "docstring": null
+                "docstring": "Raw content bytes as retrieved from the source."
               },
               "source": {
                 "name": "source",
                 "kind": "attribute",
                 "path": "omniread.core.scraper.Content.source",
                 "signature": "<bound method Alias.signature of Alias('source', 'omniread.core.content.Content.source')>",
-                "docstring": null
+                "docstring": "Identifier of the content origin (URL, file path, or logical name)."
               },
               "content_type": {
                 "name": "content_type",
                 "kind": "attribute",
                 "path": "omniread.core.scraper.Content.content_type",
                 "signature": "<bound method Alias.signature of Alias('content_type', 'omniread.core.content.Content.content_type')>",
-                "docstring": null
+                "docstring": "Optional MIME type of the content, if known."
               },
               "metadata": {
                 "name": "metadata",
                 "kind": "attribute",
                 "path": "omniread.core.scraper.Content.metadata",
                 "signature": "<bound method Alias.signature of Alias('metadata', 'omniread.core.content.Content.metadata')>",
-                "docstring": null
+                "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)."
               }
             }
           },
@@ -494,15 +494,15 @@
             "name": "BaseScraper",
             "kind": "class",
             "path": "omniread.core.scraper.BaseScraper",
-            "signature": "<bound method Class.signature of Class('BaseScraper', 26, 75)>",
+            "signature": "<bound method Class.signature of Class('BaseScraper', 30, 76)>",
-            "docstring": "Base interface for all scrapers.\n\nA scraper is responsible ONLY for fetching raw content\n(bytes) from a source. It must not interpret or parse it.\n\nA scraper is a **stateless acquisition component** that retrieves raw\ncontent from a source and returns it as a `Content` object.\n\nScrapers define *how content is obtained*, not *what the content means*.\n\nImplementations may vary in:\n- Transport mechanism (HTTP, filesystem, cloud storage)\n- Authentication strategy\n- Retry and backoff behavior\n\nImplementations must not:\n- Parse content\n- Modify content semantics\n- Couple scraping logic to a specific parser",
+            "docstring": "Base interface for all scrapers.\n\nNotes:\n    **Responsibilities:**\n\n        - A scraper is responsible ONLY for fetching raw content (bytes) from a source. It must not interpret or parse it\n        - A scraper is a stateless acquisition component that retrieves raw content from a source and returns it as a `Content` object\n        - Scrapers define how content is obtained, not what the content means\n        - Implementations may vary in transport mechanism, authentication strategy, retry and backoff behavior\n\n    **Constraints:**\n\n        - Implementations must not parse content, modify content semantics, or couple scraping logic to a specific parser",
             "members": {
               "fetch": {
                 "name": "fetch",
                 "kind": "function",
                 "path": "omniread.core.scraper.BaseScraper.fetch",
-                "signature": "<bound method Function.signature of Function('fetch', 49, 75)>",
+                "signature": "<bound method Function.signature of Function('fetch', 47, 76)>",
-                "docstring": "Fetch raw content from the given source.\n\nImplementations must retrieve the content referenced by `source`\nand return it as raw bytes wrapped in a `Content` object.\n\nArgs:\n    source: Location identifier (URL, file path, S3 URI, etc.)\n    metadata: Optional hints for the scraper (headers, auth, etc.)\n\nReturns:\n    Content object containing raw bytes and metadata.\n    - Raw content bytes\n    - Source identifier\n    - Optional metadata\n\nRaises:\n    Exception: Retrieval-specific errors as defined by the implementation."
+                "docstring": "Fetch raw content from the given source.\n\nArgs:\n    source (str):\n        Location identifier (URL, file path, S3 URI, etc.)\n    metadata (Optional[Mapping[str, Any]], optional):\n        Optional hints for the scraper (headers, auth, etc.)\n\nReturns:\n    Content:\n        Content object containing raw bytes and metadata.\n\nRaises:\n    Exception:\n        Retrieval-specific errors as defined by the implementation.\n\nNotes:\n    **Responsibilities:**\n\n        - Implementations must retrieve the content referenced by `source` and return it as raw bytes wrapped in a `Content` object"
               }
             }
           }

mcp_docs/modules/omniread.core.parser.json

@@ -2,7 +2,7 @@
   "module": "omniread.core.parser",
   "content": {
     "path": "omniread.core.parser",
-    "docstring": "Abstract parsing contracts for OmniRead.\n\nThis module defines the **format-agnostic parser interface** used to transform\nraw content into structured, typed representations.\n\nParsers are responsible for:\n- Interpreting a single `Content` instance\n- Validating compatibility with the content type\n- Producing a structured output suitable for downstream consumers\n\nParsers are not responsible for:\n- Fetching or acquiring content\n- Performing retries or error recovery\n- Managing multiple content sources",
+    "docstring": "Abstract parsing contracts for OmniRead.\n\n---\n\n## Summary\n\nThis module defines the **format-agnostic parser interface** used to transform\nraw content into structured, typed representations.\n\nParsers are responsible for:\n- Interpreting a single `Content` instance\n- Validating compatibility with the content type\n- Producing a structured output suitable for downstream consumers\n\nParsers are not responsible for:\n- Fetching or acquiring content\n- Performing retries or error recovery\n- Managing multiple content sources",
     "objects": {
       "ABC": {
         "name": "ABC",
@@ -44,35 +44,35 @@
         "kind": "class",
         "path": "omniread.core.parser.Content",
         "signature": "<bound method Alias.signature of Alias('Content', 'omniread.core.content.Content')>",
-        "docstring": "Normalized representation of extracted content.\n\nA `Content` instance represents a raw content payload along with minimal\ncontextual metadata describing its origin and type.\n\nThis class is the **primary exchange format** between:\n- Scrapers\n- Parsers\n- Downstream consumers\n\nAttributes:\n    raw: Raw content bytes as retrieved from the source.\n    source: Identifier of the content origin (URL, file path, or logical name).\n    content_type: Optional MIME type of the content, if known.\n    metadata: Optional, implementation-defined metadata associated with\n        the content (e.g., headers, encoding hints, extraction notes).",
+        "docstring": "Normalized representation of extracted content.\n\nNotes:\n    **Responsibilities:**\n\n        - A `Content` instance represents a raw content payload along with minimal contextual metadata describing its origin and type\n        - This class is the primary exchange format between Scrapers, Parsers, and Downstream consumers",
         "members": {
           "raw": {
             "name": "raw",
             "kind": "attribute",
             "path": "omniread.core.parser.Content.raw",
             "signature": "<bound method Alias.signature of Alias('raw', 'omniread.core.content.Content.raw')>",
-            "docstring": null
+            "docstring": "Raw content bytes as retrieved from the source."
           },
           "source": {
             "name": "source",
             "kind": "attribute",
             "path": "omniread.core.parser.Content.source",
             "signature": "<bound method Alias.signature of Alias('source', 'omniread.core.content.Content.source')>",
-            "docstring": null
+            "docstring": "Identifier of the content origin (URL, file path, or logical name)."
           },
           "content_type": {
             "name": "content_type",
             "kind": "attribute",
             "path": "omniread.core.parser.Content.content_type",
             "signature": "<bound method Alias.signature of Alias('content_type', 'omniread.core.content.Content.content_type')>",
-            "docstring": null
+            "docstring": "Optional MIME type of the content, if known."
           },
           "metadata": {
             "name": "metadata",
             "kind": "attribute",
             "path": "omniread.core.parser.Content.metadata",
             "signature": "<bound method Alias.signature of Alias('metadata', 'omniread.core.content.Content.metadata')>",
-            "docstring": null
+            "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)."
           }
         }
       },
@@ -81,7 +81,7 @@
         "kind": "class",
         "path": "omniread.core.parser.ContentType",
         "signature": "<bound method Alias.signature of Alias('ContentType', 'omniread.core.content.ContentType')>",
-        "docstring": "Supported MIME types for extracted content.\n\nThis enum represents the declared or inferred media type of the content\nsource. It is primarily used for routing content to the appropriate\nparser or downstream consumer.",
+        "docstring": "Supported MIME types for extracted content.\n\nNotes:\n    **Guarantees:**\n\n        - This enum represents the declared or inferred media type of the content source\n        - It is primarily used for routing content to the appropriate parser or downstream consumer",
         "members": {
           "HTML": {
             "name": "HTML",
@@ -124,15 +124,15 @@
         "name": "BaseParser",
         "kind": "class",
         "path": "omniread.core.parser.BaseParser",
-        "signature": "<bound method Class.signature of Class('BaseParser', 26, 98)>",
+        "signature": "<bound method Class.signature of Class('BaseParser', 30, 108)>",
-        "docstring": "Base interface for all parsers.\n\nA parser is a self-contained object that owns the Content\nit is responsible for interpreting.\n\nImplementations must:\n- Declare supported content types via `supported_types`\n- Raise parsing-specific exceptions from `parse()`\n- Remain deterministic for a given input\n\nConsumers may rely on:\n- Early validation of content compatibility\n- Type-stable return values from `parse()`",
+        "docstring": "Base interface for all parsers.\n\nNotes:\n    **Guarantees:**\n\n        - A parser is a self-contained object that owns the Content it is responsible for interpreting\n        - Consumers may rely on early validation of content compatibility and type-stable return values from `parse()`\n\n    **Responsibilities:**\n\n        - Implementations must declare supported content types via `supported_types`\n        - Implementations must raise parsing-specific exceptions from `parse()`\n        - Implementations must remain deterministic for a given input",
         "members": {
           "supported_types": {
             "name": "supported_types",
             "kind": "attribute",
             "path": "omniread.core.parser.BaseParser.supported_types",
             "signature": null,
-            "docstring": "Set of content types supported by this parser.\n\nAn empty set indicates that the parser is content-type agnostic."
+            "docstring": "Set of content types supported by this parser. An empty set indicates that the parser is content-type agnostic."
           },
           "content": {
             "name": "content",
@@ -145,15 +145,15 @@
             "name": "parse",
             "kind": "function",
             "path": "omniread.core.parser.BaseParser.parse",
-            "signature": "<bound method Function.signature of Function('parse', 68, 82)>",
+            "signature": "<bound method Function.signature of Function('parse', 73, 91)>",
-            "docstring": "Parse the owned content into structured output.\n\nImplementations must fully consume the provided content and\nreturn a deterministic, structured output.\n\nReturns:\n    Parsed, structured representation.\n\nRaises:\n    Exception: Parsing-specific errors as defined by the implementation."
+            "docstring": "Parse the owned content into structured output.\n\nReturns:\n    T:\n        Parsed, structured representation.\n\nRaises:\n    Exception:\n        Parsing-specific errors as defined by the implementation.\n\nNotes:\n    **Responsibilities:**\n\n        - Implementations must fully consume the provided content and return a deterministic, structured output"
           },
           "supports": {
             "name": "supports",
             "kind": "function",
             "path": "omniread.core.parser.BaseParser.supports",
-            "signature": "<bound method Function.signature of Function('supports', 84, 98)>",
+            "signature": "<bound method Function.signature of Function('supports', 93, 108)>",
-            "docstring": "Check whether this parser supports the content's type.\n\nReturns:\n    True if the content type is supported; False otherwise."
+            "docstring": "Check whether this parser supports the content's type.\n\nReturns:\n    bool:\n        True if the content type is supported; False otherwise."
           }
         }
       }

mcp_docs/modules/omniread.core.scraper.json

@@ -2,7 +2,7 @@
   "module": "omniread.core.scraper",
   "content": {
     "path": "omniread.core.scraper",
-    "docstring": "Abstract scraping contracts for OmniRead.\n\nThis module defines the **format-agnostic scraper interface** responsible for\nacquiring raw content from external sources.\n\nScrapers are responsible for:\n- Locating and retrieving raw content bytes\n- Attaching minimal contextual metadata\n- Returning normalized `Content` objects\n\nScrapers are explicitly NOT responsible for:\n- Parsing or interpreting content\n- Inferring structure or semantics\n- Performing content-type specific processing\n\nAll interpretation must be delegated to parsers.",
+    "docstring": "Abstract scraping contracts for OmniRead.\n\n---\n\n## Summary\n\nThis module defines the **format-agnostic scraper interface** responsible for\nacquiring raw content from external sources.\n\nScrapers are responsible for:\n- Locating and retrieving raw content bytes\n- Attaching minimal contextual metadata\n- Returning normalized `Content` objects\n\nScrapers are explicitly NOT responsible for:\n- Parsing or interpreting content\n- Inferring structure or semantics\n- Performing content-type specific processing\n\nAll interpretation must be delegated to parsers.",
     "objects": {
       "ABC": {
         "name": "ABC",
@@ -44,35 +44,35 @@
         "kind": "class",
         "path": "omniread.core.scraper.Content",
         "signature": "<bound method Alias.signature of Alias('Content', 'omniread.core.content.Content')>",
-        "docstring": "Normalized representation of extracted content.\n\nA `Content` instance represents a raw content payload along with minimal\ncontextual metadata describing its origin and type.\n\nThis class is the **primary exchange format** between:\n- Scrapers\n- Parsers\n- Downstream consumers\n\nAttributes:\n    raw: Raw content bytes as retrieved from the source.\n    source: Identifier of the content origin (URL, file path, or logical name).\n    content_type: Optional MIME type of the content, if known.\n    metadata: Optional, implementation-defined metadata associated with\n        the content (e.g., headers, encoding hints, extraction notes).",
+        "docstring": "Normalized representation of extracted content.\n\nNotes:\n    **Responsibilities:**\n\n        - A `Content` instance represents a raw content payload along with minimal contextual metadata describing its origin and type\n        - This class is the primary exchange format between Scrapers, Parsers, and Downstream consumers",
         "members": {
           "raw": {
             "name": "raw",
             "kind": "attribute",
             "path": "omniread.core.scraper.Content.raw",
             "signature": "<bound method Alias.signature of Alias('raw', 'omniread.core.content.Content.raw')>",
-            "docstring": null
+            "docstring": "Raw content bytes as retrieved from the source."
           },
           "source": {
             "name": "source",
             "kind": "attribute",
             "path": "omniread.core.scraper.Content.source",
             "signature": "<bound method Alias.signature of Alias('source', 'omniread.core.content.Content.source')>",
-            "docstring": null
+            "docstring": "Identifier of the content origin (URL, file path, or logical name)."
           },
           "content_type": {
             "name": "content_type",
             "kind": "attribute",
             "path": "omniread.core.scraper.Content.content_type",
             "signature": "<bound method Alias.signature of Alias('content_type', 'omniread.core.content.Content.content_type')>",
-            "docstring": null
+            "docstring": "Optional MIME type of the content, if known."
           },
           "metadata": {
             "name": "metadata",
             "kind": "attribute",
             "path": "omniread.core.scraper.Content.metadata",
             "signature": "<bound method Alias.signature of Alias('metadata', 'omniread.core.content.Content.metadata')>",
-            "docstring": null
+            "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)."
           }
         }
       },
@@ -80,15 +80,15 @@
         "name": "BaseScraper",
         "kind": "class",
         "path": "omniread.core.scraper.BaseScraper",
-        "signature": "<bound method Class.signature of Class('BaseScraper', 26, 75)>",
+        "signature": "<bound method Class.signature of Class('BaseScraper', 30, 76)>",
-        "docstring": "Base interface for all scrapers.\n\nA scraper is responsible ONLY for fetching raw content\n(bytes) from a source. It must not interpret or parse it.\n\nA scraper is a **stateless acquisition component** that retrieves raw\ncontent from a source and returns it as a `Content` object.\n\nScrapers define *how content is obtained*, not *what the content means*.\n\nImplementations may vary in:\n- Transport mechanism (HTTP, filesystem, cloud storage)\n- Authentication strategy\n- Retry and backoff behavior\n\nImplementations must not:\n- Parse content\n- Modify content semantics\n- Couple scraping logic to a specific parser",
+        "docstring": "Base interface for all scrapers.\n\nNotes:\n    **Responsibilities:**\n\n        - A scraper is responsible ONLY for fetching raw content (bytes) from a source. It must not interpret or parse it\n        - A scraper is a stateless acquisition component that retrieves raw content from a source and returns it as a `Content` object\n        - Scrapers define how content is obtained, not what the content means\n        - Implementations may vary in transport mechanism, authentication strategy, retry and backoff behavior\n\n    **Constraints:**\n\n        - Implementations must not parse content, modify content semantics, or couple scraping logic to a specific parser",
         "members": {
           "fetch": {
             "name": "fetch",
             "kind": "function",
             "path": "omniread.core.scraper.BaseScraper.fetch",
-            "signature": "<bound method Function.signature of Function('fetch', 49, 75)>",
+            "signature": "<bound method Function.signature of Function('fetch', 47, 76)>",
-            "docstring": "Fetch raw content from the given source.\n\nImplementations must retrieve the content referenced by `source`\nand return it as raw bytes wrapped in a `Content` object.\n\nArgs:\n    source: Location identifier (URL, file path, S3 URI, etc.)\n    metadata: Optional hints for the scraper (headers, auth, etc.)\n\nReturns:\n    Content object containing raw bytes and metadata.\n    - Raw content bytes\n    - Source identifier\n    - Optional metadata\n\nRaises:\n    Exception: Retrieval-specific errors as defined by the implementation."
+            "docstring": "Fetch raw content from the given source.\n\nArgs:\n    source (str):\n        Location identifier (URL, file path, S3 URI, etc.)\n    metadata (Optional[Mapping[str, Any]], optional):\n        Optional hints for the scraper (headers, auth, etc.)\n\nReturns:\n    Content:\n        Content object containing raw bytes and metadata.\n\nRaises:\n    Exception:\n        Retrieval-specific errors as defined by the implementation.\n\nNotes:\n    **Responsibilities:**\n\n        - Implementations must retrieve the content referenced by `source` and return it as raw bytes wrapped in a `Content` object"
           }
         }
       }

mcp_docs/modules/omniread.html.json

@@ -2,14 +2,14 @@
   "module": "omniread.html",
   "content": {
     "path": "omniread.html",
-    "docstring": "HTML format implementation for OmniRead.\n\nThis package provides **HTML-specific implementations** of the core OmniRead\ncontracts defined in `omniread.core`.\n\nIt includes:\n- HTML parsers that interpret HTML content\n- HTML scrapers that retrieve HTML documents\n\nThis package:\n- Implements, but does not redefine, core contracts\n- May contain HTML-specific behavior and edge-case handling\n- Produces canonical content models defined in `omniread.core.content`\n\nConsumers should depend on `omniread.core` interfaces wherever possible and\nuse this package only when HTML-specific behavior is required.",
+    "docstring": "HTML format implementation for OmniRead.\n\n---\n\n## Summary\n\nThis package provides **HTML-specific implementations** of the core OmniRead\ncontracts defined in `omniread.core`.\n\nIt includes:\n- HTML parsers that interpret HTML content\n- HTML scrapers that retrieve HTML documents\n\nThis package:\n- Implements, but does not redefine, core contracts\n- May contain HTML-specific behavior and edge-case handling\n- Produces canonical content models defined in `omniread.core.content`\n\nConsumers should depend on `omniread.core` interfaces wherever possible and\nuse this package only when HTML-specific behavior is required.\n\n---\n\n## Public API\n\n    HTMLScraper\n    HTMLParser\n\n---",
     "objects": {
       "HTMLScraper": {
         "name": "HTMLScraper",
         "kind": "class",
         "path": "omniread.html.HTMLScraper",
         "signature": "<bound method Alias.signature of Alias('HTMLScraper', 'omniread.html.scraper.HTMLScraper')>",
-        "docstring": "Base HTML scraper using httpx.\n\nThis scraper retrieves HTML documents over HTTP(S) and returns them\nas raw content wrapped in a `Content` object.\n\nFetches raw bytes and metadata only.\nThe scraper:\n- Uses `httpx.Client` for HTTP requests\n- Enforces an HTML content type\n- Preserves HTTP response metadata\n\nThe scraper does not:\n- Parse HTML\n- Perform retries or backoff\n- Handle non-HTML responses",
+        "docstring": "Base HTML scraper using httpx.\n\nNotes:\n    **Responsibilities:**\n\n        - This scraper retrieves HTML documents over HTTP(S) and returns them as raw content wrapped in a `Content` object\n        - Fetches raw bytes and metadata only. The scraper uses `httpx.Client` for HTTP requests, enforces an HTML content type, preserves HTTP response metadata\n\n    **Constraints:**\n    \n        - The scraper does not: Parse HTML, perform retries or backoff, handle non-HTML responses",
         "members": {
           "content_type": {
             "name": "content_type",
@@ -23,14 +23,14 @@
             "kind": "function",
             "path": "omniread.html.HTMLScraper.validate_content_type",
             "signature": "<bound method Alias.signature of Alias('validate_content_type', 'omniread.html.scraper.HTMLScraper.validate_content_type')>",
-            "docstring": "Validate that the HTTP response contains HTML content.\n\nArgs:\n    response: HTTP response returned by `httpx`.\n\nRaises:\n    ValueError: If the `Content-Type` header is missing or does not\n        indicate HTML content."
+            "docstring": "Validate that the HTTP response contains HTML content.\n\nArgs:\n    response (httpx.Response):\n        HTTP response returned by `httpx`.\n\nRaises:\n    ValueError:\n        If the `Content-Type` header is missing or does not indicate HTML content."
           },
           "fetch": {
             "name": "fetch",
             "kind": "function",
             "path": "omniread.html.HTMLScraper.fetch",
             "signature": "<bound method Alias.signature of Alias('fetch', 'omniread.html.scraper.HTMLScraper.fetch')>",
-            "docstring": "Fetch an HTML document from the given source.\n\nArgs:\n    source: URL of the HTML document.\n    metadata: Optional metadata to be merged into the returned content.\n\nReturns:\n    A `Content` instance containing:\n    - Raw HTML bytes\n    - Source URL\n    - HTML content type\n    - HTTP response metadata\n\nRaises:\n    httpx.HTTPError: If the HTTP request fails.\n    ValueError: If the response is not valid HTML."
+            "docstring": "Fetch an HTML document from the given source.\n\nArgs:\n    source (str):\n        URL of the HTML document.\n    metadata (Optional[Mapping[str, Any]], optional):\n        Optional metadata to be merged into the returned content.\n\nReturns:\n    Content:\n        A `Content` instance containing raw HTML bytes, source URL, HTML content type, and HTTP response metadata.\n\nRaises:\n    httpx.HTTPError:\n        If the HTTP request fails.\n    ValueError:\n        If the response is not valid HTML."
           }
         }
       },
@@ -39,7 +39,7 @@
         "kind": "class",
         "path": "omniread.html.HTMLParser",
         "signature": "<bound method Alias.signature of Alias('HTMLParser', 'omniread.html.parser.HTMLParser')>",
-        "docstring": "Base HTML parser.\n\nThis class extends the core `BaseParser` with HTML-specific behavior,\nincluding DOM parsing via BeautifulSoup and reusable extraction helpers.\n\nProvides reusable helpers for HTML extraction.\nConcrete parsers must explicitly define the return type.\n\nCharacteristics:\n- Accepts only HTML content\n- Owns a parsed BeautifulSoup DOM tree\n- Provides pure helper utilities for common HTML structures\n\nConcrete subclasses must:\n- Define the output type `T`\n- Implement the `parse()` method",
+        "docstring": "Base HTML parser.\n\nNotes:\n    **Responsibilities:**\n\n        - This class extends the core `BaseParser` with HTML-specific behavior, including DOM parsing via BeautifulSoup and reusable extraction helpers\n        - Provides reusable helpers for HTML extraction. Concrete parsers must explicitly define the return type\n\n    **Guarantees:**\n\n        - Characteristics: Accepts only HTML content, owns a parsed BeautifulSoup DOM tree, provides pure helper utilities for common HTML structures\n\n    **Constraints:**\n    \n        - Concrete subclasses must define the output type `T` and implement the `parse()` method",
         "members": {
           "supported_types": {
             "name": "supported_types",
@@ -53,35 +53,35 @@
             "kind": "function",
             "path": "omniread.html.HTMLParser.parse",
             "signature": "<bound method Alias.signature of Alias('parse', 'omniread.html.parser.HTMLParser.parse')>",
-            "docstring": "Fully parse the HTML content into structured output.\n\nImplementations must fully interpret the HTML DOM and return\na deterministic, structured output.\n\nReturns:\n    Parsed representation of type `T`."
+            "docstring": "Fully parse the HTML content into structured output.\n\nReturns:\n    T:\n        Parsed representation of type `T`.\n\nNotes:\n    **Responsibilities:**\n\n        - Implementations must fully interpret the HTML DOM and return a deterministic, structured output"
           },
           "parse_div": {
             "name": "parse_div",
             "kind": "function",
             "path": "omniread.html.HTMLParser.parse_div",
             "signature": "<bound method Alias.signature of Alias('parse_div', 'omniread.html.parser.HTMLParser.parse_div')>",
-            "docstring": "Extract normalized text from a `<div>` element.\n\nArgs:\n    div: BeautifulSoup tag representing a `<div>`.\n    separator: String used to separate text nodes.\n\nReturns:\n    Flattened, whitespace-normalized text content."
+            "docstring": "Extract normalized text from a `<div>` element.\n\nArgs:\n    div (Tag):\n        BeautifulSoup tag representing a `<div>`.\n    separator (str, optional):\n        String used to separate text nodes.\n\nReturns:\n    str:\n        Flattened, whitespace-normalized text content."
           },
           "parse_link": {
             "name": "parse_link",
             "kind": "function",
             "path": "omniread.html.HTMLParser.parse_link",
             "signature": "<bound method Alias.signature of Alias('parse_link', 'omniread.html.parser.HTMLParser.parse_link')>",
-            "docstring": "Extract the hyperlink reference from an `<a>` element.\n\nArgs:\n    a: BeautifulSoup tag representing an anchor.\n\nReturns:\n    The value of the `href` attribute, or None if absent."
+            "docstring": "Extract the hyperlink reference from an `<a>` element.\n\nArgs:\n    a (Tag):\n        BeautifulSoup tag representing an anchor.\n\nReturns:\n    Optional[str]:\n        The value of the `href` attribute, or None if absent."
           },
           "parse_table": {
             "name": "parse_table",
             "kind": "function",
             "path": "omniread.html.HTMLParser.parse_table",
             "signature": "<bound method Alias.signature of Alias('parse_table', 'omniread.html.parser.HTMLParser.parse_table')>",
-            "docstring": "Parse an HTML table into a 2D list of strings.\n\nArgs:\n    table: BeautifulSoup tag representing a `<table>`.\n\nReturns:\n    A list of rows, where each row is a list of cell text values."
+            "docstring": "Parse an HTML table into a 2D list of strings.\n\nArgs:\n    table (Tag):\n        BeautifulSoup tag representing a `<table>`.\n\nReturns:\n    list[list[str]]:\n        A list of rows, where each row is a list of cell text values."
           },
           "parse_meta": {
             "name": "parse_meta",
             "kind": "function",
             "path": "omniread.html.HTMLParser.parse_meta",
             "signature": "<bound method Alias.signature of Alias('parse_meta', 'omniread.html.parser.HTMLParser.parse_meta')>",
-            "docstring": "Extract high-level metadata from the HTML document.\n\nThis includes:\n- Document title\n- `<meta>` tag name/property → content mappings\n\nReturns:\n    Dictionary containing extracted metadata."
+            "docstring": "Extract high-level metadata from the HTML document.\n\nReturns:\n    dict[str, Any]:\n        Dictionary containing extracted metadata.\n\nNotes:\n    **Responsibilities:**\n\n        - Extract high-level metadata from the HTML document\n        - This includes: Document title, `<meta>` tag name/property → content mappings"
           }
         }
       },
@@ -90,7 +90,7 @@
         "kind": "module",
         "path": "omniread.html.parser",
         "signature": null,
-        "docstring": "HTML parser base implementations for OmniRead.\n\nThis module provides reusable HTML parsing utilities built on top of\nthe abstract parser contracts defined in `omniread.core.parser`.\n\nIt supplies:\n- Content-type enforcement for HTML inputs\n- BeautifulSoup initialization and lifecycle management\n- Common helper methods for extracting structured data from HTML elements\n\nConcrete parsers must subclass `HTMLParser` and implement the `parse()` method\nto return a structured representation appropriate for their use case.",
+        "docstring": "HTML parser base implementations for OmniRead.\n\n---\n\n## Summary\n\nThis module provides reusable HTML parsing utilities built on top of\nthe abstract parser contracts defined in `omniread.core.parser`.\n\nIt supplies:\n- Content-type enforcement for HTML inputs\n- BeautifulSoup initialization and lifecycle management\n- Common helper methods for extracting structured data from HTML elements\n\nConcrete parsers must subclass `HTMLParser` and implement the `parse()` method\nto return a structured representation appropriate for their use case.",
         "members": {
           "Any": {
             "name": "Any",
@@ -146,7 +146,7 @@
             "kind": "class",
             "path": "omniread.html.parser.ContentType",
             "signature": "<bound method Alias.signature of Alias('ContentType', 'omniread.core.content.ContentType')>",
-            "docstring": "Supported MIME types for extracted content.\n\nThis enum represents the declared or inferred media type of the content\nsource. It is primarily used for routing content to the appropriate\nparser or downstream consumer.",
+            "docstring": "Supported MIME types for extracted content.\n\nNotes:\n    **Guarantees:**\n\n        - This enum represents the declared or inferred media type of the content source\n        - It is primarily used for routing content to the appropriate parser or downstream consumer",
             "members": {
               "HTML": {
                 "name": "HTML",
@@ -183,35 +183,35 @@
             "kind": "class",
             "path": "omniread.html.parser.Content",
             "signature": "<bound method Alias.signature of Alias('Content', 'omniread.core.content.Content')>",
-            "docstring": "Normalized representation of extracted content.\n\nA `Content` instance represents a raw content payload along with minimal\ncontextual metadata describing its origin and type.\n\nThis class is the **primary exchange format** between:\n- Scrapers\n- Parsers\n- Downstream consumers\n\nAttributes:\n    raw: Raw content bytes as retrieved from the source.\n    source: Identifier of the content origin (URL, file path, or logical name).\n    content_type: Optional MIME type of the content, if known.\n    metadata: Optional, implementation-defined metadata associated with\n        the content (e.g., headers, encoding hints, extraction notes).",
+            "docstring": "Normalized representation of extracted content.\n\nNotes:\n    **Responsibilities:**\n\n        - A `Content` instance represents a raw content payload along with minimal contextual metadata describing its origin and type\n        - This class is the primary exchange format between Scrapers, Parsers, and Downstream consumers",
             "members": {
               "raw": {
                 "name": "raw",
                 "kind": "attribute",
                 "path": "omniread.html.parser.Content.raw",
                 "signature": "<bound method Alias.signature of Alias('raw', 'omniread.core.content.Content.raw')>",
-                "docstring": null
+                "docstring": "Raw content bytes as retrieved from the source."
               },
               "source": {
                 "name": "source",
                 "kind": "attribute",
                 "path": "omniread.html.parser.Content.source",
                 "signature": "<bound method Alias.signature of Alias('source', 'omniread.core.content.Content.source')>",
-                "docstring": null
+                "docstring": "Identifier of the content origin (URL, file path, or logical name)."
               },
               "content_type": {
                 "name": "content_type",
                 "kind": "attribute",
                 "path": "omniread.html.parser.Content.content_type",
                 "signature": "<bound method Alias.signature of Alias('content_type', 'omniread.core.content.Content.content_type')>",
-                "docstring": null
+                "docstring": "Optional MIME type of the content, if known."
               },
               "metadata": {
                 "name": "metadata",
                 "kind": "attribute",
                 "path": "omniread.html.parser.Content.metadata",
                 "signature": "<bound method Alias.signature of Alias('metadata', 'omniread.core.content.Content.metadata')>",
-                "docstring": null
+                "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)."
               }
             }
           },
@@ -220,14 +220,14 @@
             "kind": "class",
             "path": "omniread.html.parser.BaseParser",
             "signature": "<bound method Alias.signature of Alias('BaseParser', 'omniread.core.parser.BaseParser')>",
-            "docstring": "Base interface for all parsers.\n\nA parser is a self-contained object that owns the Content\nit is responsible for interpreting.\n\nImplementations must:\n- Declare supported content types via `supported_types`\n- Raise parsing-specific exceptions from `parse()`\n- Remain deterministic for a given input\n\nConsumers may rely on:\n- Early validation of content compatibility\n- Type-stable return values from `parse()`",
+            "docstring": "Base interface for all parsers.\n\nNotes:\n    **Guarantees:**\n\n        - A parser is a self-contained object that owns the Content it is responsible for interpreting\n        - Consumers may rely on early validation of content compatibility and type-stable return values from `parse()`\n\n    **Responsibilities:**\n\n        - Implementations must declare supported content types via `supported_types`\n        - Implementations must raise parsing-specific exceptions from `parse()`\n        - Implementations must remain deterministic for a given input",
             "members": {
               "supported_types": {
                 "name": "supported_types",
                 "kind": "attribute",
                 "path": "omniread.html.parser.BaseParser.supported_types",
                 "signature": "<bound method Alias.signature of Alias('supported_types', 'omniread.core.parser.BaseParser.supported_types')>",
-                "docstring": "Set of content types supported by this parser.\n\nAn empty set indicates that the parser is content-type agnostic."
+                "docstring": "Set of content types supported by this parser. An empty set indicates that the parser is content-type agnostic."
               },
               "content": {
                 "name": "content",
@@ -241,14 +241,14 @@
                 "kind": "function",
                 "path": "omniread.html.parser.BaseParser.parse",
                 "signature": "<bound method Alias.signature of Alias('parse', 'omniread.core.parser.BaseParser.parse')>",
-                "docstring": "Parse the owned content into structured output.\n\nImplementations must fully consume the provided content and\nreturn a deterministic, structured output.\n\nReturns:\n    Parsed, structured representation.\n\nRaises:\n    Exception: Parsing-specific errors as defined by the implementation."
+                "docstring": "Parse the owned content into structured output.\n\nReturns:\n    T:\n        Parsed, structured representation.\n\nRaises:\n    Exception:\n        Parsing-specific errors as defined by the implementation.\n\nNotes:\n    **Responsibilities:**\n\n        - Implementations must fully consume the provided content and return a deterministic, structured output"
               },
               "supports": {
                 "name": "supports",
                 "kind": "function",
                 "path": "omniread.html.parser.BaseParser.supports",
                 "signature": "<bound method Alias.signature of Alias('supports', 'omniread.core.parser.BaseParser.supports')>",
-                "docstring": "Check whether this parser supports the content's type.\n\nReturns:\n    True if the content type is supported; False otherwise."
+                "docstring": "Check whether this parser supports the content's type.\n\nReturns:\n    bool:\n        True if the content type is supported; False otherwise."
               }
             }
           },
@@ -263,8 +263,8 @@
             "name": "HTMLParser",
             "kind": "class",
             "path": "omniread.html.parser.HTMLParser",
-            "signature": "<bound method Class.signature of Class('HTMLParser', 27, 177)>",
+            "signature": "<bound method Class.signature of Class('HTMLParser', 31, 199)>",
-            "docstring": "Base HTML parser.\n\nThis class extends the core `BaseParser` with HTML-specific behavior,\nincluding DOM parsing via BeautifulSoup and reusable extraction helpers.\n\nProvides reusable helpers for HTML extraction.\nConcrete parsers must explicitly define the return type.\n\nCharacteristics:\n- Accepts only HTML content\n- Owns a parsed BeautifulSoup DOM tree\n- Provides pure helper utilities for common HTML structures\n\nConcrete subclasses must:\n- Define the output type `T`\n- Implement the `parse()` method",
+            "docstring": "Base HTML parser.\n\nNotes:\n    **Responsibilities:**\n\n        - This class extends the core `BaseParser` with HTML-specific behavior, including DOM parsing via BeautifulSoup and reusable extraction helpers\n        - Provides reusable helpers for HTML extraction. Concrete parsers must explicitly define the return type\n\n    **Guarantees:**\n\n        - Characteristics: Accepts only HTML content, owns a parsed BeautifulSoup DOM tree, provides pure helper utilities for common HTML structures\n\n    **Constraints:**\n    \n        - Concrete subclasses must define the output type `T` and implement the `parse()` method",
             "members": {
               "supported_types": {
                 "name": "supported_types",
@@ -277,36 +277,36 @@
                 "name": "parse",
                 "kind": "function",
                 "path": "omniread.html.parser.HTMLParser.parse",
-                "signature": "<bound method Function.signature of Function('parse', 70, 81)>",
+                "signature": "<bound method Function.signature of Function('parse', 77, 91)>",
-                "docstring": "Fully parse the HTML content into structured output.\n\nImplementations must fully interpret the HTML DOM and return\na deterministic, structured output.\n\nReturns:\n    Parsed representation of type `T`."
+                "docstring": "Fully parse the HTML content into structured output.\n\nReturns:\n    T:\n        Parsed representation of type `T`.\n\nNotes:\n    **Responsibilities:**\n\n        - Implementations must fully interpret the HTML DOM and return a deterministic, structured output"
               },
               "parse_div": {
                 "name": "parse_div",
                 "kind": "function",
                 "path": "omniread.html.parser.HTMLParser.parse_div",
-                "signature": "<bound method Function.signature of Function('parse_div', 87, 99)>",
+                "signature": "<bound method Function.signature of Function('parse_div', 97, 112)>",
-                "docstring": "Extract normalized text from a `<div>` element.\n\nArgs:\n    div: BeautifulSoup tag representing a `<div>`.\n    separator: String used to separate text nodes.\n\nReturns:\n    Flattened, whitespace-normalized text content."
+                "docstring": "Extract normalized text from a `<div>` element.\n\nArgs:\n    div (Tag):\n        BeautifulSoup tag representing a `<div>`.\n    separator (str, optional):\n        String used to separate text nodes.\n\nReturns:\n    str:\n        Flattened, whitespace-normalized text content."
               },
               "parse_link": {
                 "name": "parse_link",
                 "kind": "function",
                 "path": "omniread.html.parser.HTMLParser.parse_link",
-                "signature": "<bound method Function.signature of Function('parse_link', 101, 112)>",
+                "signature": "<bound method Function.signature of Function('parse_link', 114, 127)>",
-                "docstring": "Extract the hyperlink reference from an `<a>` element.\n\nArgs:\n    a: BeautifulSoup tag representing an anchor.\n\nReturns:\n    The value of the `href` attribute, or None if absent."
+                "docstring": "Extract the hyperlink reference from an `<a>` element.\n\nArgs:\n    a (Tag):\n        BeautifulSoup tag representing an anchor.\n\nReturns:\n    Optional[str]:\n        The value of the `href` attribute, or None if absent."
               },
               "parse_table": {
                 "name": "parse_table",
                 "kind": "function",
                 "path": "omniread.html.parser.HTMLParser.parse_table",
-                "signature": "<bound method Function.signature of Function('parse_table', 114, 133)>",
+                "signature": "<bound method Function.signature of Function('parse_table', 129, 150)>",
-                "docstring": "Parse an HTML table into a 2D list of strings.\n\nArgs:\n    table: BeautifulSoup tag representing a `<table>`.\n\nReturns:\n    A list of rows, where each row is a list of cell text values."
+                "docstring": "Parse an HTML table into a 2D list of strings.\n\nArgs:\n    table (Tag):\n        BeautifulSoup tag representing a `<table>`.\n\nReturns:\n    list[list[str]]:\n        A list of rows, where each row is a list of cell text values."
               },
               "parse_meta": {
                 "name": "parse_meta",
                 "kind": "function",
                 "path": "omniread.html.parser.HTMLParser.parse_meta",
-                "signature": "<bound method Function.signature of Function('parse_meta', 153, 177)>",
+                "signature": "<bound method Function.signature of Function('parse_meta', 172, 199)>",
-                "docstring": "Extract high-level metadata from the HTML document.\n\nThis includes:\n- Document title\n- `<meta>` tag name/property → content mappings\n\nReturns:\n    Dictionary containing extracted metadata."
+                "docstring": "Extract high-level metadata from the HTML document.\n\nReturns:\n    dict[str, Any]:\n        Dictionary containing extracted metadata.\n\nNotes:\n    **Responsibilities:**\n\n        - Extract high-level metadata from the HTML document\n        - This includes: Document title, `<meta>` tag name/property → content mappings"
               }
             }
           },
@@ -331,7 +331,7 @@
         "kind": "module",
         "path": "omniread.html.scraper",
         "signature": null,
-        "docstring": "HTML scraping implementation for OmniRead.\n\nThis module provides an HTTP-based scraper for retrieving HTML documents.\nIt implements the core `BaseScraper` contract using `httpx` as the transport\nlayer.\n\nThis scraper is responsible for:\n- Fetching raw HTML bytes over HTTP(S)\n- Validating response content type\n- Attaching HTTP metadata to the returned content\n\nThis scraper is not responsible for:\n- Parsing or interpreting HTML\n- Retrying failed requests\n- Managing crawl policies or rate limiting",
+        "docstring": "HTML scraping implementation for OmniRead.\n\n---\n\n## Summary\n\nThis module provides an HTTP-based scraper for retrieving HTML documents.\nIt implements the core `BaseScraper` contract using `httpx` as the transport\nlayer.\n\nThis scraper is responsible for:\n- Fetching raw HTML bytes over HTTP(S)\n- Validating response content type\n- Attaching HTTP metadata to the returned content\n\nThis scraper is not responsible for:\n- Parsing or interpreting HTML\n- Retrying failed requests\n- Managing crawl policies or rate limiting",
         "members": {
           "httpx": {
             "name": "httpx",
@@ -366,35 +366,35 @@
             "kind": "class",
             "path": "omniread.html.scraper.Content",
             "signature": "<bound method Alias.signature of Alias('Content', 'omniread.core.content.Content')>",
-            "docstring": "Normalized representation of extracted content.\n\nA `Content` instance represents a raw content payload along with minimal\ncontextual metadata describing its origin and type.\n\nThis class is the **primary exchange format** between:\n- Scrapers\n- Parsers\n- Downstream consumers\n\nAttributes:\n    raw: Raw content bytes as retrieved from the source.\n    source: Identifier of the content origin (URL, file path, or logical name).\n    content_type: Optional MIME type of the content, if known.\n    metadata: Optional, implementation-defined metadata associated with\n        the content (e.g., headers, encoding hints, extraction notes).",
+            "docstring": "Normalized representation of extracted content.\n\nNotes:\n    **Responsibilities:**\n\n        - A `Content` instance represents a raw content payload along with minimal contextual metadata describing its origin and type\n        - This class is the primary exchange format between Scrapers, Parsers, and Downstream consumers",
             "members": {
               "raw": {
                 "name": "raw",
                 "kind": "attribute",
                 "path": "omniread.html.scraper.Content.raw",
                 "signature": "<bound method Alias.signature of Alias('raw', 'omniread.core.content.Content.raw')>",
-                "docstring": null
+                "docstring": "Raw content bytes as retrieved from the source."
               },
               "source": {
                 "name": "source",
                 "kind": "attribute",
                 "path": "omniread.html.scraper.Content.source",
                 "signature": "<bound method Alias.signature of Alias('source', 'omniread.core.content.Content.source')>",
-                "docstring": null
+                "docstring": "Identifier of the content origin (URL, file path, or logical name)."
               },
               "content_type": {
                 "name": "content_type",
                 "kind": "attribute",
                 "path": "omniread.html.scraper.Content.content_type",
                 "signature": "<bound method Alias.signature of Alias('content_type', 'omniread.core.content.Content.content_type')>",
-                "docstring": null
+                "docstring": "Optional MIME type of the content, if known."
               },
               "metadata": {
                 "name": "metadata",
                 "kind": "attribute",
                 "path": "omniread.html.scraper.Content.metadata",
                 "signature": "<bound method Alias.signature of Alias('metadata', 'omniread.core.content.Content.metadata')>",
-                "docstring": null
+                "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)."
               }
             }
           },
@@ -403,7 +403,7 @@
             "kind": "class",
             "path": "omniread.html.scraper.ContentType",
             "signature": "<bound method Alias.signature of Alias('ContentType', 'omniread.core.content.ContentType')>",
-            "docstring": "Supported MIME types for extracted content.\n\nThis enum represents the declared or inferred media type of the content\nsource. It is primarily used for routing content to the appropriate\nparser or downstream consumer.",
+            "docstring": "Supported MIME types for extracted content.\n\nNotes:\n    **Guarantees:**\n\n        - This enum represents the declared or inferred media type of the content source\n        - It is primarily used for routing content to the appropriate parser or downstream consumer",
             "members": {
               "HTML": {
                 "name": "HTML",
@@ -440,14 +440,14 @@
             "kind": "class",
             "path": "omniread.html.scraper.BaseScraper",
             "signature": "<bound method Alias.signature of Alias('BaseScraper', 'omniread.core.scraper.BaseScraper')>",
-            "docstring": "Base interface for all scrapers.\n\nA scraper is responsible ONLY for fetching raw content\n(bytes) from a source. It must not interpret or parse it.\n\nA scraper is a **stateless acquisition component** that retrieves raw\ncontent from a source and returns it as a `Content` object.\n\nScrapers define *how content is obtained*, not *what the content means*.\n\nImplementations may vary in:\n- Transport mechanism (HTTP, filesystem, cloud storage)\n- Authentication strategy\n- Retry and backoff behavior\n\nImplementations must not:\n- Parse content\n- Modify content semantics\n- Couple scraping logic to a specific parser",
+            "docstring": "Base interface for all scrapers.\n\nNotes:\n    **Responsibilities:**\n\n        - A scraper is responsible ONLY for fetching raw content (bytes) from a source. It must not interpret or parse it\n        - A scraper is a stateless acquisition component that retrieves raw content from a source and returns it as a `Content` object\n        - Scrapers define how content is obtained, not what the content means\n        - Implementations may vary in transport mechanism, authentication strategy, retry and backoff behavior\n\n    **Constraints:**\n\n        - Implementations must not parse content, modify content semantics, or couple scraping logic to a specific parser",
             "members": {
               "fetch": {
                 "name": "fetch",
                 "kind": "function",
                 "path": "omniread.html.scraper.BaseScraper.fetch",
                 "signature": "<bound method Alias.signature of Alias('fetch', 'omniread.core.scraper.BaseScraper.fetch')>",
-                "docstring": "Fetch raw content from the given source.\n\nImplementations must retrieve the content referenced by `source`\nand return it as raw bytes wrapped in a `Content` object.\n\nArgs:\n    source: Location identifier (URL, file path, S3 URI, etc.)\n    metadata: Optional hints for the scraper (headers, auth, etc.)\n\nReturns:\n    Content object containing raw bytes and metadata.\n    - Raw content bytes\n    - Source identifier\n    - Optional metadata\n\nRaises:\n    Exception: Retrieval-specific errors as defined by the implementation."
+                "docstring": "Fetch raw content from the given source.\n\nArgs:\n    source (str):\n        Location identifier (URL, file path, S3 URI, etc.)\n    metadata (Optional[Mapping[str, Any]], optional):\n        Optional hints for the scraper (headers, auth, etc.)\n\nReturns:\n    Content:\n        Content object containing raw bytes and metadata.\n\nRaises:\n    Exception:\n        Retrieval-specific errors as defined by the implementation.\n\nNotes:\n    **Responsibilities:**\n\n        - Implementations must retrieve the content referenced by `source` and return it as raw bytes wrapped in a `Content` object"
               }
             }
           },
@@ -455,8 +455,8 @@
             "name": "HTMLScraper",
             "kind": "class",
             "path": "omniread.html.scraper.HTMLScraper",
-            "signature": "<bound method Class.signature of Class('HTMLScraper', 26, 134)>",
+            "signature": "<bound method Class.signature of Class('HTMLScraper', 30, 139)>",
-            "docstring": "Base HTML scraper using httpx.\n\nThis scraper retrieves HTML documents over HTTP(S) and returns them\nas raw content wrapped in a `Content` object.\n\nFetches raw bytes and metadata only.\nThe scraper:\n- Uses `httpx.Client` for HTTP requests\n- Enforces an HTML content type\n- Preserves HTTP response metadata\n\nThe scraper does not:\n- Parse HTML\n- Perform retries or backoff\n- Handle non-HTML responses",
+            "docstring": "Base HTML scraper using httpx.\n\nNotes:\n    **Responsibilities:**\n\n        - This scraper retrieves HTML documents over HTTP(S) and returns them as raw content wrapped in a `Content` object\n        - Fetches raw bytes and metadata only. The scraper uses `httpx.Client` for HTTP requests, enforces an HTML content type, preserves HTTP response metadata\n\n    **Constraints:**\n    \n        - The scraper does not: Parse HTML, perform retries or backoff, handle non-HTML responses",
             "members": {
               "content_type": {
                 "name": "content_type",
@@ -469,15 +469,15 @@
                 "name": "validate_content_type",
                 "kind": "function",
                 "path": "omniread.html.scraper.HTMLScraper.validate_content_type",
-                "signature": "<bound method Function.signature of Function('validate_content_type', 71, 94)>",
+                "signature": "<bound method Function.signature of Function('validate_content_type', 74, 98)>",
-                "docstring": "Validate that the HTTP response contains HTML content.\n\nArgs:\n    response: HTTP response returned by `httpx`.\n\nRaises:\n    ValueError: If the `Content-Type` header is missing or does not\n        indicate HTML content."
+                "docstring": "Validate that the HTTP response contains HTML content.\n\nArgs:\n    response (httpx.Response):\n        HTTP response returned by `httpx`.\n\nRaises:\n    ValueError:\n        If the `Content-Type` header is missing or does not indicate HTML content."
               },
               "fetch": {
                 "name": "fetch",
                 "kind": "function",
                 "path": "omniread.html.scraper.HTMLScraper.fetch",
-                "signature": "<bound method Function.signature of Function('fetch', 96, 134)>",
+                "signature": "<bound method Function.signature of Function('fetch', 100, 139)>",
-                "docstring": "Fetch an HTML document from the given source.\n\nArgs:\n    source: URL of the HTML document.\n    metadata: Optional metadata to be merged into the returned content.\n\nReturns:\n    A `Content` instance containing:\n    - Raw HTML bytes\n    - Source URL\n    - HTML content type\n    - HTTP response metadata\n\nRaises:\n    httpx.HTTPError: If the HTTP request fails.\n    ValueError: If the response is not valid HTML."
+                "docstring": "Fetch an HTML document from the given source.\n\nArgs:\n    source (str):\n        URL of the HTML document.\n    metadata (Optional[Mapping[str, Any]], optional):\n        Optional metadata to be merged into the returned content.\n\nReturns:\n    Content:\n        A `Content` instance containing raw HTML bytes, source URL, HTML content type, and HTTP response metadata.\n\nRaises:\n    httpx.HTTPError:\n        If the HTTP request fails.\n    ValueError:\n        If the response is not valid HTML."
               }
             }
           }

mcp_docs/modules/omniread.html.parser.json

@@ -2,7 +2,7 @@
   "module": "omniread.html.parser",
   "content": {
     "path": "omniread.html.parser",
-    "docstring": "HTML parser base implementations for OmniRead.\n\nThis module provides reusable HTML parsing utilities built on top of\nthe abstract parser contracts defined in `omniread.core.parser`.\n\nIt supplies:\n- Content-type enforcement for HTML inputs\n- BeautifulSoup initialization and lifecycle management\n- Common helper methods for extracting structured data from HTML elements\n\nConcrete parsers must subclass `HTMLParser` and implement the `parse()` method\nto return a structured representation appropriate for their use case.",
+    "docstring": "HTML parser base implementations for OmniRead.\n\n---\n\n## Summary\n\nThis module provides reusable HTML parsing utilities built on top of\nthe abstract parser contracts defined in `omniread.core.parser`.\n\nIt supplies:\n- Content-type enforcement for HTML inputs\n- BeautifulSoup initialization and lifecycle management\n- Common helper methods for extracting structured data from HTML elements\n\nConcrete parsers must subclass `HTMLParser` and implement the `parse()` method\nto return a structured representation appropriate for their use case.",
     "objects": {
       "Any": {
         "name": "Any",
@@ -58,7 +58,7 @@
         "kind": "class",
         "path": "omniread.html.parser.ContentType",
         "signature": "<bound method Alias.signature of Alias('ContentType', 'omniread.core.content.ContentType')>",
-        "docstring": "Supported MIME types for extracted content.\n\nThis enum represents the declared or inferred media type of the content\nsource. It is primarily used for routing content to the appropriate\nparser or downstream consumer.",
+        "docstring": "Supported MIME types for extracted content.\n\nNotes:\n    **Guarantees:**\n\n        - This enum represents the declared or inferred media type of the content source\n        - It is primarily used for routing content to the appropriate parser or downstream consumer",
         "members": {
           "HTML": {
             "name": "HTML",
@@ -95,35 +95,35 @@
         "kind": "class",
         "path": "omniread.html.parser.Content",
         "signature": "<bound method Alias.signature of Alias('Content', 'omniread.core.content.Content')>",
-        "docstring": "Normalized representation of extracted content.\n\nA `Content` instance represents a raw content payload along with minimal\ncontextual metadata describing its origin and type.\n\nThis class is the **primary exchange format** between:\n- Scrapers\n- Parsers\n- Downstream consumers\n\nAttributes:\n    raw: Raw content bytes as retrieved from the source.\n    source: Identifier of the content origin (URL, file path, or logical name).\n    content_type: Optional MIME type of the content, if known.\n    metadata: Optional, implementation-defined metadata associated with\n        the content (e.g., headers, encoding hints, extraction notes).",
+        "docstring": "Normalized representation of extracted content.\n\nNotes:\n    **Responsibilities:**\n\n        - A `Content` instance represents a raw content payload along with minimal contextual metadata describing its origin and type\n        - This class is the primary exchange format between Scrapers, Parsers, and Downstream consumers",
         "members": {
           "raw": {
             "name": "raw",
             "kind": "attribute",
             "path": "omniread.html.parser.Content.raw",
             "signature": "<bound method Alias.signature of Alias('raw', 'omniread.core.content.Content.raw')>",
-            "docstring": null
+            "docstring": "Raw content bytes as retrieved from the source."
           },
           "source": {
             "name": "source",
             "kind": "attribute",
             "path": "omniread.html.parser.Content.source",
             "signature": "<bound method Alias.signature of Alias('source', 'omniread.core.content.Content.source')>",
-            "docstring": null
+            "docstring": "Identifier of the content origin (URL, file path, or logical name)."
           },
           "content_type": {
             "name": "content_type",
             "kind": "attribute",
             "path": "omniread.html.parser.Content.content_type",
             "signature": "<bound method Alias.signature of Alias('content_type', 'omniread.core.content.Content.content_type')>",
-            "docstring": null
+            "docstring": "Optional MIME type of the content, if known."
           },
           "metadata": {
             "name": "metadata",
             "kind": "attribute",
             "path": "omniread.html.parser.Content.metadata",
             "signature": "<bound method Alias.signature of Alias('metadata', 'omniread.core.content.Content.metadata')>",
-            "docstring": null
+            "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)."
           }
         }
       },
@@ -132,14 +132,14 @@
         "kind": "class",
         "path": "omniread.html.parser.BaseParser",
         "signature": "<bound method Alias.signature of Alias('BaseParser', 'omniread.core.parser.BaseParser')>",
-        "docstring": "Base interface for all parsers.\n\nA parser is a self-contained object that owns the Content\nit is responsible for interpreting.\n\nImplementations must:\n- Declare supported content types via `supported_types`\n- Raise parsing-specific exceptions from `parse()`\n- Remain deterministic for a given input\n\nConsumers may rely on:\n- Early validation of content compatibility\n- Type-stable return values from `parse()`",
+        "docstring": "Base interface for all parsers.\n\nNotes:\n    **Guarantees:**\n\n        - A parser is a self-contained object that owns the Content it is responsible for interpreting\n        - Consumers may rely on early validation of content compatibility and type-stable return values from `parse()`\n\n    **Responsibilities:**\n\n        - Implementations must declare supported content types via `supported_types`\n        - Implementations must raise parsing-specific exceptions from `parse()`\n        - Implementations must remain deterministic for a given input",
         "members": {
           "supported_types": {
             "name": "supported_types",
             "kind": "attribute",
             "path": "omniread.html.parser.BaseParser.supported_types",
             "signature": "<bound method Alias.signature of Alias('supported_types', 'omniread.core.parser.BaseParser.supported_types')>",
-            "docstring": "Set of content types supported by this parser.\n\nAn empty set indicates that the parser is content-type agnostic."
+            "docstring": "Set of content types supported by this parser. An empty set indicates that the parser is content-type agnostic."
           },
           "content": {
             "name": "content",
@@ -153,14 +153,14 @@
             "kind": "function",
             "path": "omniread.html.parser.BaseParser.parse",
             "signature": "<bound method Alias.signature of Alias('parse', 'omniread.core.parser.BaseParser.parse')>",
-            "docstring": "Parse the owned content into structured output.\n\nImplementations must fully consume the provided content and\nreturn a deterministic, structured output.\n\nReturns:\n    Parsed, structured representation.\n\nRaises:\n    Exception: Parsing-specific errors as defined by the implementation."
+            "docstring": "Parse the owned content into structured output.\n\nReturns:\n    T:\n        Parsed, structured representation.\n\nRaises:\n    Exception:\n        Parsing-specific errors as defined by the implementation.\n\nNotes:\n    **Responsibilities:**\n\n        - Implementations must fully consume the provided content and return a deterministic, structured output"
           },
           "supports": {
             "name": "supports",
             "kind": "function",
             "path": "omniread.html.parser.BaseParser.supports",
             "signature": "<bound method Alias.signature of Alias('supports', 'omniread.core.parser.BaseParser.supports')>",
-            "docstring": "Check whether this parser supports the content's type.\n\nReturns:\n    True if the content type is supported; False otherwise."
+            "docstring": "Check whether this parser supports the content's type.\n\nReturns:\n    bool:\n        True if the content type is supported; False otherwise."
           }
         }
       },
@@ -175,8 +175,8 @@
         "name": "HTMLParser",
         "kind": "class",
         "path": "omniread.html.parser.HTMLParser",
-        "signature": "<bound method Class.signature of Class('HTMLParser', 27, 177)>",
+        "signature": "<bound method Class.signature of Class('HTMLParser', 31, 199)>",
-        "docstring": "Base HTML parser.\n\nThis class extends the core `BaseParser` with HTML-specific behavior,\nincluding DOM parsing via BeautifulSoup and reusable extraction helpers.\n\nProvides reusable helpers for HTML extraction.\nConcrete parsers must explicitly define the return type.\n\nCharacteristics:\n- Accepts only HTML content\n- Owns a parsed BeautifulSoup DOM tree\n- Provides pure helper utilities for common HTML structures\n\nConcrete subclasses must:\n- Define the output type `T`\n- Implement the `parse()` method",
+        "docstring": "Base HTML parser.\n\nNotes:\n    **Responsibilities:**\n\n        - This class extends the core `BaseParser` with HTML-specific behavior, including DOM parsing via BeautifulSoup and reusable extraction helpers\n        - Provides reusable helpers for HTML extraction. Concrete parsers must explicitly define the return type\n\n    **Guarantees:**\n\n        - Characteristics: Accepts only HTML content, owns a parsed BeautifulSoup DOM tree, provides pure helper utilities for common HTML structures\n\n    **Constraints:**\n    \n        - Concrete subclasses must define the output type `T` and implement the `parse()` method",
         "members": {
           "supported_types": {
             "name": "supported_types",
@@ -189,36 +189,36 @@
             "name": "parse",
             "kind": "function",
             "path": "omniread.html.parser.HTMLParser.parse",
-            "signature": "<bound method Function.signature of Function('parse', 70, 81)>",
+            "signature": "<bound method Function.signature of Function('parse', 77, 91)>",
-            "docstring": "Fully parse the HTML content into structured output.\n\nImplementations must fully interpret the HTML DOM and return\na deterministic, structured output.\n\nReturns:\n    Parsed representation of type `T`."
+            "docstring": "Fully parse the HTML content into structured output.\n\nReturns:\n    T:\n        Parsed representation of type `T`.\n\nNotes:\n    **Responsibilities:**\n\n        - Implementations must fully interpret the HTML DOM and return a deterministic, structured output"
           },
           "parse_div": {
             "name": "parse_div",
             "kind": "function",
             "path": "omniread.html.parser.HTMLParser.parse_div",
-            "signature": "<bound method Function.signature of Function('parse_div', 87, 99)>",
+            "signature": "<bound method Function.signature of Function('parse_div', 97, 112)>",
-            "docstring": "Extract normalized text from a `<div>` element.\n\nArgs:\n    div: BeautifulSoup tag representing a `<div>`.\n    separator: String used to separate text nodes.\n\nReturns:\n    Flattened, whitespace-normalized text content."
+            "docstring": "Extract normalized text from a `<div>` element.\n\nArgs:\n    div (Tag):\n        BeautifulSoup tag representing a `<div>`.\n    separator (str, optional):\n        String used to separate text nodes.\n\nReturns:\n    str:\n        Flattened, whitespace-normalized text content."
           },
           "parse_link": {
             "name": "parse_link",
             "kind": "function",
             "path": "omniread.html.parser.HTMLParser.parse_link",
-            "signature": "<bound method Function.signature of Function('parse_link', 101, 112)>",
+            "signature": "<bound method Function.signature of Function('parse_link', 114, 127)>",
-            "docstring": "Extract the hyperlink reference from an `<a>` element.\n\nArgs:\n    a: BeautifulSoup tag representing an anchor.\n\nReturns:\n    The value of the `href` attribute, or None if absent."
+            "docstring": "Extract the hyperlink reference from an `<a>` element.\n\nArgs:\n    a (Tag):\n        BeautifulSoup tag representing an anchor.\n\nReturns:\n    Optional[str]:\n        The value of the `href` attribute, or None if absent."
           },
           "parse_table": {
             "name": "parse_table",
             "kind": "function",
             "path": "omniread.html.parser.HTMLParser.parse_table",
-            "signature": "<bound method Function.signature of Function('parse_table', 114, 133)>",
+            "signature": "<bound method Function.signature of Function('parse_table', 129, 150)>",
-            "docstring": "Parse an HTML table into a 2D list of strings.\n\nArgs:\n    table: BeautifulSoup tag representing a `<table>`.\n\nReturns:\n    A list of rows, where each row is a list of cell text values."
+            "docstring": "Parse an HTML table into a 2D list of strings.\n\nArgs:\n    table (Tag):\n        BeautifulSoup tag representing a `<table>`.\n\nReturns:\n    list[list[str]]:\n        A list of rows, where each row is a list of cell text values."
           },
           "parse_meta": {
             "name": "parse_meta",
             "kind": "function",
             "path": "omniread.html.parser.HTMLParser.parse_meta",
-            "signature": "<bound method Function.signature of Function('parse_meta', 153, 177)>",
+            "signature": "<bound method Function.signature of Function('parse_meta', 172, 199)>",
-            "docstring": "Extract high-level metadata from the HTML document.\n\nThis includes:\n- Document title\n- `<meta>` tag name/property → content mappings\n\nReturns:\n    Dictionary containing extracted metadata."
+            "docstring": "Extract high-level metadata from the HTML document.\n\nReturns:\n    dict[str, Any]:\n        Dictionary containing extracted metadata.\n\nNotes:\n    **Responsibilities:**\n\n        - Extract high-level metadata from the HTML document\n        - This includes: Document title, `<meta>` tag name/property → content mappings"
           }
         }
       },

mcp_docs/modules/omniread.html.scraper.json

@@ -2,7 +2,7 @@
   "module": "omniread.html.scraper",
   "content": {
     "path": "omniread.html.scraper",
-    "docstring": "HTML scraping implementation for OmniRead.\n\nThis module provides an HTTP-based scraper for retrieving HTML documents.\nIt implements the core `BaseScraper` contract using `httpx` as the transport\nlayer.\n\nThis scraper is responsible for:\n- Fetching raw HTML bytes over HTTP(S)\n- Validating response content type\n- Attaching HTTP metadata to the returned content\n\nThis scraper is not responsible for:\n- Parsing or interpreting HTML\n- Retrying failed requests\n- Managing crawl policies or rate limiting",
+    "docstring": "HTML scraping implementation for OmniRead.\n\n---\n\n## Summary\n\nThis module provides an HTTP-based scraper for retrieving HTML documents.\nIt implements the core `BaseScraper` contract using `httpx` as the transport\nlayer.\n\nThis scraper is responsible for:\n- Fetching raw HTML bytes over HTTP(S)\n- Validating response content type\n- Attaching HTTP metadata to the returned content\n\nThis scraper is not responsible for:\n- Parsing or interpreting HTML\n- Retrying failed requests\n- Managing crawl policies or rate limiting",
     "objects": {
       "httpx": {
         "name": "httpx",
@@ -37,35 +37,35 @@
         "kind": "class",
         "path": "omniread.html.scraper.Content",
         "signature": "<bound method Alias.signature of Alias('Content', 'omniread.core.content.Content')>",
-        "docstring": "Normalized representation of extracted content.\n\nA `Content` instance represents a raw content payload along with minimal\ncontextual metadata describing its origin and type.\n\nThis class is the **primary exchange format** between:\n- Scrapers\n- Parsers\n- Downstream consumers\n\nAttributes:\n    raw: Raw content bytes as retrieved from the source.\n    source: Identifier of the content origin (URL, file path, or logical name).\n    content_type: Optional MIME type of the content, if known.\n    metadata: Optional, implementation-defined metadata associated with\n        the content (e.g., headers, encoding hints, extraction notes).",
+        "docstring": "Normalized representation of extracted content.\n\nNotes:\n    **Responsibilities:**\n\n        - A `Content` instance represents a raw content payload along with minimal contextual metadata describing its origin and type\n        - This class is the primary exchange format between Scrapers, Parsers, and Downstream consumers",
         "members": {
           "raw": {
             "name": "raw",
             "kind": "attribute",
             "path": "omniread.html.scraper.Content.raw",
             "signature": "<bound method Alias.signature of Alias('raw', 'omniread.core.content.Content.raw')>",
-            "docstring": null
+            "docstring": "Raw content bytes as retrieved from the source."
           },
           "source": {
             "name": "source",
             "kind": "attribute",
             "path": "omniread.html.scraper.Content.source",
             "signature": "<bound method Alias.signature of Alias('source', 'omniread.core.content.Content.source')>",
-            "docstring": null
+            "docstring": "Identifier of the content origin (URL, file path, or logical name)."
           },
           "content_type": {
             "name": "content_type",
             "kind": "attribute",
             "path": "omniread.html.scraper.Content.content_type",
             "signature": "<bound method Alias.signature of Alias('content_type', 'omniread.core.content.Content.content_type')>",
-            "docstring": null
+            "docstring": "Optional MIME type of the content, if known."
           },
           "metadata": {
             "name": "metadata",
             "kind": "attribute",
             "path": "omniread.html.scraper.Content.metadata",
             "signature": "<bound method Alias.signature of Alias('metadata', 'omniread.core.content.Content.metadata')>",
-            "docstring": null
+            "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)."
           }
         }
       },
@@ -74,7 +74,7 @@
         "kind": "class",
         "path": "omniread.html.scraper.ContentType",
         "signature": "<bound method Alias.signature of Alias('ContentType', 'omniread.core.content.ContentType')>",
-        "docstring": "Supported MIME types for extracted content.\n\nThis enum represents the declared or inferred media type of the content\nsource. It is primarily used for routing content to the appropriate\nparser or downstream consumer.",
+        "docstring": "Supported MIME types for extracted content.\n\nNotes:\n    **Guarantees:**\n\n        - This enum represents the declared or inferred media type of the content source\n        - It is primarily used for routing content to the appropriate parser or downstream consumer",
         "members": {
           "HTML": {
             "name": "HTML",
@@ -111,14 +111,14 @@
         "kind": "class",
         "path": "omniread.html.scraper.BaseScraper",
         "signature": "<bound method Alias.signature of Alias('BaseScraper', 'omniread.core.scraper.BaseScraper')>",
-        "docstring": "Base interface for all scrapers.\n\nA scraper is responsible ONLY for fetching raw content\n(bytes) from a source. It must not interpret or parse it.\n\nA scraper is a **stateless acquisition component** that retrieves raw\ncontent from a source and returns it as a `Content` object.\n\nScrapers define *how content is obtained*, not *what the content means*.\n\nImplementations may vary in:\n- Transport mechanism (HTTP, filesystem, cloud storage)\n- Authentication strategy\n- Retry and backoff behavior\n\nImplementations must not:\n- Parse content\n- Modify content semantics\n- Couple scraping logic to a specific parser",
+        "docstring": "Base interface for all scrapers.\n\nNotes:\n    **Responsibilities:**\n\n        - A scraper is responsible ONLY for fetching raw content (bytes) from a source. It must not interpret or parse it\n        - A scraper is a stateless acquisition component that retrieves raw content from a source and returns it as a `Content` object\n        - Scrapers define how content is obtained, not what the content means\n        - Implementations may vary in transport mechanism, authentication strategy, retry and backoff behavior\n\n    **Constraints:**\n\n        - Implementations must not parse content, modify content semantics, or couple scraping logic to a specific parser",
         "members": {
           "fetch": {
             "name": "fetch",
             "kind": "function",
             "path": "omniread.html.scraper.BaseScraper.fetch",
             "signature": "<bound method Alias.signature of Alias('fetch', 'omniread.core.scraper.BaseScraper.fetch')>",
-            "docstring": "Fetch raw content from the given source.\n\nImplementations must retrieve the content referenced by `source`\nand return it as raw bytes wrapped in a `Content` object.\n\nArgs:\n    source: Location identifier (URL, file path, S3 URI, etc.)\n    metadata: Optional hints for the scraper (headers, auth, etc.)\n\nReturns:\n    Content object containing raw bytes and metadata.\n    - Raw content bytes\n    - Source identifier\n    - Optional metadata\n\nRaises:\n    Exception: Retrieval-specific errors as defined by the implementation."
+            "docstring": "Fetch raw content from the given source.\n\nArgs:\n    source (str):\n        Location identifier (URL, file path, S3 URI, etc.)\n    metadata (Optional[Mapping[str, Any]], optional):\n        Optional hints for the scraper (headers, auth, etc.)\n\nReturns:\n    Content:\n        Content object containing raw bytes and metadata.\n\nRaises:\n    Exception:\n        Retrieval-specific errors as defined by the implementation.\n\nNotes:\n    **Responsibilities:**\n\n        - Implementations must retrieve the content referenced by `source` and return it as raw bytes wrapped in a `Content` object"
           }
         }
       },
@@ -126,8 +126,8 @@
         "name": "HTMLScraper",
         "kind": "class",
         "path": "omniread.html.scraper.HTMLScraper",
-        "signature": "<bound method Class.signature of Class('HTMLScraper', 26, 134)>",
+        "signature": "<bound method Class.signature of Class('HTMLScraper', 30, 139)>",
-        "docstring": "Base HTML scraper using httpx.\n\nThis scraper retrieves HTML documents over HTTP(S) and returns them\nas raw content wrapped in a `Content` object.\n\nFetches raw bytes and metadata only.\nThe scraper:\n- Uses `httpx.Client` for HTTP requests\n- Enforces an HTML content type\n- Preserves HTTP response metadata\n\nThe scraper does not:\n- Parse HTML\n- Perform retries or backoff\n- Handle non-HTML responses",
+        "docstring": "Base HTML scraper using httpx.\n\nNotes:\n    **Responsibilities:**\n\n        - This scraper retrieves HTML documents over HTTP(S) and returns them as raw content wrapped in a `Content` object\n        - Fetches raw bytes and metadata only. The scraper uses `httpx.Client` for HTTP requests, enforces an HTML content type, preserves HTTP response metadata\n\n    **Constraints:**\n    \n        - The scraper does not: Parse HTML, perform retries or backoff, handle non-HTML responses",
         "members": {
           "content_type": {
             "name": "content_type",
@@ -140,15 +140,15 @@
             "name": "validate_content_type",
             "kind": "function",
             "path": "omniread.html.scraper.HTMLScraper.validate_content_type",
-            "signature": "<bound method Function.signature of Function('validate_content_type', 71, 94)>",
+            "signature": "<bound method Function.signature of Function('validate_content_type', 74, 98)>",
-            "docstring": "Validate that the HTTP response contains HTML content.\n\nArgs:\n    response: HTTP response returned by `httpx`.\n\nRaises:\n    ValueError: If the `Content-Type` header is missing or does not\n        indicate HTML content."
+            "docstring": "Validate that the HTTP response contains HTML content.\n\nArgs:\n    response (httpx.Response):\n        HTTP response returned by `httpx`.\n\nRaises:\n    ValueError:\n        If the `Content-Type` header is missing or does not indicate HTML content."
           },
           "fetch": {
             "name": "fetch",
             "kind": "function",
             "path": "omniread.html.scraper.HTMLScraper.fetch",
-            "signature": "<bound method Function.signature of Function('fetch', 96, 134)>",
+            "signature": "<bound method Function.signature of Function('fetch', 100, 139)>",
-            "docstring": "Fetch an HTML document from the given source.\n\nArgs:\n    source: URL of the HTML document.\n    metadata: Optional metadata to be merged into the returned content.\n\nReturns:\n    A `Content` instance containing:\n    - Raw HTML bytes\n    - Source URL\n    - HTML content type\n    - HTTP response metadata\n\nRaises:\n    httpx.HTTPError: If the HTTP request fails.\n    ValueError: If the response is not valid HTML."
+            "docstring": "Fetch an HTML document from the given source.\n\nArgs:\n    source (str):\n        URL of the HTML document.\n    metadata (Optional[Mapping[str, Any]], optional):\n        Optional metadata to be merged into the returned content.\n\nReturns:\n    Content:\n        A `Content` instance containing raw HTML bytes, source URL, HTML content type, and HTTP response metadata.\n\nRaises:\n    httpx.HTTPError:\n        If the HTTP request fails.\n    ValueError:\n        If the response is not valid HTML."
           }
         }
       }

mcp_docs/modules/omniread.pdf.client.json

@@ -2,7 +2,7 @@
   "module": "omniread.pdf.client",
   "content": {
     "path": "omniread.pdf.client",
-    "docstring": "PDF client abstractions for OmniRead.\n\nThis module defines the **client layer** responsible for retrieving raw PDF\nbytes from a concrete backing store.\n\nClients provide low-level access to PDF binaries and are intentionally\ndecoupled from scraping and parsing logic. They do not perform validation,\ninterpretation, or content extraction.\n\nTypical backing stores include:\n- Local filesystems\n- Object storage (S3, GCS, etc.)\n- Network file systems",
+    "docstring": "PDF client abstractions for OmniRead.\n\n---\n\n## Summary\n\nThis module defines the **client layer** responsible for retrieving raw PDF\nbytes from a concrete backing store.\n\nClients provide low-level access to PDF binaries and are intentionally\ndecoupled from scraping and parsing logic. They do not perform validation,\ninterpretation, or content extraction.\n\nTypical backing stores include:\n- Local filesystems\n- Object storage (S3, GCS, etc.)\n- Network file systems",
     "objects": {
       "Any": {
         "name": "Any",
@@ -36,15 +36,15 @@
         "name": "BasePDFClient",
         "kind": "class",
         "path": "omniread.pdf.client.BasePDFClient",
-        "signature": "<bound method Class.signature of Class('BasePDFClient', 22, 48)>",
+        "signature": "<bound method Class.signature of Class('BasePDFClient', 26, 54)>",
-        "docstring": "Abstract client responsible for retrieving PDF bytes\nfrom a specific backing store (filesystem, S3, FTP, etc.).\n\nImplementations must:\n- Accept a source identifier appropriate to the backing store\n- Return the full PDF binary payload\n- Raise retrieval-specific errors on failure",
+        "docstring": "Abstract client responsible for retrieving PDF bytes\nfrom a specific backing store (filesystem, S3, FTP, etc.).\n\nNotes:\n    **Responsibilities:**\n\n        - Implementations must accept a source identifier appropriate to the backing store, return the full PDF binary payload, and raise retrieval-specific errors on failure",
         "members": {
           "fetch": {
             "name": "fetch",
             "kind": "function",
             "path": "omniread.pdf.client.BasePDFClient.fetch",
-            "signature": "<bound method Function.signature of Function('fetch', 33, 48)>",
+            "signature": "<bound method Function.signature of Function('fetch', 37, 54)>",
-            "docstring": "Fetch raw PDF bytes from the given source.\n\nArgs:\n    source: Identifier of the PDF location, such as a file path,\n        object storage key, or remote reference.\n\nReturns:\n    Raw PDF bytes.\n\nRaises:\n    Exception: Retrieval-specific errors defined by the implementation."
+            "docstring": "Fetch raw PDF bytes from the given source.\n\nArgs:\n    source (Any):\n        Identifier of the PDF location, such as a file path, object storage key, or remote reference.\n\nReturns:\n    bytes:\n        Raw PDF bytes.\n\nRaises:\n    Exception:\n        Retrieval-specific errors defined by the implementation."
           }
         }
       },
@@ -52,15 +52,15 @@
         "name": "FileSystemPDFClient",
         "kind": "class",
         "path": "omniread.pdf.client.FileSystemPDFClient",
-        "signature": "<bound method Class.signature of Class('FileSystemPDFClient', 51, 80)>",
+        "signature": "<bound method Class.signature of Class('FileSystemPDFClient', 57, 92)>",
-        "docstring": "PDF client that reads from the local filesystem.\n\nThis client reads PDF files directly from the disk and returns their raw\nbinary contents.",
+        "docstring": "PDF client that reads from the local filesystem.\n\nNotes:\n    **Guarantees:**\n\n        - This client reads PDF files directly from the disk and returns their raw binary contents",
         "members": {
           "fetch": {
             "name": "fetch",
             "kind": "function",
             "path": "omniread.pdf.client.FileSystemPDFClient.fetch",
-            "signature": "<bound method Function.signature of Function('fetch', 59, 80)>",
+            "signature": "<bound method Function.signature of Function('fetch', 67, 92)>",
-            "docstring": "Read a PDF file from the local filesystem.\n\nArgs:\n    path: Filesystem path to the PDF file.\n\nReturns:\n    Raw PDF bytes.\n\nRaises:\n    FileNotFoundError: If the path does not exist.\n    ValueError: If the path exists but is not a file."
+            "docstring": "Read a PDF file from the local filesystem.\n\nArgs:\n    path (Path):\n        Filesystem path to the PDF file.\n\nReturns:\n    bytes:\n        Raw PDF bytes.\n\nRaises:\n    FileNotFoundError:\n        If the path does not exist.\n    ValueError:\n        If the path exists but is not a file."
           }
         }
       }

mcp_docs/modules/omniread.pdf.json

@@ -2,21 +2,21 @@
   "module": "omniread.pdf",
   "content": {
     "path": "omniread.pdf",
-    "docstring": "PDF format implementation for OmniRead.\n\nThis package provides **PDF-specific implementations** of the core OmniRead\ncontracts defined in `omniread.core`.\n\nUnlike HTML, PDF handling requires an explicit client layer for document\naccess. This package therefore includes:\n- PDF clients for acquiring raw PDF data\n- PDF scrapers that coordinate client access\n- PDF parsers that extract structured content from PDF binaries\n\nPublic exports from this package represent the supported PDF pipeline\nand are safe for consumers to import directly when working with PDFs.",
+    "docstring": "PDF format implementation for OmniRead.\n\n---\n\n## Summary\n\nThis package provides **PDF-specific implementations** of the core OmniRead\ncontracts defined in `omniread.core`.\n\nUnlike HTML, PDF handling requires an explicit client layer for document\naccess. This package therefore includes:\n- PDF clients for acquiring raw PDF data\n- PDF scrapers that coordinate client access\n- PDF parsers that extract structured content from PDF binaries\n\nPublic exports from this package represent the supported PDF pipeline\nand are safe for consumers to import directly when working with PDFs.\n\n---\n\n## Public API\n\n    FileSystemPDFClient\n    PDFScraper\n    PDFParser\n\n---",
     "objects": {
       "FileSystemPDFClient": {
         "name": "FileSystemPDFClient",
         "kind": "class",
         "path": "omniread.pdf.FileSystemPDFClient",
         "signature": "<bound method Alias.signature of Alias('FileSystemPDFClient', 'omniread.pdf.client.FileSystemPDFClient')>",
-        "docstring": "PDF client that reads from the local filesystem.\n\nThis client reads PDF files directly from the disk and returns their raw\nbinary contents.",
+        "docstring": "PDF client that reads from the local filesystem.\n\nNotes:\n    **Guarantees:**\n\n        - This client reads PDF files directly from the disk and returns their raw binary contents",
         "members": {
           "fetch": {
             "name": "fetch",
             "kind": "function",
             "path": "omniread.pdf.FileSystemPDFClient.fetch",
             "signature": "<bound method Alias.signature of Alias('fetch', 'omniread.pdf.client.FileSystemPDFClient.fetch')>",
-            "docstring": "Read a PDF file from the local filesystem.\n\nArgs:\n    path: Filesystem path to the PDF file.\n\nReturns:\n    Raw PDF bytes.\n\nRaises:\n    FileNotFoundError: If the path does not exist.\n    ValueError: If the path exists but is not a file."
+            "docstring": "Read a PDF file from the local filesystem.\n\nArgs:\n    path (Path):\n        Filesystem path to the PDF file.\n\nReturns:\n    bytes:\n        Raw PDF bytes.\n\nRaises:\n    FileNotFoundError:\n        If the path does not exist.\n    ValueError:\n        If the path exists but is not a file."
           }
         }
       },
@@ -25,14 +25,14 @@
         "kind": "class",
         "path": "omniread.pdf.PDFScraper",
         "signature": "<bound method Alias.signature of Alias('PDFScraper', 'omniread.pdf.scraper.PDFScraper')>",
-        "docstring": "Scraper for PDF sources.\n\nDelegates byte retrieval to a PDF client and normalizes\noutput into Content.\n\nThe scraper:\n- Does not perform parsing or interpretation\n- Does not assume a specific storage backend\n- Preserves caller-provided metadata",
+        "docstring": "Scraper for PDF sources.\n\nNotes:\n    **Responsibilities:**\n\n        - Delegates byte retrieval to a PDF client and normalizes output into Content\n        - Preserves caller-provided metadata\n\n    **Constraints:**\n    \n        - The scraper: Does not perform parsing or interpretation, does not assume a specific storage backend",
         "members": {
           "fetch": {
             "name": "fetch",
             "kind": "function",
             "path": "omniread.pdf.PDFScraper.fetch",
             "signature": "<bound method Alias.signature of Alias('fetch', 'omniread.pdf.scraper.PDFScraper.fetch')>",
-            "docstring": "Fetch a PDF document from the given source.\n\nArgs:\n    source: Identifier of the PDF source as understood by the\n        configured PDF client.\n    metadata: Optional metadata to attach to the returned content.\n\nReturns:\n    A `Content` instance containing:\n    - Raw PDF bytes\n    - Source identifier\n    - PDF content type\n    - Optional metadata\n\nRaises:\n    Exception: Retrieval-specific errors raised by the PDF client."
+            "docstring": "Fetch a PDF document from the given source.\n\nArgs:\n    source (Any):\n        Identifier of the PDF source as understood by the configured PDF client.\n    metadata (Optional[Mapping[str, Any]], optional):\n        Optional metadata to attach to the returned content.\n\nReturns:\n    Content:\n        A `Content` instance containing raw PDF bytes, source identifier, PDF content type, and optional metadata.\n\nRaises:\n    Exception:\n        Retrieval-specific errors raised by the PDF client."
           }
         }
       },
@@ -41,7 +41,7 @@
         "kind": "class",
         "path": "omniread.pdf.PDFParser",
         "signature": "<bound method Alias.signature of Alias('PDFParser', 'omniread.pdf.parser.PDFParser')>",
-        "docstring": "Base PDF parser.\n\nThis class enforces PDF content-type compatibility and provides the\nextension point for implementing concrete PDF parsing strategies.\n\nConcrete implementations must define:\n- Define the output type `T`\n- Implement the `parse()` method",
+        "docstring": "Base PDF parser.\n\nNotes:\n    **Responsibilities:**\n\n        - This class enforces PDF content-type compatibility and provides the extension point for implementing concrete PDF parsing strategies\n\n    **Constraints:**\n\n        - Concrete implementations must: Define the output type `T`, implement the `parse()` method",
         "members": {
           "supported_types": {
             "name": "supported_types",
@@ -55,7 +55,7 @@
             "kind": "function",
             "path": "omniread.pdf.PDFParser.parse",
             "signature": "<bound method Alias.signature of Alias('parse', 'omniread.pdf.parser.PDFParser.parse')>",
-            "docstring": "Parse PDF content into a structured output.\n\nImplementations must fully interpret the PDF binary payload and\nreturn a deterministic, structured output.\n\nReturns:\n    Parsed representation of type `T`.\n\nRaises:\n    Exception: Parsing-specific errors as defined by the implementation."
+            "docstring": "Parse PDF content into a structured output.\n\nReturns:\n    T:\n        Parsed representation of type `T`.\n\nRaises:\n    Exception:\n        Parsing-specific errors as defined by the implementation.\n\nNotes:\n    **Responsibilities:**\n\n        - Implementations must fully interpret the PDF binary payload and return a deterministic, structured output"
           }
         }
       },
@@ -64,7 +64,7 @@
         "kind": "module",
         "path": "omniread.pdf.client",
         "signature": null,
-        "docstring": "PDF client abstractions for OmniRead.\n\nThis module defines the **client layer** responsible for retrieving raw PDF\nbytes from a concrete backing store.\n\nClients provide low-level access to PDF binaries and are intentionally\ndecoupled from scraping and parsing logic. They do not perform validation,\ninterpretation, or content extraction.\n\nTypical backing stores include:\n- Local filesystems\n- Object storage (S3, GCS, etc.)\n- Network file systems",
+        "docstring": "PDF client abstractions for OmniRead.\n\n---\n\n## Summary\n\nThis module defines the **client layer** responsible for retrieving raw PDF\nbytes from a concrete backing store.\n\nClients provide low-level access to PDF binaries and are intentionally\ndecoupled from scraping and parsing logic. They do not perform validation,\ninterpretation, or content extraction.\n\nTypical backing stores include:\n- Local filesystems\n- Object storage (S3, GCS, etc.)\n- Network file systems",
         "members": {
           "Any": {
             "name": "Any",
@@ -98,15 +98,15 @@
             "name": "BasePDFClient",
             "kind": "class",
             "path": "omniread.pdf.client.BasePDFClient",
-            "signature": "<bound method Class.signature of Class('BasePDFClient', 22, 48)>",
+            "signature": "<bound method Class.signature of Class('BasePDFClient', 26, 54)>",
-            "docstring": "Abstract client responsible for retrieving PDF bytes\nfrom a specific backing store (filesystem, S3, FTP, etc.).\n\nImplementations must:\n- Accept a source identifier appropriate to the backing store\n- Return the full PDF binary payload\n- Raise retrieval-specific errors on failure",
+            "docstring": "Abstract client responsible for retrieving PDF bytes\nfrom a specific backing store (filesystem, S3, FTP, etc.).\n\nNotes:\n    **Responsibilities:**\n\n        - Implementations must accept a source identifier appropriate to the backing store, return the full PDF binary payload, and raise retrieval-specific errors on failure",
             "members": {
               "fetch": {
                 "name": "fetch",
                 "kind": "function",
                 "path": "omniread.pdf.client.BasePDFClient.fetch",
-                "signature": "<bound method Function.signature of Function('fetch', 33, 48)>",
+                "signature": "<bound method Function.signature of Function('fetch', 37, 54)>",
-                "docstring": "Fetch raw PDF bytes from the given source.\n\nArgs:\n    source: Identifier of the PDF location, such as a file path,\n        object storage key, or remote reference.\n\nReturns:\n    Raw PDF bytes.\n\nRaises:\n    Exception: Retrieval-specific errors defined by the implementation."
+                "docstring": "Fetch raw PDF bytes from the given source.\n\nArgs:\n    source (Any):\n        Identifier of the PDF location, such as a file path, object storage key, or remote reference.\n\nReturns:\n    bytes:\n        Raw PDF bytes.\n\nRaises:\n    Exception:\n        Retrieval-specific errors defined by the implementation."
               }
             }
           },
@@ -114,15 +114,15 @@
             "name": "FileSystemPDFClient",
             "kind": "class",
             "path": "omniread.pdf.client.FileSystemPDFClient",
-            "signature": "<bound method Class.signature of Class('FileSystemPDFClient', 51, 80)>",
+            "signature": "<bound method Class.signature of Class('FileSystemPDFClient', 57, 92)>",
-            "docstring": "PDF client that reads from the local filesystem.\n\nThis client reads PDF files directly from the disk and returns their raw\nbinary contents.",
+            "docstring": "PDF client that reads from the local filesystem.\n\nNotes:\n    **Guarantees:**\n\n        - This client reads PDF files directly from the disk and returns their raw binary contents",
             "members": {
               "fetch": {
                 "name": "fetch",
                 "kind": "function",
                 "path": "omniread.pdf.client.FileSystemPDFClient.fetch",
-                "signature": "<bound method Function.signature of Function('fetch', 59, 80)>",
+                "signature": "<bound method Function.signature of Function('fetch', 67, 92)>",
-                "docstring": "Read a PDF file from the local filesystem.\n\nArgs:\n    path: Filesystem path to the PDF file.\n\nReturns:\n    Raw PDF bytes.\n\nRaises:\n    FileNotFoundError: If the path does not exist.\n    ValueError: If the path exists but is not a file."
+                "docstring": "Read a PDF file from the local filesystem.\n\nArgs:\n    path (Path):\n        Filesystem path to the PDF file.\n\nReturns:\n    bytes:\n        Raw PDF bytes.\n\nRaises:\n    FileNotFoundError:\n        If the path does not exist.\n    ValueError:\n        If the path exists but is not a file."
               }
             }
           }
@@ -133,7 +133,7 @@
         "kind": "module",
         "path": "omniread.pdf.parser",
         "signature": null,
-        "docstring": "PDF parser base implementations for OmniRead.\n\nThis module defines the **PDF-specific parser contract**, extending the\nformat-agnostic `BaseParser` with constraints appropriate for PDF content.\n\nPDF parsers are responsible for interpreting binary PDF data and producing\nstructured representations suitable for downstream consumption.",
+        "docstring": "PDF parser base implementations for OmniRead.\n\n---\n\n## Summary\n\nThis module defines the **PDF-specific parser contract**, extending the\nformat-agnostic `BaseParser` with constraints appropriate for PDF content.\n\nPDF parsers are responsible for interpreting binary PDF data and producing\nstructured representations suitable for downstream consumption.",
         "members": {
           "Generic": {
             "name": "Generic",
@@ -161,7 +161,7 @@
             "kind": "class",
             "path": "omniread.pdf.parser.ContentType",
             "signature": "<bound method Alias.signature of Alias('ContentType', 'omniread.core.content.ContentType')>",
-            "docstring": "Supported MIME types for extracted content.\n\nThis enum represents the declared or inferred media type of the content\nsource. It is primarily used for routing content to the appropriate\nparser or downstream consumer.",
+            "docstring": "Supported MIME types for extracted content.\n\nNotes:\n    **Guarantees:**\n\n        - This enum represents the declared or inferred media type of the content source\n        - It is primarily used for routing content to the appropriate parser or downstream consumer",
             "members": {
               "HTML": {
                 "name": "HTML",
@@ -198,14 +198,14 @@
             "kind": "class",
             "path": "omniread.pdf.parser.BaseParser",
             "signature": "<bound method Alias.signature of Alias('BaseParser', 'omniread.core.parser.BaseParser')>",
-            "docstring": "Base interface for all parsers.\n\nA parser is a self-contained object that owns the Content\nit is responsible for interpreting.\n\nImplementations must:\n- Declare supported content types via `supported_types`\n- Raise parsing-specific exceptions from `parse()`\n- Remain deterministic for a given input\n\nConsumers may rely on:\n- Early validation of content compatibility\n- Type-stable return values from `parse()`",
+            "docstring": "Base interface for all parsers.\n\nNotes:\n    **Guarantees:**\n\n        - A parser is a self-contained object that owns the Content it is responsible for interpreting\n        - Consumers may rely on early validation of content compatibility and type-stable return values from `parse()`\n\n    **Responsibilities:**\n\n        - Implementations must declare supported content types via `supported_types`\n        - Implementations must raise parsing-specific exceptions from `parse()`\n        - Implementations must remain deterministic for a given input",
             "members": {
               "supported_types": {
                 "name": "supported_types",
                 "kind": "attribute",
                 "path": "omniread.pdf.parser.BaseParser.supported_types",
                 "signature": "<bound method Alias.signature of Alias('supported_types', 'omniread.core.parser.BaseParser.supported_types')>",
-                "docstring": "Set of content types supported by this parser.\n\nAn empty set indicates that the parser is content-type agnostic."
+                "docstring": "Set of content types supported by this parser. An empty set indicates that the parser is content-type agnostic."
               },
               "content": {
                 "name": "content",
@@ -219,14 +219,14 @@
                 "kind": "function",
                 "path": "omniread.pdf.parser.BaseParser.parse",
                 "signature": "<bound method Alias.signature of Alias('parse', 'omniread.core.parser.BaseParser.parse')>",
-                "docstring": "Parse the owned content into structured output.\n\nImplementations must fully consume the provided content and\nreturn a deterministic, structured output.\n\nReturns:\n    Parsed, structured representation.\n\nRaises:\n    Exception: Parsing-specific errors as defined by the implementation."
+                "docstring": "Parse the owned content into structured output.\n\nReturns:\n    T:\n        Parsed, structured representation.\n\nRaises:\n    Exception:\n        Parsing-specific errors as defined by the implementation.\n\nNotes:\n    **Responsibilities:**\n\n        - Implementations must fully consume the provided content and return a deterministic, structured output"
               },
               "supports": {
                 "name": "supports",
                 "kind": "function",
                 "path": "omniread.pdf.parser.BaseParser.supports",
                 "signature": "<bound method Alias.signature of Alias('supports', 'omniread.core.parser.BaseParser.supports')>",
-                "docstring": "Check whether this parser supports the content's type.\n\nReturns:\n    True if the content type is supported; False otherwise."
+                "docstring": "Check whether this parser supports the content's type.\n\nReturns:\n    bool:\n        True if the content type is supported; False otherwise."
               }
             }
           },
@@ -241,8 +241,8 @@
             "name": "PDFParser",
             "kind": "class",
             "path": "omniread.pdf.parser.PDFParser",
-            "signature": "<bound method Class.signature of Class('PDFParser', 20, 49)>",
+            "signature": "<bound method Class.signature of Class('PDFParser', 24, 61)>",
-            "docstring": "Base PDF parser.\n\nThis class enforces PDF content-type compatibility and provides the\nextension point for implementing concrete PDF parsing strategies.\n\nConcrete implementations must define:\n- Define the output type `T`\n- Implement the `parse()` method",
+            "docstring": "Base PDF parser.\n\nNotes:\n    **Responsibilities:**\n\n        - This class enforces PDF content-type compatibility and provides the extension point for implementing concrete PDF parsing strategies\n\n    **Constraints:**\n\n        - Concrete implementations must: Define the output type `T`, implement the `parse()` method",
             "members": {
               "supported_types": {
                 "name": "supported_types",
@@ -255,8 +255,8 @@
                 "name": "parse",
                 "kind": "function",
                 "path": "omniread.pdf.parser.PDFParser.parse",
-                "signature": "<bound method Function.signature of Function('parse', 35, 49)>",
+                "signature": "<bound method Function.signature of Function('parse', 43, 61)>",
-                "docstring": "Parse PDF content into a structured output.\n\nImplementations must fully interpret the PDF binary payload and\nreturn a deterministic, structured output.\n\nReturns:\n    Parsed representation of type `T`.\n\nRaises:\n    Exception: Parsing-specific errors as defined by the implementation."
+                "docstring": "Parse PDF content into a structured output.\n\nReturns:\n    T:\n        Parsed representation of type `T`.\n\nRaises:\n    Exception:\n        Parsing-specific errors as defined by the implementation.\n\nNotes:\n    **Responsibilities:**\n\n        - Implementations must fully interpret the PDF binary payload and return a deterministic, structured output"
               }
             }
           }
@@ -267,7 +267,7 @@
         "kind": "module",
         "path": "omniread.pdf.scraper",
         "signature": null,
-        "docstring": "PDF scraping implementation for OmniRead.\n\nThis module provides a PDF-specific scraper that coordinates PDF byte\nretrieval via a client and normalizes the result into a `Content` object.\n\nThe scraper implements the core `BaseScraper` contract while delegating\nall storage and access concerns to a `BasePDFClient` implementation.",
+        "docstring": "PDF scraping implementation for OmniRead.\n\n---\n\n## Summary\n\nThis module provides a PDF-specific scraper that coordinates PDF byte\nretrieval via a client and normalizes the result into a `Content` object.\n\nThe scraper implements the core `BaseScraper` contract while delegating\nall storage and access concerns to a `BasePDFClient` implementation.",
         "members": {
           "Any": {
             "name": "Any",
@@ -295,35 +295,35 @@
             "kind": "class",
             "path": "omniread.pdf.scraper.Content",
             "signature": "<bound method Alias.signature of Alias('Content', 'omniread.core.content.Content')>",
-            "docstring": "Normalized representation of extracted content.\n\nA `Content` instance represents a raw content payload along with minimal\ncontextual metadata describing its origin and type.\n\nThis class is the **primary exchange format** between:\n- Scrapers\n- Parsers\n- Downstream consumers\n\nAttributes:\n    raw: Raw content bytes as retrieved from the source.\n    source: Identifier of the content origin (URL, file path, or logical name).\n    content_type: Optional MIME type of the content, if known.\n    metadata: Optional, implementation-defined metadata associated with\n        the content (e.g., headers, encoding hints, extraction notes).",
+            "docstring": "Normalized representation of extracted content.\n\nNotes:\n    **Responsibilities:**\n\n        - A `Content` instance represents a raw content payload along with minimal contextual metadata describing its origin and type\n        - This class is the primary exchange format between Scrapers, Parsers, and Downstream consumers",
             "members": {
               "raw": {
                 "name": "raw",
                 "kind": "attribute",
                 "path": "omniread.pdf.scraper.Content.raw",
                 "signature": "<bound method Alias.signature of Alias('raw', 'omniread.core.content.Content.raw')>",
-                "docstring": null
+                "docstring": "Raw content bytes as retrieved from the source."
               },
               "source": {
                 "name": "source",
                 "kind": "attribute",
                 "path": "omniread.pdf.scraper.Content.source",
                 "signature": "<bound method Alias.signature of Alias('source', 'omniread.core.content.Content.source')>",
-                "docstring": null
+                "docstring": "Identifier of the content origin (URL, file path, or logical name)."
               },
               "content_type": {
                 "name": "content_type",
                 "kind": "attribute",
                 "path": "omniread.pdf.scraper.Content.content_type",
                 "signature": "<bound method Alias.signature of Alias('content_type', 'omniread.core.content.Content.content_type')>",
-                "docstring": null
+                "docstring": "Optional MIME type of the content, if known."
               },
               "metadata": {
                 "name": "metadata",
                 "kind": "attribute",
                 "path": "omniread.pdf.scraper.Content.metadata",
                 "signature": "<bound method Alias.signature of Alias('metadata', 'omniread.core.content.Content.metadata')>",
-                "docstring": null
+                "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)."
               }
             }
           },
@@ -332,7 +332,7 @@
             "kind": "class",
             "path": "omniread.pdf.scraper.ContentType",
             "signature": "<bound method Alias.signature of Alias('ContentType', 'omniread.core.content.ContentType')>",
-            "docstring": "Supported MIME types for extracted content.\n\nThis enum represents the declared or inferred media type of the content\nsource. It is primarily used for routing content to the appropriate\nparser or downstream consumer.",
+            "docstring": "Supported MIME types for extracted content.\n\nNotes:\n    **Guarantees:**\n\n        - This enum represents the declared or inferred media type of the content source\n        - It is primarily used for routing content to the appropriate parser or downstream consumer",
             "members": {
               "HTML": {
                 "name": "HTML",
@@ -369,14 +369,14 @@
             "kind": "class",
             "path": "omniread.pdf.scraper.BaseScraper",
             "signature": "<bound method Alias.signature of Alias('BaseScraper', 'omniread.core.scraper.BaseScraper')>",
-            "docstring": "Base interface for all scrapers.\n\nA scraper is responsible ONLY for fetching raw content\n(bytes) from a source. It must not interpret or parse it.\n\nA scraper is a **stateless acquisition component** that retrieves raw\ncontent from a source and returns it as a `Content` object.\n\nScrapers define *how content is obtained*, not *what the content means*.\n\nImplementations may vary in:\n- Transport mechanism (HTTP, filesystem, cloud storage)\n- Authentication strategy\n- Retry and backoff behavior\n\nImplementations must not:\n- Parse content\n- Modify content semantics\n- Couple scraping logic to a specific parser",
+            "docstring": "Base interface for all scrapers.\n\nNotes:\n    **Responsibilities:**\n\n        - A scraper is responsible ONLY for fetching raw content (bytes) from a source. It must not interpret or parse it\n        - A scraper is a stateless acquisition component that retrieves raw content from a source and returns it as a `Content` object\n        - Scrapers define how content is obtained, not what the content means\n        - Implementations may vary in transport mechanism, authentication strategy, retry and backoff behavior\n\n    **Constraints:**\n\n        - Implementations must not parse content, modify content semantics, or couple scraping logic to a specific parser",
             "members": {
               "fetch": {
                 "name": "fetch",
                 "kind": "function",
                 "path": "omniread.pdf.scraper.BaseScraper.fetch",
                 "signature": "<bound method Alias.signature of Alias('fetch', 'omniread.core.scraper.BaseScraper.fetch')>",
-                "docstring": "Fetch raw content from the given source.\n\nImplementations must retrieve the content referenced by `source`\nand return it as raw bytes wrapped in a `Content` object.\n\nArgs:\n    source: Location identifier (URL, file path, S3 URI, etc.)\n    metadata: Optional hints for the scraper (headers, auth, etc.)\n\nReturns:\n    Content object containing raw bytes and metadata.\n    - Raw content bytes\n    - Source identifier\n    - Optional metadata\n\nRaises:\n    Exception: Retrieval-specific errors as defined by the implementation."
+                "docstring": "Fetch raw content from the given source.\n\nArgs:\n    source (str):\n        Location identifier (URL, file path, S3 URI, etc.)\n    metadata (Optional[Mapping[str, Any]], optional):\n        Optional hints for the scraper (headers, auth, etc.)\n\nReturns:\n    Content:\n        Content object containing raw bytes and metadata.\n\nRaises:\n    Exception:\n        Retrieval-specific errors as defined by the implementation.\n\nNotes:\n    **Responsibilities:**\n\n        - Implementations must retrieve the content referenced by `source` and return it as raw bytes wrapped in a `Content` object"
               }
             }
           },
@@ -385,14 +385,14 @@
             "kind": "class",
             "path": "omniread.pdf.scraper.BasePDFClient",
             "signature": "<bound method Alias.signature of Alias('BasePDFClient', 'omniread.pdf.client.BasePDFClient')>",
-            "docstring": "Abstract client responsible for retrieving PDF bytes\nfrom a specific backing store (filesystem, S3, FTP, etc.).\n\nImplementations must:\n- Accept a source identifier appropriate to the backing store\n- Return the full PDF binary payload\n- Raise retrieval-specific errors on failure",
+            "docstring": "Abstract client responsible for retrieving PDF bytes\nfrom a specific backing store (filesystem, S3, FTP, etc.).\n\nNotes:\n    **Responsibilities:**\n\n        - Implementations must accept a source identifier appropriate to the backing store, return the full PDF binary payload, and raise retrieval-specific errors on failure",
             "members": {
               "fetch": {
                 "name": "fetch",
                 "kind": "function",
                 "path": "omniread.pdf.scraper.BasePDFClient.fetch",
                 "signature": "<bound method Alias.signature of Alias('fetch', 'omniread.pdf.client.BasePDFClient.fetch')>",
-                "docstring": "Fetch raw PDF bytes from the given source.\n\nArgs:\n    source: Identifier of the PDF location, such as a file path,\n        object storage key, or remote reference.\n\nReturns:\n    Raw PDF bytes.\n\nRaises:\n    Exception: Retrieval-specific errors defined by the implementation."
+                "docstring": "Fetch raw PDF bytes from the given source.\n\nArgs:\n    source (Any):\n        Identifier of the PDF location, such as a file path, object storage key, or remote reference.\n\nReturns:\n    bytes:\n        Raw PDF bytes.\n\nRaises:\n    Exception:\n        Retrieval-specific errors defined by the implementation."
               }
             }
           },
@@ -400,15 +400,15 @@
             "name": "PDFScraper",
             "kind": "class",
             "path": "omniread.pdf.scraper.PDFScraper",
-            "signature": "<bound method Class.signature of Class('PDFScraper', 18, 71)>",
+            "signature": "<bound method Class.signature of Class('PDFScraper', 22, 77)>",
-            "docstring": "Scraper for PDF sources.\n\nDelegates byte retrieval to a PDF client and normalizes\noutput into Content.\n\nThe scraper:\n- Does not perform parsing or interpretation\n- Does not assume a specific storage backend\n- Preserves caller-provided metadata",
+            "docstring": "Scraper for PDF sources.\n\nNotes:\n    **Responsibilities:**\n\n        - Delegates byte retrieval to a PDF client and normalizes output into Content\n        - Preserves caller-provided metadata\n\n    **Constraints:**\n    \n        - The scraper: Does not perform parsing or interpretation, does not assume a specific storage backend",
             "members": {
               "fetch": {
                 "name": "fetch",
                 "kind": "function",
                 "path": "omniread.pdf.scraper.PDFScraper.fetch",
-                "signature": "<bound method Function.signature of Function('fetch', 40, 71)>",
+                "signature": "<bound method Function.signature of Function('fetch', 47, 77)>",
-                "docstring": "Fetch a PDF document from the given source.\n\nArgs:\n    source: Identifier of the PDF source as understood by the\n        configured PDF client.\n    metadata: Optional metadata to attach to the returned content.\n\nReturns:\n    A `Content` instance containing:\n    - Raw PDF bytes\n    - Source identifier\n    - PDF content type\n    - Optional metadata\n\nRaises:\n    Exception: Retrieval-specific errors raised by the PDF client."
+                "docstring": "Fetch a PDF document from the given source.\n\nArgs:\n    source (Any):\n        Identifier of the PDF source as understood by the configured PDF client.\n    metadata (Optional[Mapping[str, Any]], optional):\n        Optional metadata to attach to the returned content.\n\nReturns:\n    Content:\n        A `Content` instance containing raw PDF bytes, source identifier, PDF content type, and optional metadata.\n\nRaises:\n    Exception:\n        Retrieval-specific errors raised by the PDF client."
               }
             }
           }

mcp_docs/modules/omniread.pdf.parser.json

@@ -2,7 +2,7 @@
   "module": "omniread.pdf.parser",
   "content": {
     "path": "omniread.pdf.parser",
-    "docstring": "PDF parser base implementations for OmniRead.\n\nThis module defines the **PDF-specific parser contract**, extending the\nformat-agnostic `BaseParser` with constraints appropriate for PDF content.\n\nPDF parsers are responsible for interpreting binary PDF data and producing\nstructured representations suitable for downstream consumption.",
+    "docstring": "PDF parser base implementations for OmniRead.\n\n---\n\n## Summary\n\nThis module defines the **PDF-specific parser contract**, extending the\nformat-agnostic `BaseParser` with constraints appropriate for PDF content.\n\nPDF parsers are responsible for interpreting binary PDF data and producing\nstructured representations suitable for downstream consumption.",
     "objects": {
       "Generic": {
         "name": "Generic",
@@ -30,7 +30,7 @@
         "kind": "class",
         "path": "omniread.pdf.parser.ContentType",
         "signature": "<bound method Alias.signature of Alias('ContentType', 'omniread.core.content.ContentType')>",
-        "docstring": "Supported MIME types for extracted content.\n\nThis enum represents the declared or inferred media type of the content\nsource. It is primarily used for routing content to the appropriate\nparser or downstream consumer.",
+        "docstring": "Supported MIME types for extracted content.\n\nNotes:\n    **Guarantees:**\n\n        - This enum represents the declared or inferred media type of the content source\n        - It is primarily used for routing content to the appropriate parser or downstream consumer",
         "members": {
           "HTML": {
             "name": "HTML",
@@ -67,14 +67,14 @@
         "kind": "class",
         "path": "omniread.pdf.parser.BaseParser",
         "signature": "<bound method Alias.signature of Alias('BaseParser', 'omniread.core.parser.BaseParser')>",
-        "docstring": "Base interface for all parsers.\n\nA parser is a self-contained object that owns the Content\nit is responsible for interpreting.\n\nImplementations must:\n- Declare supported content types via `supported_types`\n- Raise parsing-specific exceptions from `parse()`\n- Remain deterministic for a given input\n\nConsumers may rely on:\n- Early validation of content compatibility\n- Type-stable return values from `parse()`",
+        "docstring": "Base interface for all parsers.\n\nNotes:\n    **Guarantees:**\n\n        - A parser is a self-contained object that owns the Content it is responsible for interpreting\n        - Consumers may rely on early validation of content compatibility and type-stable return values from `parse()`\n\n    **Responsibilities:**\n\n        - Implementations must declare supported content types via `supported_types`\n        - Implementations must raise parsing-specific exceptions from `parse()`\n        - Implementations must remain deterministic for a given input",
         "members": {
           "supported_types": {
             "name": "supported_types",
             "kind": "attribute",
             "path": "omniread.pdf.parser.BaseParser.supported_types",
             "signature": "<bound method Alias.signature of Alias('supported_types', 'omniread.core.parser.BaseParser.supported_types')>",
-            "docstring": "Set of content types supported by this parser.\n\nAn empty set indicates that the parser is content-type agnostic."
+            "docstring": "Set of content types supported by this parser. An empty set indicates that the parser is content-type agnostic."
           },
           "content": {
             "name": "content",
@@ -88,14 +88,14 @@
             "kind": "function",
             "path": "omniread.pdf.parser.BaseParser.parse",
             "signature": "<bound method Alias.signature of Alias('parse', 'omniread.core.parser.BaseParser.parse')>",
-            "docstring": "Parse the owned content into structured output.\n\nImplementations must fully consume the provided content and\nreturn a deterministic, structured output.\n\nReturns:\n    Parsed, structured representation.\n\nRaises:\n    Exception: Parsing-specific errors as defined by the implementation."
+            "docstring": "Parse the owned content into structured output.\n\nReturns:\n    T:\n        Parsed, structured representation.\n\nRaises:\n    Exception:\n        Parsing-specific errors as defined by the implementation.\n\nNotes:\n    **Responsibilities:**\n\n        - Implementations must fully consume the provided content and return a deterministic, structured output"
           },
           "supports": {
             "name": "supports",
             "kind": "function",
             "path": "omniread.pdf.parser.BaseParser.supports",
             "signature": "<bound method Alias.signature of Alias('supports', 'omniread.core.parser.BaseParser.supports')>",
-            "docstring": "Check whether this parser supports the content's type.\n\nReturns:\n    True if the content type is supported; False otherwise."
+            "docstring": "Check whether this parser supports the content's type.\n\nReturns:\n    bool:\n        True if the content type is supported; False otherwise."
           }
         }
       },
@@ -110,8 +110,8 @@
         "name": "PDFParser",
         "kind": "class",
         "path": "omniread.pdf.parser.PDFParser",
-        "signature": "<bound method Class.signature of Class('PDFParser', 20, 49)>",
+        "signature": "<bound method Class.signature of Class('PDFParser', 24, 61)>",
-        "docstring": "Base PDF parser.\n\nThis class enforces PDF content-type compatibility and provides the\nextension point for implementing concrete PDF parsing strategies.\n\nConcrete implementations must define:\n- Define the output type `T`\n- Implement the `parse()` method",
+        "docstring": "Base PDF parser.\n\nNotes:\n    **Responsibilities:**\n\n        - This class enforces PDF content-type compatibility and provides the extension point for implementing concrete PDF parsing strategies\n\n    **Constraints:**\n\n        - Concrete implementations must: Define the output type `T`, implement the `parse()` method",
         "members": {
           "supported_types": {
             "name": "supported_types",
@@ -124,8 +124,8 @@
             "name": "parse",
             "kind": "function",
             "path": "omniread.pdf.parser.PDFParser.parse",
-            "signature": "<bound method Function.signature of Function('parse', 35, 49)>",
+            "signature": "<bound method Function.signature of Function('parse', 43, 61)>",
-            "docstring": "Parse PDF content into a structured output.\n\nImplementations must fully interpret the PDF binary payload and\nreturn a deterministic, structured output.\n\nReturns:\n    Parsed representation of type `T`.\n\nRaises:\n    Exception: Parsing-specific errors as defined by the implementation."
+            "docstring": "Parse PDF content into a structured output.\n\nReturns:\n    T:\n        Parsed representation of type `T`.\n\nRaises:\n    Exception:\n        Parsing-specific errors as defined by the implementation.\n\nNotes:\n    **Responsibilities:**\n\n        - Implementations must fully interpret the PDF binary payload and return a deterministic, structured output"
           }
         }
       }

mcp_docs/modules/omniread.pdf.scraper.json

@@ -2,7 +2,7 @@
   "module": "omniread.pdf.scraper",
   "content": {
     "path": "omniread.pdf.scraper",
-    "docstring": "PDF scraping implementation for OmniRead.\n\nThis module provides a PDF-specific scraper that coordinates PDF byte\nretrieval via a client and normalizes the result into a `Content` object.\n\nThe scraper implements the core `BaseScraper` contract while delegating\nall storage and access concerns to a `BasePDFClient` implementation.",
+    "docstring": "PDF scraping implementation for OmniRead.\n\n---\n\n## Summary\n\nThis module provides a PDF-specific scraper that coordinates PDF byte\nretrieval via a client and normalizes the result into a `Content` object.\n\nThe scraper implements the core `BaseScraper` contract while delegating\nall storage and access concerns to a `BasePDFClient` implementation.",
     "objects": {
       "Any": {
         "name": "Any",
@@ -30,35 +30,35 @@
         "kind": "class",
         "path": "omniread.pdf.scraper.Content",
         "signature": "<bound method Alias.signature of Alias('Content', 'omniread.core.content.Content')>",
-        "docstring": "Normalized representation of extracted content.\n\nA `Content` instance represents a raw content payload along with minimal\ncontextual metadata describing its origin and type.\n\nThis class is the **primary exchange format** between:\n- Scrapers\n- Parsers\n- Downstream consumers\n\nAttributes:\n    raw: Raw content bytes as retrieved from the source.\n    source: Identifier of the content origin (URL, file path, or logical name).\n    content_type: Optional MIME type of the content, if known.\n    metadata: Optional, implementation-defined metadata associated with\n        the content (e.g., headers, encoding hints, extraction notes).",
+        "docstring": "Normalized representation of extracted content.\n\nNotes:\n    **Responsibilities:**\n\n        - A `Content` instance represents a raw content payload along with minimal contextual metadata describing its origin and type\n        - This class is the primary exchange format between Scrapers, Parsers, and Downstream consumers",
         "members": {
           "raw": {
             "name": "raw",
             "kind": "attribute",
             "path": "omniread.pdf.scraper.Content.raw",
             "signature": "<bound method Alias.signature of Alias('raw', 'omniread.core.content.Content.raw')>",
-            "docstring": null
+            "docstring": "Raw content bytes as retrieved from the source."
           },
           "source": {
             "name": "source",
             "kind": "attribute",
             "path": "omniread.pdf.scraper.Content.source",
             "signature": "<bound method Alias.signature of Alias('source', 'omniread.core.content.Content.source')>",
-            "docstring": null
+            "docstring": "Identifier of the content origin (URL, file path, or logical name)."
           },
           "content_type": {
             "name": "content_type",
             "kind": "attribute",
             "path": "omniread.pdf.scraper.Content.content_type",
             "signature": "<bound method Alias.signature of Alias('content_type', 'omniread.core.content.Content.content_type')>",
-            "docstring": null
+            "docstring": "Optional MIME type of the content, if known."
           },
           "metadata": {
             "name": "metadata",
             "kind": "attribute",
             "path": "omniread.pdf.scraper.Content.metadata",
             "signature": "<bound method Alias.signature of Alias('metadata', 'omniread.core.content.Content.metadata')>",
-            "docstring": null
+            "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)."
           }
         }
       },
@@ -67,7 +67,7 @@
         "kind": "class",
         "path": "omniread.pdf.scraper.ContentType",
         "signature": "<bound method Alias.signature of Alias('ContentType', 'omniread.core.content.ContentType')>",
-        "docstring": "Supported MIME types for extracted content.\n\nThis enum represents the declared or inferred media type of the content\nsource. It is primarily used for routing content to the appropriate\nparser or downstream consumer.",
+        "docstring": "Supported MIME types for extracted content.\n\nNotes:\n    **Guarantees:**\n\n        - This enum represents the declared or inferred media type of the content source\n        - It is primarily used for routing content to the appropriate parser or downstream consumer",
         "members": {
           "HTML": {
             "name": "HTML",
@@ -104,14 +104,14 @@
         "kind": "class",
         "path": "omniread.pdf.scraper.BaseScraper",
         "signature": "<bound method Alias.signature of Alias('BaseScraper', 'omniread.core.scraper.BaseScraper')>",
-        "docstring": "Base interface for all scrapers.\n\nA scraper is responsible ONLY for fetching raw content\n(bytes) from a source. It must not interpret or parse it.\n\nA scraper is a **stateless acquisition component** that retrieves raw\ncontent from a source and returns it as a `Content` object.\n\nScrapers define *how content is obtained*, not *what the content means*.\n\nImplementations may vary in:\n- Transport mechanism (HTTP, filesystem, cloud storage)\n- Authentication strategy\n- Retry and backoff behavior\n\nImplementations must not:\n- Parse content\n- Modify content semantics\n- Couple scraping logic to a specific parser",
+        "docstring": "Base interface for all scrapers.\n\nNotes:\n    **Responsibilities:**\n\n        - A scraper is responsible ONLY for fetching raw content (bytes) from a source. It must not interpret or parse it\n        - A scraper is a stateless acquisition component that retrieves raw content from a source and returns it as a `Content` object\n        - Scrapers define how content is obtained, not what the content means\n        - Implementations may vary in transport mechanism, authentication strategy, retry and backoff behavior\n\n    **Constraints:**\n\n        - Implementations must not parse content, modify content semantics, or couple scraping logic to a specific parser",
         "members": {
           "fetch": {
             "name": "fetch",
             "kind": "function",
             "path": "omniread.pdf.scraper.BaseScraper.fetch",
             "signature": "<bound method Alias.signature of Alias('fetch', 'omniread.core.scraper.BaseScraper.fetch')>",
-            "docstring": "Fetch raw content from the given source.\n\nImplementations must retrieve the content referenced by `source`\nand return it as raw bytes wrapped in a `Content` object.\n\nArgs:\n    source: Location identifier (URL, file path, S3 URI, etc.)\n    metadata: Optional hints for the scraper (headers, auth, etc.)\n\nReturns:\n    Content object containing raw bytes and metadata.\n    - Raw content bytes\n    - Source identifier\n    - Optional metadata\n\nRaises:\n    Exception: Retrieval-specific errors as defined by the implementation."
+            "docstring": "Fetch raw content from the given source.\n\nArgs:\n    source (str):\n        Location identifier (URL, file path, S3 URI, etc.)\n    metadata (Optional[Mapping[str, Any]], optional):\n        Optional hints for the scraper (headers, auth, etc.)\n\nReturns:\n    Content:\n        Content object containing raw bytes and metadata.\n\nRaises:\n    Exception:\n        Retrieval-specific errors as defined by the implementation.\n\nNotes:\n    **Responsibilities:**\n\n        - Implementations must retrieve the content referenced by `source` and return it as raw bytes wrapped in a `Content` object"
           }
         }
       },
@@ -120,14 +120,14 @@
         "kind": "class",
         "path": "omniread.pdf.scraper.BasePDFClient",
         "signature": "<bound method Alias.signature of Alias('BasePDFClient', 'omniread.pdf.client.BasePDFClient')>",
-        "docstring": "Abstract client responsible for retrieving PDF bytes\nfrom a specific backing store (filesystem, S3, FTP, etc.).\n\nImplementations must:\n- Accept a source identifier appropriate to the backing store\n- Return the full PDF binary payload\n- Raise retrieval-specific errors on failure",
+        "docstring": "Abstract client responsible for retrieving PDF bytes\nfrom a specific backing store (filesystem, S3, FTP, etc.).\n\nNotes:\n    **Responsibilities:**\n\n        - Implementations must accept a source identifier appropriate to the backing store, return the full PDF binary payload, and raise retrieval-specific errors on failure",
         "members": {
           "fetch": {
             "name": "fetch",
             "kind": "function",
             "path": "omniread.pdf.scraper.BasePDFClient.fetch",
             "signature": "<bound method Alias.signature of Alias('fetch', 'omniread.pdf.client.BasePDFClient.fetch')>",
-            "docstring": "Fetch raw PDF bytes from the given source.\n\nArgs:\n    source: Identifier of the PDF location, such as a file path,\n        object storage key, or remote reference.\n\nReturns:\n    Raw PDF bytes.\n\nRaises:\n    Exception: Retrieval-specific errors defined by the implementation."
+            "docstring": "Fetch raw PDF bytes from the given source.\n\nArgs:\n    source (Any):\n        Identifier of the PDF location, such as a file path, object storage key, or remote reference.\n\nReturns:\n    bytes:\n        Raw PDF bytes.\n\nRaises:\n    Exception:\n        Retrieval-specific errors defined by the implementation."
           }
         }
       },
@@ -135,15 +135,15 @@
         "name": "PDFScraper",
         "kind": "class",
         "path": "omniread.pdf.scraper.PDFScraper",
-        "signature": "<bound method Class.signature of Class('PDFScraper', 18, 71)>",
+        "signature": "<bound method Class.signature of Class('PDFScraper', 22, 77)>",
-        "docstring": "Scraper for PDF sources.\n\nDelegates byte retrieval to a PDF client and normalizes\noutput into Content.\n\nThe scraper:\n- Does not perform parsing or interpretation\n- Does not assume a specific storage backend\n- Preserves caller-provided metadata",
+        "docstring": "Scraper for PDF sources.\n\nNotes:\n    **Responsibilities:**\n\n        - Delegates byte retrieval to a PDF client and normalizes output into Content\n        - Preserves caller-provided metadata\n\n    **Constraints:**\n    \n        - The scraper: Does not perform parsing or interpretation, does not assume a specific storage backend",
         "members": {
           "fetch": {
             "name": "fetch",
             "kind": "function",
             "path": "omniread.pdf.scraper.PDFScraper.fetch",
-            "signature": "<bound method Function.signature of Function('fetch', 40, 71)>",
+            "signature": "<bound method Function.signature of Function('fetch', 47, 77)>",
-            "docstring": "Fetch a PDF document from the given source.\n\nArgs:\n    source: Identifier of the PDF source as understood by the\n        configured PDF client.\n    metadata: Optional metadata to attach to the returned content.\n\nReturns:\n    A `Content` instance containing:\n    - Raw PDF bytes\n    - Source identifier\n    - PDF content type\n    - Optional metadata\n\nRaises:\n    Exception: Retrieval-specific errors raised by the PDF client."
+            "docstring": "Fetch a PDF document from the given source.\n\nArgs:\n    source (Any):\n        Identifier of the PDF source as understood by the configured PDF client.\n    metadata (Optional[Mapping[str, Any]], optional):\n        Optional metadata to attach to the returned content.\n\nReturns:\n    Content:\n        A `Content` instance containing raw PDF bytes, source identifier, PDF content type, and optional metadata.\n\nRaises:\n    Exception:\n        Retrieval-specific errors raised by the PDF client."
           }
         }
       }

mkdocs.yml

@@ -8,12 +8,19 @@ theme:
     text: Inter
     code: JetBrains Mono
   features:
-  - navigation.tabs
+  - navigation.sections
   - navigation.expand
   - navigation.top
   - navigation.instant
+  - navigation.tracking
+  - navigation.indexes
   - content.code.copy
   - content.code.annotate
+  - content.tabs.link
+  - content.action.edit
+  - search.highlight
+  - search.share
+  - search.suggest
 plugins:
 - search
 - mkdocstrings:
@@ -31,6 +38,30 @@ plugins:
           annotations_path: brief
           show_root_heading: true
           group_by_category: true
+          show_category_heading: true
+          show_object_full_path: false
+          show_symbol_type_heading: true
+markdown_extensions:
+- pymdownx.superfences
+- pymdownx.inlinehilite
+- pymdownx.snippets
+- admonition
+- pymdownx.details
+- pymdownx.superfences
+- pymdownx.highlight:
+    linenums: true
+    anchor_linenums: true
+    line_spans: __span
+    pygments_lang_class: true
+- pymdownx.tabbed:
+    alternate_style: true
+- pymdownx.tasklist:
+    custom_checkbox: true
+- tables
+- footnotes
+- pymdownx.caret
+- pymdownx.tilde
+- pymdownx.mark
 site_name: omniread
 nav:
 - Home: index.md

omniread/__init__.py

@@ -1,33 +1,28 @@
 """
 OmniRead — format-agnostic content acquisition and parsing framework.
 
+---
+
+## Summary
+
 OmniRead provides a **cleanly layered architecture** for fetching, parsing,
 and normalizing content from heterogeneous sources such as HTML documents
 and PDF files.
 
 The library is structured around three core concepts:
 
-1. **Content**
+1. **Content**: A canonical, format-agnostic container representing raw content bytes and minimal contextual metadata.
-   A canonical, format-agnostic container representing raw content bytes
+2. **Scrapers**: Components responsible for *acquiring* raw content from a source (HTTP, filesystem, object storage, etc.). Scrapers never interpret content.
-   and minimal contextual metadata.
+3. **Parsers**: Components responsible for *interpreting* acquired content and converting it into structured, typed representations.
-
-2. **Scrapers**
-   Components responsible for *acquiring* raw content from a source
-   (HTTP, filesystem, object storage, etc.). Scrapers never interpret
-   content.
-
-3. **Parsers**
-   Components responsible for *interpreting* acquired content and
-   converting it into structured, typed representations.
 
 OmniRead deliberately separates these responsibilities to ensure:
 - Clear boundaries between IO and interpretation
 - Replaceable implementations per format
 - Predictable, testable behavior
 
-----------------------------------------------------------------------
+---
-Installation
+
-----------------------------------------------------------------------
+## Installation
 
 Install OmniRead using pip:
 
@@ -37,9 +32,9 @@ Or with Poetry:
 
     poetry add omniread
 
-----------------------------------------------------------------------
+---
-Basic Usage
+
-----------------------------------------------------------------------
+## Quick start
 
 HTML example:
 
@@ -72,49 +67,35 @@ PDF example:
     parser = TextPDFParser(content)
     result = parser.parse()
 
-----------------------------------------------------------------------
+---
-Public API Surface
+
-----------------------------------------------------------------------
+## Public API
 
 This module re-exports the **recommended public entry points** of OmniRead.
-
 Consumers are encouraged to import from this namespace rather than from
 format-specific submodules directly, unless advanced customization is
 required.
 
-Core:
+**Core:**
 - Content
 - ContentType
 
-HTML:
+**HTML:**
 - HTMLScraper
 - HTMLParser
 
-PDF:
+**PDF:**
 - FileSystemPDFClient
 - PDFScraper
 - PDFParser
 
-## Core Philosophy
+**Core Philosophy:**
-
 `OmniRead` is designed as a **decoupled content engine**:
-
 1. **Separation of Concerns**: Scrapers *fetch*, Parsers *interpret*. Neither knows about the other.
 2. **Normalized Exchange**: All components communicate via the `Content` model, ensuring a consistent contract.
 3. **Format Agnosticism**: The core logic is independent of whether the input is HTML, PDF, or JSON.
 
-## Documentation Design
+---
-
-For those extending `OmniRead`, follow these "AI-Native" docstring principles:
-
-### For Humans
-- **Clear Contracts**: Explicitly state what a component is and is NOT responsible for.
-- **Runnable Examples**: Include small, logical snippets in the package `__init__.py`.
-
-### For LLMs
-- **Structured Models**: Use dataclasses and enums for core data to ensure clean MCP JSON representation.
-- **Type Safety**: All public APIs must be fully typed and have corresponding `.pyi` stubs.
-- **Detailed Raises**: Include `: description` pairs in the `Raises` section to help agents handle errors gracefully.
 """
 
 from .core import Content, ContentType

omniread/core/__init__.py

@@ -1,6 +1,10 @@
 """
 Core domain contracts for OmniRead.
 
+---
+
+## Summary
+
 This package defines the **format-agnostic domain layer** of OmniRead.
 It exposes canonical content models and abstract interfaces that are
 implemented by format-specific modules (HTML, PDF, etc.).
@@ -14,6 +18,15 @@ Submodules:
 - scraper: Abstract scraping contracts
 
 Format-specific behavior must not be introduced at this layer.
+
+---
+
+## Public API
+
+    Content
+    ContentType
+
+---
 """
 
 from .content import Content, ContentType

omniread/core/content.py

@@ -1,6 +1,10 @@
 """
 Canonical content models for OmniRead.
 
+---
+
+## Summary
+
 This module defines the **format-agnostic content representation** used across
 all parsers and scrapers in OmniRead.
 
@@ -18,9 +22,11 @@ class ContentType(str, Enum):
     """
     Supported MIME types for extracted content.
 
-    This enum represents the declared or inferred media type of the content
+    Notes:
-    source. It is primarily used for routing content to the appropriate
+        **Guarantees:**
-    parser or downstream consumer.
+
+            - This enum represents the declared or inferred media type of the content source
+            - It is primarily used for routing content to the appropriate parser or downstream consumer
     """
 
     HTML = "text/html"
@@ -41,23 +47,29 @@ class Content:
     """
     Normalized representation of extracted content.
 
-    A `Content` instance represents a raw content payload along with minimal
+    Notes:
-    contextual metadata describing its origin and type.
+        **Responsibilities:**
 
-    This class is the **primary exchange format** between:
+            - A `Content` instance represents a raw content payload along with minimal contextual metadata describing its origin and type
-    - Scrapers
+            - This class is the primary exchange format between Scrapers, Parsers, and Downstream consumers
-    - Parsers
-    - Downstream consumers
-
-    Attributes:
-        raw: Raw content bytes as retrieved from the source.
-        source: Identifier of the content origin (URL, file path, or logical name).
-        content_type: Optional MIME type of the content, if known.
-        metadata: Optional, implementation-defined metadata associated with
-            the content (e.g., headers, encoding hints, extraction notes).
     """
 
     raw: bytes
+    """
+    Raw content bytes as retrieved from the source.
+    """
+
     source: str
+    """
+    Identifier of the content origin (URL, file path, or logical name).
+    """
+
     content_type: Optional[ContentType] = None
+    """
+    Optional MIME type of the content, if known.
+    """
+
     metadata: Optional[Mapping[str, Any]] = None
+    """
+    Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes).
+    """

omniread/core/parser.py

@@ -1,6 +1,10 @@
 """
 Abstract parsing contracts for OmniRead.
 
+---
+
+## Summary
+
 This module defines the **format-agnostic parser interface** used to transform
 raw content into structured, typed representations.
 
@@ -27,23 +31,22 @@ class BaseParser(ABC, Generic[T]):
     """
     Base interface for all parsers.
 
-    A parser is a self-contained object that owns the Content
+    Notes:
-    it is responsible for interpreting.
+        **Guarantees:**
 
-    Implementations must:
+            - A parser is a self-contained object that owns the Content it is responsible for interpreting
-    - Declare supported content types via `supported_types`
+            - Consumers may rely on early validation of content compatibility and type-stable return values from `parse()`
-    - Raise parsing-specific exceptions from `parse()`
-    - Remain deterministic for a given input
 
-    Consumers may rely on:
+        **Responsibilities:**
-    - Early validation of content compatibility
+
-    - Type-stable return values from `parse()`
+            - Implementations must declare supported content types via `supported_types`
+            - Implementations must raise parsing-specific exceptions from `parse()`
+            - Implementations must remain deterministic for a given input
     """
 
     supported_types: Set[ContentType] = set()
-    """Set of content types supported by this parser.
+    """
-
+    Set of content types supported by this parser. An empty set indicates that the parser is content-type agnostic.
-    An empty set indicates that the parser is content-type agnostic.
     """
 
     def __init__(self, content: Content):
@@ -51,10 +54,12 @@ class BaseParser(ABC, Generic[T]):
         Initialize the parser with content to be parsed.
 
         Args:
-            content: Content instance to be parsed.
+            content (Content):
+                Content instance to be parsed.
 
         Raises:
-            ValueError: If the content type is not supported by this parser.
+            ValueError:
+                If the content type is not supported by this parser.
         """
 
         self.content = content
@@ -70,14 +75,18 @@ class BaseParser(ABC, Generic[T]):
         """
         Parse the owned content into structured output.
 
-        Implementations must fully consume the provided content and
-        return a deterministic, structured output.
-
         Returns:
-            Parsed, structured representation.
+            T:
+                Parsed, structured representation.
 
         Raises:
-            Exception: Parsing-specific errors as defined by the implementation.
+            Exception:
+                Parsing-specific errors as defined by the implementation.
+
+        Notes:
+            **Responsibilities:**
+
+                - Implementations must fully consume the provided content and return a deterministic, structured output
         """
         raise NotImplementedError
 
@@ -86,7 +95,8 @@ class BaseParser(ABC, Generic[T]):
         Check whether this parser supports the content's type.
 
         Returns:
-            True if the content type is supported; False otherwise.
+            bool:
+                True if the content type is supported; False otherwise.
         """
 
         if not self.supported_types:

omniread/core/scraper.py

@@ -1,6 +1,10 @@
 """
 Abstract scraping contracts for OmniRead.
 
+---
+
+## Summary
+
 This module defines the **format-agnostic scraper interface** responsible for
 acquiring raw content from external sources.
 
@@ -27,23 +31,17 @@ class BaseScraper(ABC):
     """
     Base interface for all scrapers.
 
-    A scraper is responsible ONLY for fetching raw content
+    Notes:
-    (bytes) from a source. It must not interpret or parse it.
+        **Responsibilities:**
 
-    A scraper is a **stateless acquisition component** that retrieves raw
+            - A scraper is responsible ONLY for fetching raw content (bytes) from a source. It must not interpret or parse it
-    content from a source and returns it as a `Content` object.
+            - A scraper is a stateless acquisition component that retrieves raw content from a source and returns it as a `Content` object
+            - Scrapers define how content is obtained, not what the content means
+            - Implementations may vary in transport mechanism, authentication strategy, retry and backoff behavior
 
-    Scrapers define *how content is obtained*, not *what the content means*.
+        **Constraints:**
 
-    Implementations may vary in:
+            - Implementations must not parse content, modify content semantics, or couple scraping logic to a specific parser
-    - Transport mechanism (HTTP, filesystem, cloud storage)
-    - Authentication strategy
-    - Retry and backoff behavior
-
-    Implementations must not:
-    - Parse content
-    - Modify content semantics
-    - Couple scraping logic to a specific parser
     """
 
     @abstractmethod
@@ -56,20 +54,23 @@ class BaseScraper(ABC):
         """
         Fetch raw content from the given source.
 
-        Implementations must retrieve the content referenced by `source`
-        and return it as raw bytes wrapped in a `Content` object.
-
         Args:
-            source: Location identifier (URL, file path, S3 URI, etc.)
+            source (str):
-            metadata: Optional hints for the scraper (headers, auth, etc.)
+                Location identifier (URL, file path, S3 URI, etc.)
+            metadata (Optional[Mapping[str, Any]], optional):
+                Optional hints for the scraper (headers, auth, etc.)
 
         Returns:
-            Content object containing raw bytes and metadata.
+            Content:
-            - Raw content bytes
+                Content object containing raw bytes and metadata.
-            - Source identifier
-            - Optional metadata
 
         Raises:
-            Exception: Retrieval-specific errors as defined by the implementation.
+            Exception:
+                Retrieval-specific errors as defined by the implementation.
+
+        Notes:
+            **Responsibilities:**
+
+                - Implementations must retrieve the content referenced by `source` and return it as raw bytes wrapped in a `Content` object
         """
         raise NotImplementedError

omniread/html/__init__.py

@@ -1,6 +1,10 @@
 """
 HTML format implementation for OmniRead.
 
+---
+
+## Summary
+
 This package provides **HTML-specific implementations** of the core OmniRead
 contracts defined in `omniread.core`.
 
@@ -15,6 +19,15 @@ This package:
 
 Consumers should depend on `omniread.core` interfaces wherever possible and
 use this package only when HTML-specific behavior is required.
+
+---
+
+## Public API
+
+    HTMLScraper
+    HTMLParser
+
+---
 """
 
 

omniread/html/parser.py

@@ -1,6 +1,10 @@
 """
 HTML parser base implementations for OmniRead.
 
+---
+
+## Summary
+
 This module provides reusable HTML parsing utilities built on top of
 the abstract parser contracts defined in `omniread.core.parser`.
 
@@ -28,36 +32,39 @@ class HTMLParser(BaseParser[T], Generic[T]):
     """
     Base HTML parser.
 
-    This class extends the core `BaseParser` with HTML-specific behavior,
+    Notes:
-    including DOM parsing via BeautifulSoup and reusable extraction helpers.
+        **Responsibilities:**
 
-    Provides reusable helpers for HTML extraction.
+            - This class extends the core `BaseParser` with HTML-specific behavior, including DOM parsing via BeautifulSoup and reusable extraction helpers
-    Concrete parsers must explicitly define the return type.
+            - Provides reusable helpers for HTML extraction. Concrete parsers must explicitly define the return type
 
-    Characteristics:
+        **Guarantees:**
-    - Accepts only HTML content
-    - Owns a parsed BeautifulSoup DOM tree
-    - Provides pure helper utilities for common HTML structures
 
-    Concrete subclasses must:
+            - Characteristics: Accepts only HTML content, owns a parsed BeautifulSoup DOM tree, provides pure helper utilities for common HTML structures
-    - Define the output type `T`
+
-    - Implement the `parse()` method
+        **Constraints:**
+        
+            - Concrete subclasses must define the output type `T` and implement the `parse()` method
     """
 
     supported_types = {ContentType.HTML}
-    """Set of content types supported by this parser (HTML only)."""
+    """
+    Set of content types supported by this parser (HTML only).
+    """
 
     def __init__(self, content: Content, features: str = "html.parser"):
         """
         Initialize the HTML parser.
 
         Args:
-            content: HTML content to be parsed.
+            content (Content):
-            features: BeautifulSoup parser backend to use
+                HTML content to be parsed.
-                (e.g., 'html.parser', 'lxml').
+            features (str, optional):
+                BeautifulSoup parser backend to use (e.g., 'html.parser', 'lxml').
 
         Raises:
-            ValueError: If the content is empty or not valid HTML.
+            ValueError:
+                If the content is empty or not valid HTML.
         """
         super().__init__(content)
         self._features = features
@@ -72,11 +79,14 @@ class HTMLParser(BaseParser[T], Generic[T]):
         """
         Fully parse the HTML content into structured output.
 
-        Implementations must fully interpret the HTML DOM and return
-        a deterministic, structured output.
-
         Returns:
-            Parsed representation of type `T`.
+            T:
+                Parsed representation of type `T`.
+
+        Notes:
+            **Responsibilities:**
+
+                - Implementations must fully interpret the HTML DOM and return a deterministic, structured output
         """
         raise NotImplementedError
 
@@ -90,11 +100,14 @@ class HTMLParser(BaseParser[T], Generic[T]):
         Extract normalized text from a `<div>` element.
 
         Args:
-            div: BeautifulSoup tag representing a `<div>`.
+            div (Tag):
-            separator: String used to separate text nodes.
+                BeautifulSoup tag representing a `<div>`.
+            separator (str, optional):
+                String used to separate text nodes.
 
         Returns:
-            Flattened, whitespace-normalized text content.
+            str:
+                Flattened, whitespace-normalized text content.
         """
         return div.get_text(separator=separator, strip=True)
 
@@ -104,10 +117,12 @@ class HTMLParser(BaseParser[T], Generic[T]):
         Extract the hyperlink reference from an `<a>` element.
 
         Args:
-            a: BeautifulSoup tag representing an anchor.
+            a (Tag):
+                BeautifulSoup tag representing an anchor.
 
         Returns:
-            The value of the `href` attribute, or None if absent.
+            Optional[str]:
+                The value of the `href` attribute, or None if absent.
         """
         return a.get("href")
 
@@ -117,10 +132,12 @@ class HTMLParser(BaseParser[T], Generic[T]):
         Parse an HTML table into a 2D list of strings.
 
         Args:
-            table: BeautifulSoup tag representing a `<table>`.
+            table (Tag):
+                BeautifulSoup tag representing a `<table>`.
 
         Returns:
-            A list of rows, where each row is a list of cell text values.
+            list[list[str]]:
+                A list of rows, where each row is a list of cell text values.
         """
         rows: list[list[str]] = []
         for tr in table.find_all("tr"):
@@ -141,10 +158,12 @@ class HTMLParser(BaseParser[T], Generic[T]):
         Build a BeautifulSoup DOM tree from raw HTML content.
 
         Returns:
-            Parsed BeautifulSoup document tree.
+            BeautifulSoup:
+                Parsed BeautifulSoup document tree.
 
         Raises:
-            ValueError: If the content payload is empty.
+            ValueError:
+                If the content payload is empty.
         """
         if not self.content.raw:
             raise ValueError("Empty HTML content")
@@ -154,12 +173,15 @@ class HTMLParser(BaseParser[T], Generic[T]):
         """
         Extract high-level metadata from the HTML document.
 
-        This includes:
-        - Document title
-        - `<meta>` tag name/property → content mappings
-
         Returns:
-            Dictionary containing extracted metadata.
+            dict[str, Any]:
+                Dictionary containing extracted metadata.
+
+        Notes:
+            **Responsibilities:**
+
+                - Extract high-level metadata from the HTML document
+                - This includes: Document title, `<meta>` tag name/property → content mappings
         """
         soup = self._soup
 

omniread/html/scraper.py

@@ -1,6 +1,10 @@
 """
 HTML scraping implementation for OmniRead.
 
+---
+
+## Summary
+
 This module provides an HTTP-based scraper for retrieving HTML documents.
 It implements the core `BaseScraper` contract using `httpx` as the transport
 layer.
@@ -27,19 +31,15 @@ class HTMLScraper(BaseScraper):
     """
     Base HTML scraper using httpx.
 
-    This scraper retrieves HTML documents over HTTP(S) and returns them
+    Notes:
-    as raw content wrapped in a `Content` object.
+        **Responsibilities:**
 
-    Fetches raw bytes and metadata only.
+            - This scraper retrieves HTML documents over HTTP(S) and returns them as raw content wrapped in a `Content` object
-    The scraper:
+            - Fetches raw bytes and metadata only. The scraper uses `httpx.Client` for HTTP requests, enforces an HTML content type, preserves HTTP response metadata
-    - Uses `httpx.Client` for HTTP requests
-    - Enforces an HTML content type
-    - Preserves HTTP response metadata
 
-    The scraper does not:
+        **Constraints:**
-    - Parse HTML
+        
-    - Perform retries or backoff
+            - The scraper does not: Parse HTML, perform retries or backoff, handle non-HTML responses
-    - Handle non-HTML responses
     """
 
     def __init__(
@@ -54,11 +54,14 @@ class HTMLScraper(BaseScraper):
         Initialize the HTML scraper.
 
         Args:
-            client: Optional pre-configured `httpx.Client`. If omitted,
+            client (httpx.Client | None, optional):
-                a client is created internally.
+                Optional pre-configured `httpx.Client`. If omitted, a client is created internally.
-            timeout: Request timeout in seconds.
+            timeout (float, optional):
-            headers: Optional default HTTP headers.
+                Request timeout in seconds.
-            follow_redirects: Whether to follow HTTP redirects.
+            headers (Optional[Mapping[str, str]], optional):
+                Optional default HTTP headers.
+            follow_redirects (bool, optional):
+                Whether to follow HTTP redirects.
         """
 
         self._client = client or httpx.Client(
@@ -76,11 +79,12 @@ class HTMLScraper(BaseScraper):
         Validate that the HTTP response contains HTML content.
 
         Args:
-            response: HTTP response returned by `httpx`.
+            response (httpx.Response):
+                HTTP response returned by `httpx`.
 
         Raises:
-            ValueError: If the `Content-Type` header is missing or does not
+            ValueError:
-                indicate HTML content.
+                If the `Content-Type` header is missing or does not indicate HTML content.
         """
 
         raw_ct = response.headers.get("Content-Type")
@@ -103,19 +107,20 @@ class HTMLScraper(BaseScraper):
         Fetch an HTML document from the given source.
 
         Args:
-            source: URL of the HTML document.
+            source (str):
-            metadata: Optional metadata to be merged into the returned content.
+                URL of the HTML document.
+            metadata (Optional[Mapping[str, Any]], optional):
+                Optional metadata to be merged into the returned content.
 
         Returns:
-            A `Content` instance containing:
+            Content:
-            - Raw HTML bytes
+                A `Content` instance containing raw HTML bytes, source URL, HTML content type, and HTTP response metadata.
-            - Source URL
-            - HTML content type
-            - HTTP response metadata
 
         Raises:
-            httpx.HTTPError: If the HTTP request fails.
+            httpx.HTTPError:
-            ValueError: If the response is not valid HTML.
+                If the HTTP request fails.
+            ValueError:
+                If the response is not valid HTML.
         """
 
         response = self._client.get(source)

omniread/pdf/__init__.py

@@ -1,6 +1,10 @@
 """
 PDF format implementation for OmniRead.
 
+---
+
+## Summary
+
 This package provides **PDF-specific implementations** of the core OmniRead
 contracts defined in `omniread.core`.
 
@@ -12,6 +16,16 @@ access. This package therefore includes:
 
 Public exports from this package represent the supported PDF pipeline
 and are safe for consumers to import directly when working with PDFs.
+
+---
+
+## Public API
+
+    FileSystemPDFClient
+    PDFScraper
+    PDFParser
+
+---
 """
 
 from .client import FileSystemPDFClient

omniread/pdf/client.py

@@ -1,6 +1,10 @@
 """
 PDF client abstractions for OmniRead.
 
+---
+
+## Summary
+
 This module defines the **client layer** responsible for retrieving raw PDF
 bytes from a concrete backing store.
 
@@ -24,10 +28,10 @@ class BasePDFClient(ABC):
     Abstract client responsible for retrieving PDF bytes
     from a specific backing store (filesystem, S3, FTP, etc.).
 
-    Implementations must:
+    Notes:
-    - Accept a source identifier appropriate to the backing store
+        **Responsibilities:**
-    - Return the full PDF binary payload
+
-    - Raise retrieval-specific errors on failure
+            - Implementations must accept a source identifier appropriate to the backing store, return the full PDF binary payload, and raise retrieval-specific errors on failure
     """
 
     @abstractmethod
@@ -36,14 +40,16 @@ class BasePDFClient(ABC):
         Fetch raw PDF bytes from the given source.
 
         Args:
-            source: Identifier of the PDF location, such as a file path,
+            source (Any):
-                object storage key, or remote reference.
+                Identifier of the PDF location, such as a file path, object storage key, or remote reference.
 
         Returns:
-            Raw PDF bytes.
+            bytes:
+                Raw PDF bytes.
 
         Raises:
-            Exception: Retrieval-specific errors defined by the implementation.
+            Exception:
+                Retrieval-specific errors defined by the implementation.
         """
         raise NotImplementedError
 
@@ -52,8 +58,10 @@ class FileSystemPDFClient(BasePDFClient):
     """
     PDF client that reads from the local filesystem.
 
-    This client reads PDF files directly from the disk and returns their raw
+    Notes:
-    binary contents.
+        **Guarantees:**
+
+            - This client reads PDF files directly from the disk and returns their raw binary contents
     """
 
     def fetch(self, path: Path) -> bytes:
@@ -61,14 +69,18 @@ class FileSystemPDFClient(BasePDFClient):
         Read a PDF file from the local filesystem.
 
         Args:
-            path: Filesystem path to the PDF file.
+            path (Path):
+                Filesystem path to the PDF file.
 
         Returns:
-            Raw PDF bytes.
+            bytes:
+                Raw PDF bytes.
 
         Raises:
-            FileNotFoundError: If the path does not exist.
+            FileNotFoundError:
-            ValueError: If the path exists but is not a file.
+                If the path does not exist.
+            ValueError:
+                If the path exists but is not a file.
         """
 
         if not path.exists():

omniread/pdf/parser.py

@@ -1,6 +1,10 @@
 """
 PDF parser base implementations for OmniRead.
 
+---
+
+## Summary
+
 This module defines the **PDF-specific parser contract**, extending the
 format-agnostic `BaseParser` with constraints appropriate for PDF content.
 
@@ -21,29 +25,37 @@ class PDFParser(BaseParser[T], Generic[T]):
     """
     Base PDF parser.
 
-    This class enforces PDF content-type compatibility and provides the
+    Notes:
-    extension point for implementing concrete PDF parsing strategies.
+        **Responsibilities:**
 
-    Concrete implementations must define:
+            - This class enforces PDF content-type compatibility and provides the extension point for implementing concrete PDF parsing strategies
-    - Define the output type `T`
+
-    - Implement the `parse()` method
+        **Constraints:**
+
+            - Concrete implementations must: Define the output type `T`, implement the `parse()` method
     """
 
     supported_types = {ContentType.PDF}
-    """Set of content types supported by this parser (PDF only)."""
+    """
+    Set of content types supported by this parser (PDF only).
+    """
 
     @abstractmethod
     def parse(self) -> T:
         """
         Parse PDF content into a structured output.
 
-        Implementations must fully interpret the PDF binary payload and
-        return a deterministic, structured output.
-
         Returns:
-            Parsed representation of type `T`.
+            T:
+                Parsed representation of type `T`.
 
         Raises:
-            Exception: Parsing-specific errors as defined by the implementation.
+            Exception:
+                Parsing-specific errors as defined by the implementation.
+
+        Notes:
+            **Responsibilities:**
+
+                - Implementations must fully interpret the PDF binary payload and return a deterministic, structured output
         """
         raise NotImplementedError

omniread/pdf/scraper.py

@@ -1,6 +1,10 @@
 """
 PDF scraping implementation for OmniRead.
 
+---
+
+## Summary
+
 This module provides a PDF-specific scraper that coordinates PDF byte
 retrieval via a client and normalizes the result into a `Content` object.
 
@@ -19,13 +23,15 @@ class PDFScraper(BaseScraper):
     """
     Scraper for PDF sources.
 
-    Delegates byte retrieval to a PDF client and normalizes
+    Notes:
-    output into Content.
+        **Responsibilities:**
 
-    The scraper:
+            - Delegates byte retrieval to a PDF client and normalizes output into Content
-    - Does not perform parsing or interpretation
+            - Preserves caller-provided metadata
-    - Does not assume a specific storage backend
+
-    - Preserves caller-provided metadata
+        **Constraints:**
+        
+            - The scraper: Does not perform parsing or interpretation, does not assume a specific storage backend
     """
 
     def __init__(self, *, client: BasePDFClient):
@@ -33,7 +39,8 @@ class PDFScraper(BaseScraper):
         Initialize the PDF scraper.
 
         Args:
-            client: PDF client responsible for retrieving raw PDF bytes.
+            client (BasePDFClient):
+                PDF client responsible for retrieving raw PDF bytes.
         """
         self._client = client
 
@@ -47,19 +54,18 @@ class PDFScraper(BaseScraper):
         Fetch a PDF document from the given source.
 
         Args:
-            source: Identifier of the PDF source as understood by the
+            source (Any):
-                configured PDF client.
+                Identifier of the PDF source as understood by the configured PDF client.
-            metadata: Optional metadata to attach to the returned content.
+            metadata (Optional[Mapping[str, Any]], optional):
+                Optional metadata to attach to the returned content.
 
         Returns:
-            A `Content` instance containing:
+            Content:
-            - Raw PDF bytes
+                A `Content` instance containing raw PDF bytes, source identifier, PDF content type, and optional metadata.
-            - Source identifier
-            - PDF content type
-            - Optional metadata
 
         Raises:
-            Exception: Retrieval-specific errors raised by the PDF client.
+            Exception:
+                Retrieval-specific errors raised by the PDF client.
         """
         raw = self._client.fetch(source)