updated docs strings and added README.md

mail_intake/ingestion/__init__.py

@@ -1,10 +1,8 @@
 """
+# Summary
+
 Mail ingestion orchestration for Mail Intake.
 
----
-
-## Summary
-
 This package contains **high-level ingestion components** responsible for
 coordinating mail retrieval, parsing, normalization, and model construction.
 
@@ -12,19 +10,20 @@ It represents the **top of the ingestion pipeline** and is intended to be the
 primary interaction surface for library consumers.
 
 Components in this package:
-- Are provider-agnostic
-- Depend only on adapter and parser contracts
-- Contain no provider-specific API logic
-- Expose read-only ingestion workflows
+
+- Are provider-agnostic.
+- Depend only on adapter and parser contracts.
+- Contain no provider-specific API logic.
+- Expose read-only ingestion workflows.
 
 Consumers are expected to construct a mail adapter and pass it to the
 ingestion layer to begin processing messages and threads.
 
 ---
 
-## Public API
+# Public API
 
-    MailIntakeReader
+- `MailIntakeReader`
 
 ---
 """

mail_intake/ingestion/reader.py

@@ -1,18 +1,17 @@
 """
+# Summary
+
 High-level mail ingestion orchestration for Mail Intake.
 
----
-
-## Summary
-
 This module provides the primary, provider-agnostic entry point for
 reading and processing mail data.
 
 It coordinates:
-- Mail adapter access
-- Message and thread iteration
-- Header and body parsing
-- Normalization and model construction
+
+- Mail adapter access.
+- Message and thread iteration.
+- Header and body parsing.
+- Normalization and model construction.
 
 No provider-specific logic or API semantics are permitted in this layer.
 """
@@ -36,12 +35,18 @@ class MailIntakeReader:
     Notes:
         **Responsibilities:**
 
-            - This class is the primary entry point for consumers of the Mail Intake library
-            - It orchestrates the full ingestion pipeline: Querying the adapter for message references, fetching raw provider messages, parsing and normalizing message data, constructing domain models
+            - This class is the primary entry point for consumers of the
+              Mail Intake library.
+            - It orchestrates the full ingestion pipeline:
+                - Querying the adapter for message references.
+                - Fetching raw provider messages.
+                - Parsing and normalizing message data.
+                - Constructing domain models.
 
         **Constraints:**
-        
-            - This class is intentionally: Provider-agnostic, stateless beyond iteration scope, read-only
+
+            - This class is intentionally: Provider-agnostic, stateless beyond
+              iteration scope, read-only.
     """
 
     def __init__(self, adapter: MailIntakeAdapter):
@@ -87,13 +92,14 @@ class MailIntakeReader:
                 An iterator of `MailIntakeThread` instances.
 
         Raises:
-            MailIntakeParsingError:
+            `MailIntakeParsingError`:
                 If a message cannot be parsed.
 
         Notes:
             **Guarantees:**
 
-                - Messages are grouped by `thread_id` and yielded as complete thread objects containing all associated messages
+                - Messages are grouped by `thread_id` and yielded as complete
+                  thread objects containing all associated messages.
         """
         threads: Dict[str, MailIntakeThread] = {}