ciris-agent 1.7.7__py3-none-any.whl

ciris_adapters/reddit/REDDIT_ADAPTER_ANALYSIS.md

@@ -0,0 +1,715 @@
+# Reddit Adapter Implementation Analysis
+
+## Executive Summary
+
+The CIRIS codebase contains a **complete, production-ready Reddit adapter** implementation as a modular service. The adapter provides full Reddit integration with tool, communication, and observation capabilities. The implementation uses **httpx for HTTP requests** instead of PRAW (Python Reddit API Wrapper), providing direct OAuth2 handling.
+
+**Status**: IMPLEMENTED (1,188 lines of production code)
+**Location**: `/home/emoore/CIRISAgent/ciris_adapters/reddit/`
+
+---
+
+## 1. Directory Structure
+
+```
+ciris_adapters/reddit/
+├── __init__.py              # Package exports
+├── README.md                # Complete documentation
+├── manifest.json            # Module declaration (JSON)
+├── protocol.py              # Service protocols
+├── schemas.py               # Pydantic type models
+├── service.py               # Tool + Communication services (1,188 lines)
+└── observer.py              # Passive observation implementation
+```
+
+**Size & Scope**:
+- Total: ~1,900 lines of production Python code
+- `service.py`: 1,188 lines (RedditAPIClient, RedditToolService, RedditCommunicationService)
+- `observer.py`: 162 lines (RedditObserver for passive monitoring)
+- `schemas.py`: 356 lines (15+ Pydantic models)
+
+---
+
+## 2. Reddit API Integration (NOT using PRAW)
+
+### Implementation Approach
+The adapter implements a **custom HTTP client** (`RedditAPIClient`) instead of using PRAW:
+
+**Advantages of this approach:**
+- Direct control over HTTP requests and rate limiting
+- Lighter dependencies (only requires httpx)
+- Type-safe request/response handling
+- Custom OAuth token management
+
+### Key Methods:
+
+```python
+class RedditAPIClient:
+    _TOKEN_URL = "https://www.reddit.com/api/v1/access_token"
+    _API_BASE_URL = "https://oauth.reddit.com"
+
+    # OAuth Management
+    async def refresh_token(force: bool = False) -> bool
+    async def update_credentials(credentials: RedditCredentials) -> None
+
+    # Public Methods
+    async def fetch_user_context(request: RedditUserContextRequest)
+    async def submit_post(request: RedditSubmitPostRequest)
+    async def submit_comment(request: RedditSubmitCommentRequest)
+    async def remove_content(request: RedditRemoveContentRequest)
+    async def get_submission_summary(submission_id, ...)
+    async def fetch_subreddit_new(subreddit, limit)
+    async def fetch_subreddit_comments(subreddit, limit)
+    async def fetch_submission_comments(submission_id, limit)
+    async def fetch_user_activity(username, limit)
+```
+
+---
+
+## 3. Bot Identification Implementation
+
+### User-Agent Configuration
+
+**✅ Properly Identifies Bot:**
+
+```python
+# Default User-Agent (Reddit API compliant)
+_USER_AGENT_FALLBACK = "CIRIS-RedditAdapter/1.0 (+https://ciris.ai)"
+
+# Configurable via environment
+CIRIS_REDDIT_USER_AGENT env variable (defaults to above)
+```
+
+### Configuration
+Defined in `manifest.json`:
+```json
+"reddit_user_agent": {
+  "type": "string",
+  "env": "CIRIS_REDDIT_USER_AGENT",
+  "default": "CIRIS-RedditAdapter/1.0 (+https://ciris.ai)",
+  "description": "User-Agent header that complies with Reddit API rules"
+}
+```
+
+### Transparency Mechanism
+**Documentation in README.md explicitly states:**
+- "Adheres to the CIRIS covenant"
+- "Honors Reddit best practices (user agent, rate handling)"
+- "Surfaces API failures with actionable error messages"
+
+### Status: COMPLETE ✅
+- Bot is clearly identified as CIRIS
+- URL points to legitimately discoverable information
+- Complies with Reddit's user-agent policy
+
+---
+
+## 4. Data Retention & Deletion Handling
+
+### Status: MINIMAL ⚠️
+
+**What EXISTS:**
+- OAuth tokens are expired/cleaned on token refresh
+- RedditObserver uses OrderedDict with `_CACHE_LIMIT = 500` to auto-evict old item IDs
+- No explicit persistent data storage beyond what's in graph memory
+
+**What's MISSING:**
+1. **No explicit data deletion API** - Comments/posts created by bot cannot be auto-deleted
+2. **No cache purging mechanism** - Observer cache persists indefinitely (though bounded)
+3. **No retention policy documentation** - No specified data lifetime guidelines
+4. **No audit-trail deletion hooks** - Audit service may retain Reddit content permanently
+
+### Implementation Details (Cache Management):
+```python
+# From observer.py (line 106-112)
+def _mark_seen(self, cache: "OrderedDict[str, None]", key: str) -> bool:
+    if key in cache:
+        return True
+    cache[key] = None
+    while len(cache) > _CACHE_LIMIT:  # 500 item limit
+        cache.popitem(last=False)
+    return False
+```
+
+### Recommendation:
+- Add `reddit_delete_content` tool method
+- Document data retention policy in manifest
+- Consider integrating with graph memory deletion service
+
+---
+
+## 5. Rate Limiting Implementation
+
+### Status: IMPLEMENTED ✅
+
+**Primary Rate Limiting (HTTP 429 handling):**
+
+```python
+# From service.py (lines 179-182)
+if response.status_code == 429:
+    retry_after = float(response.headers.get("Retry-After", "1"))
+    await asyncio.sleep(max(retry_after, 0))
+    response = await self._http_client.request(...)
+```
+
+**Features:**
+- Respects Reddit's `Retry-After` header
+- Automatic retry after backoff
+- Configurable timeout (httpx.Timeout settings: 10s connect, 20s read/write, 10s pool)
+
+**Metrics Tracking:**
+```python
+self._request_count = 0     # Track all requests
+self._error_count = 0        # Track errors
+metrics["requests"] = float(self._request_count)
+metrics["errors"] = float(self._error_count)
+```
+
+### Additional Rate Limit Handling:
+- **Token refresh lock**: Uses `asyncio.Lock()` to prevent concurrent token requests
+- **Connection pooling**: httpx AsyncClient with configured pool timeout
+- **Token buffer**: 60-second buffer before expiration to prevent mid-request expiration
+
+### Status: COMPLETE ✅
+Implements best practices for respecting Reddit API rate limits.
+
+---
+
+## 6. OAuth2 Authentication
+
+### Status: FULLY IMPLEMENTED ✅
+
+### Authentication Flow
+
+**Type**: Reddit OAuth2 Password Grant (User Account)
+
+**Endpoints:**
+- Token endpoint: `https://www.reddit.com/api/v1/access_token`
+- API base: `https://oauth.reddit.com`
+
+### Credential Management
+
+**RedditCredentials Schema:**
+```python
+class RedditCredentials(BaseModel):
+    client_id: str              # App client ID
+    client_secret: str          # App secret
+    username: str               # Bot account username
+    password: str               # Bot account password
+    user_agent: str             # User-Agent header
+    subreddit: str = "ciris"    # Default subreddit
+```
+
+**Token Refresh Mechanism:**
+```python
+async def refresh_token(force: bool = False) -> bool:
+    """Ensure access token available, optionally forcing refresh"""
+    async with self._token_lock:  # Thread-safe with asyncio.Lock()
+        if not force and self._token and not self._token.is_expired():
+            return True
+
+        auth = (client_id, client_secret)
+        data = {
+            "grant_type": "password",
+            "username": username,
+            "password": password,
+        }
+        # POST to token endpoint with Basic auth
+        response = await client.post(TOKEN_URL, data=data, auth=auth)
+```
+
+**Token Storage:**
+```python
+class RedditToken(BaseModel):
+    access_token: str
+    expires_at: datetime
+
+    def is_expired(self, now=None, buffer_seconds: int = 60) -> bool:
+        """Checks if expired or within 60-second refresh window"""
+```
+
+### Environment Variables:
+```
+CIRIS_REDDIT_CLIENT_ID       # Required
+CIRIS_REDDIT_CLIENT_SECRET   # Required (HIGH sensitivity)
+CIRIS_REDDIT_USERNAME        # Required
+CIRIS_REDDIT_PASSWORD        # Required (HIGH sensitivity)
+CIRIS_REDDIT_USER_AGENT      # Optional (defaults to fallback)
+CIRIS_REDDIT_SUBREDDIT       # Optional (defaults to 'ciris')
+```
+
+### Security Notes:
+- Credentials stored in RedditCredentials Pydantic model
+- No credentials logged (defensive logging in place)
+- Token refresh is synchronized with asyncio.Lock()
+- 401 responses trigger automatic token refresh
+
+### Status: PRODUCTION-READY ✅
+OAuth2 implementation is complete, type-safe, and follows Reddit API best practices.
+
+---
+
+## 7. Content Moderation Logic
+
+### Status: IMPLEMENTED ✅
+
+**Available Moderation Tools:**
+
+1. **`reddit_remove_content`** - Remove submissions or comments
+   ```python
+   RedditRemoveContentRequest:
+       thing_fullname: str      # t3_xxx or t1_xxx
+       spam: bool = False       # Mark as spam vs just remove
+   ```
+
+2. **`reddit_submit_comment`** - Post comments with optional thread lock
+   ```python
+   RedditSubmitCommentRequest:
+       parent_fullname: str     # Parent thing ID
+       text: str                # Comment body (Markdown)
+       lock_thread: bool = False # Lock submission after replying
+   ```
+
+3. **`reddit_submit_post`** - Create new submissions
+   ```python
+   RedditSubmitPostRequest:
+       title: str
+       body: str                # Markdown
+       flair_id: Optional[str]  # Pre-configured flair
+       flair_text: Optional[str]
+       nsfw: bool = False
+       spoiler: bool = False
+       send_replies: bool = True
+   ```
+
+4. **`reddit_get_user_context`** - Get user info + history
+   ```python
+   RedditUserContextRequest:
+       username: str
+       include_history: bool = True
+       history_limit: int = 5-25
+   ```
+
+### Anti-Spoofing & Safety
+
+**From observer.py (lines 151-161):**
+```python
+async def _enhance_message(self, msg: RedditMessage) -> RedditMessage:
+    """Apply Reddit-specific content hardening before processing."""
+
+    # Uses base observer's spoofing detection
+    cleaned = detect_and_replace_spoofed_markers(msg.content)
+    if cleaned != msg.content:
+        msg.content = cleaned
+
+    # Surfaces permalink for context reconstruction
+    if msg.permalink:
+        setattr(msg, "permalink_url", msg.permalink)
+
+    return msg
+```
+
+### CIRIS Covenant Enforcement
+
+**From README.md:**
+> "Adheres to the CIRIS covenant: no medical, clinical, or political campaigning actions."
+
+And from **manifest.json**:
+```json
+"prohibited": ["medical", "political_campaigning"],
+```
+
+This enforcement happens at the **WiseBus level** (checked in wise_bus.py) - not Reddit-specific.
+
+### Status: COMPLETE ✅
+Moderation tools are well-designed with type safety and integrated anti-spoofing.
+
+---
+
+## 8. Transparency & Disclosure Mechanisms
+
+### Status: IMPLEMENTED (Partial) ✅⚠️
+
+**What EXISTS:**
+
+1. **User-Agent Transparency**
+   - Clear identification: "CIRIS-RedditAdapter/1.0 (+https://ciris.ai)"
+   - Reddit policy compliant (includes contact URL)
+
+2. **README Documentation**
+   - Comprehensive module documentation at `/ciris_adapters/reddit/README.md`
+   - Explains capabilities, configuration, and channel references
+   - Safety section: "Adheres to the CIRIS covenant"
+
+3. **Manifest Declaration**
+   - `manifest.json` declares:
+     - All capabilities (7 tool capabilities + 2 communication)
+     - Safety domain: "community_outreach"
+     - Prohibited capabilities: "medical", "political_campaigning"
+     - Required configuration
+
+4. **Service Metadata**
+   - Capabilities endpoint reports all actions
+   - Tool descriptions available via service introspection
+
+**What's MISSING:**
+
+1. **No explicit bot disclosure tool** - Cannot programmatically announce CIRIS identity
+2. **No transparency report hooks** - No mechanism to log all actions for community audit
+3. **No `/about` profile endpoint** - Reddit profile could link to documentation
+4. **No consent/acknowledgment mechanism** - No way to confirm user awareness of bot presence
+
+### Example of What's Possible But Not Implemented:
+```python
+# Not present in code, but could be added:
+async def _tool_disclose_identity(self, ...) -> ToolExecutionResult:
+    """Tool to announce CIRIS identity and purpose"""
+    message = """
+I am CIRIS-RedditAdapter/1.0 (https://ciris.ai)
+- I am an AI moderation bot operated by CIRIS
+- My decisions are subject to human review
+- Full audit trail: https://agents.ciris.ai/audit
+- Questions? Contact: [contact info]
+"""
+```
+
+### Recommendation:
+- Consider adding `reddit_disclose_identity` tool for transparency
+- Document bot profile in subreddit sidebar
+- Add logging hook for all Reddit actions to community-visible audit trail
+
+---
+
+## 9. Reddit-Specific Configuration
+
+### Status: COMPLETE ✅
+
+**Configuration Management:**
+
+1. **manifest.json Declaration:**
+```json
+{
+  "configuration": {
+    "reddit_client_id": {
+      "type": "string",
+      "env": "CIRIS_REDDIT_CLIENT_ID",
+      "description": "Reddit OAuth client identifier"
+    },
+    "reddit_client_secret": {
+      "type": "string",
+      "env": "CIRIS_REDDIT_CLIENT_SECRET",
+      "description": "Reddit OAuth client secret"
+    },
+    "reddit_username": {
+      "type": "string",
+      "env": "CIRIS_REDDIT_USERNAME",
+      "description": "Bot account username"
+    },
+    "reddit_password": {
+      "type": "string",
+      "env": "CIRIS_REDDIT_PASSWORD",
+      "sensitivity": "HIGH",
+      "description": "Bot account password"
+    },
+    "reddit_user_agent": {
+      "type": "string",
+      "env": "CIRIS_REDDIT_USER_AGENT",
+      "default": "CIRIS-RedditAdapter/1.0 (+https://ciris.ai)",
+      "description": "User-Agent header that complies with Reddit API rules"
+    },
+    "reddit_subreddit": {
+      "type": "string",
+      "env": "CIRIS_REDDIT_SUBREDDIT",
+      "default": "ciris",
+      "description": "Home subreddit for passive observation"
+    }
+  }
+}
+```
+
+2. **Environment Variable Loading:**
+```python
+@classmethod
+def from_env(cls) -> "RedditCredentials | None":
+    """Create credentials from environment variables if available."""
+    env_mapping = {
+        "reddit_client_id": os.getenv("CIRIS_REDDIT_CLIENT_ID"),
+        "reddit_client_secret": os.getenv("CIRIS_REDDIT_CLIENT_SECRET"),
+        "reddit_username": os.getenv("CIRIS_REDDIT_USERNAME"),
+        "reddit_password": os.getenv("CIRIS_REDDIT_PASSWORD"),
+        "reddit_user_agent": os.getenv("CIRIS_REDDIT_USER_AGENT", "CIRIS-RedditAdapter/1.0 (+https://ciris.ai)"),
+        "reddit_subreddit": os.getenv("CIRIS_REDDIT_SUBREDDIT", "ciris"),
+    }
+    if all(value for value in env_mapping.values()):
+        return cls.model_validate(env_mapping)
+    return None
+```
+
+3. **Channel Reference Format:**
+Reddit uses proprietary channel references matching the canonical format:
+```
+reddit:r/<subreddit>                                 # Subreddit
+reddit:r/<subreddit>:post/<submission_id>          # Submission
+reddit:r/<subreddit>:post/<submission_id>:comment/<comment_id>  # Comment
+reddit:u/<username>                                 # User timeline
+```
+
+4. **WAKEUP Submission Discovery:**
+During startup, RedditCommunicationService searches for a WAKEUP submission to use as default channel:
+```python
+async def _resolve_home_channel(self) -> None:
+    """Resolve the WAKEUP submission used for default Reddit messaging."""
+    entries = await self._client.fetch_subreddit_new(subreddit, limit=25)
+    for entry in entries:
+        if "wakeup" in entry.title.lower() or "wakeup" in entry.body.lower():
+            self._home_channel = _build_channel_reference(subreddit, submission_id=entry.item_id)
+```
+
+### Usage Examples:
+
+**Command Line:**
+```bash
+python main.py --adapter reddit
+python main.py --adapter api --adapter reddit  # Multiple adapters
+```
+
+**Environment Variables (.env):**
+```bash
+CIRIS_REDDIT_CLIENT_ID=xxxxx
+CIRIS_REDDIT_CLIENT_SECRET=yyyyy
+CIRIS_REDDIT_USERNAME=ciris_bot_account
+CIRIS_REDDIT_PASSWORD=bot_password
+CIRIS_REDDIT_SUBREDDIT=mycommunity
+```
+
+---
+
+## 10. Service Architecture
+
+### Module Declaration (manifest.json)
+
+```json
+{
+  "services": [
+    {
+      "type": "TOOL",
+      "priority": "NORMAL",
+      "class": "reddit.service.RedditToolService",
+      "capabilities": [
+        "tool:reddit",
+        "tool:reddit:get_user_context",
+        "tool:reddit:submit_post",
+        "tool:reddit:submit_comment",
+        "tool:reddit:remove_content",
+        "tool:reddit:get_submission",
+        "tool:reddit:observe"
+      ]
+    },
+    {
+      "type": "COMMUNICATION",
+      "priority": "LOW",
+      "class": "reddit.service.RedditCommunicationService",
+      "capabilities": [
+        "communication:send_message",
+        "communication:fetch_messages"
+      ]
+    }
+  ]
+}
+```
+
+### Service Classes
+
+**RedditToolService** (extends RedditServiceBase, RedditToolProtocol)
+- 7 tool implementations
+- Validation and error handling
+- Metrics collection
+- 6 request model validators
+
+**RedditCommunicationService** (extends RedditServiceBase, RedditCommunicationProtocol)
+- `send_message()` - Post comments
+- `fetch_messages()` - Retrieve messages
+- `get_home_channel_id()` - Default channel resolution
+- Supports all channel types (subreddit, submission, comment, user)
+
+**RedditObserver** (extends BaseObserver[RedditMessage])
+- Passive polling every 15 seconds (configurable 5s minimum)
+- Detects new submissions and comments
+- Integrates with adaptive filtering
+- Anti-spoofing content cleaning
+
+---
+
+## 11. What's MISSING
+
+### Critical Gaps
+
+1. **No Unit/Integration Tests**
+   - No test files in `/tests/` for Reddit adapter
+   - No fixture or mock Reddit API
+
+2. **No PRAW Library** ⚠️
+   - Intentionally not using PRAW
+   - Custom implementation provides more control
+   - Acceptable for production use
+
+3. **Limited Data Deletion Support**
+   - Can remove content via API
+   - No auto-deletion tool
+   - No deletion confirmation workflow
+
+4. **No Explicit Content Filtering**
+   - Relies on parent system's adaptive filter
+   - No Reddit-specific filtering rules
+
+5. **No Webhook Support**
+   - Polling-only observer (not webhook-based)
+   - Reddit doesn't support webhooks anyway
+
+### Enhancement Opportunities
+
+1. **Transparency Disclosure Tool**
+   ```python
+   reddit_disclose_identity() -> ToolExecutionResult
+   # Post message announcing CIRIS presence
+   ```
+
+2. **Activity Auditing Tool**
+   ```python
+   reddit_get_activity_log() -> List[AuditEvent]
+   # Return all actions taken by this bot
+   ```
+
+3. **Subreddit Rule Synchronization**
+   ```python
+   reddit_sync_rules(rule_text: str) -> bool
+   # Sync moderation rules to subreddit about section
+   ```
+
+4. **User Report Handling**
+   ```python
+   reddit_get_modqueue() -> List[ModQueueItem]
+   # Fetch reported content for review
+   ```
+
+5. **Test Suite**
+   ```
+   tests/modular_services/test_reddit_adapter.py  (400+ lines)
+   - Mocked httpx client
+   - OAuth flow testing
+   - Channel reference parsing
+   - Tool execution validation
+   ```
+
+---
+
+## 12. Comparison with Discord Adapter
+
+| Feature | Discord | Reddit |
+|---------|---------|--------|
+| **Tool Service** | ✅ DiscordToolService | ✅ RedditToolService |
+| **Communication Service** | ✅ DiscordAdapter | ✅ RedditCommunicationService |
+| **Observer** | ✅ DiscordObserver | ✅ RedditObserver |
+| **Moderation Tools** | 13 tools (timeout, ban, kick, etc.) | 6 tools (post, comment, remove, etc.) |
+| **User Management** | ✅ Full role/permission support | ⚠️ Limited (no mod actions) |
+| **Rate Limiting** | Advanced (exponential backoff) | ✅ 429 handling |
+| **Test Coverage** | 100+ test files | ⚠️ 0 test files |
+| **Production Status** | ✅ Powering agents.ciris.ai | ✅ Ready but untested |
+| **Documentation** | Extensive | Good (README + docstrings) |
+
+---
+
+## 13. Type Safety Analysis
+
+### Pydantic Models (10 Request/Response types)
+
+All type-safe, no `Dict[str, Any]` in schemas:
+
+```python
+RedditCredentials          ✅ All fields required/typed
+RedditToken               ✅ datetime + expiration logic
+RedditChannelReference    ✅ Enum + nested validation
+RedditUserContextRequest  ✅ Typed fields with defaults
+RedditSubmitPostRequest   ✅ Full request schema
+RedditSubmitCommentRequest ✅ Typed parameters
+RedditRemoveContentRequest ✅ Minimal but typed
+RedditGetSubmissionRequest ✅ Validation via model_validator
+RedditUserContext         ✅ Complex response type
+RedditSubmissionSummary   ✅ Full metadata response
+```
+
+### Service Implementation Quality
+
+**✅ Type-Safe:**
+- All public methods have type annotations
+- Return types explicitly declared
+- Tool parameters validated via Pydantic
+
+**⚠️ JSON Handling:**
+- Some `JSONDict` and `JSONValue` usage (necessary for API responses)
+- Limited to parsing Reddit's JSON responses
+- Not used in public-facing code
+
+---
+
+## 14. Summary Table
+
+| Aspect | Status | Notes |
+|--------|--------|-------|
+| **Directory Structure** | ✅ Complete | Modular service at `/ciris_adapters/reddit/` |
+| **Reddit API Integration** | ✅ Complete | Custom httpx-based client, no PRAW dependency |
+| **Bot Identification** | ✅ Complete | User-Agent clearly identifies as CIRIS |
+| **Data Retention** | ⚠️ Partial | Token expiration + cache limits, but no deletion API |
+| **Rate Limiting** | ✅ Complete | 429 handling with Retry-After respect |
+| **OAuth2 Authentication** | ✅ Complete | Password grant flow, token refresh with locking |
+| **Content Moderation** | ✅ Complete | Remove, post, comment, lock thread tools |
+| **Transparency/Disclosure** | ⚠️ Partial | Bot identified in user-agent, lacks disclosure tool |
+| **Reddit Configuration** | ✅ Complete | 6 environment variables, flexible setup |
+| **Service Architecture** | ✅ Complete | 2 services (tool + communication) + observer |
+| **Test Coverage** | ❌ Missing | No dedicated test files |
+| **Documentation** | ✅ Good | README + docstrings + manifest |
+
+---
+
+## 15. Production Readiness Assessment
+
+### ✅ Ready for Production:
+- Type-safe implementation (Pydantic models throughout)
+- Proper OAuth2 handling with token refresh
+- Rate limit compliance
+- Error handling and logging
+- Channel abstraction (works with multiple subreddits)
+- Async/await implementation (non-blocking I/O)
+
+### ⚠️ Recommended Before Production Deployment:
+1. **Add comprehensive test suite** (currently 0 tests)
+2. **Add data deletion API** for content removal workflows
+3. **Add transparency disclosure tool** for community trust
+4. **Document data retention policy** in README
+5. **Add activity audit logging** integration
+
+### 🚀 Deployment Status:
+**PRODUCTION-READY with caveats**
+- Functional and type-safe
+- Currently untested (no test suite)
+- Recommend adding tests before deploying to public subreddit
+- All CIRIS covenant protections apply (medical/political filtering at WiseBus level)
+
+---
+
+## 16. Code Quality Metrics
+
+```
+Total Lines:        ~1,900
+Service Code:       1,188 lines (service.py)
+Observer Code:      162 lines (observer.py)
+Schema Code:        356 lines (schemas.py + protocol.py)
+
+Cyclomatic Complexity: Low to Medium
+  - Mostly straightforward HTTP request/response handling
+  - Some complexity in channel reference parsing
+
+Test Coverage:      0% (no tests exist)
+Type Annotations:   ~95% coverage (well-typed codebase)
+Documentation:      Good (README, docstrings, manifest)
+```