nothx 0.1.0__tar.gz

nothx-0.1.0/.context/attachments/PR instructions.md

@@ -0,0 +1,18 @@
+The user likes the state of the code.
+
+There are 11 uncommitted changes.
+The current branch is sainihas/code-review.
+The target branch is origin/main.
+
+There is no upstream branch yet.
+The user requested a PR.
+
+Follow these **exact steps** to create a PR:
+
+- Run `git diff` to review uncommitted changes
+- Commit them. Follow any instructions the user gave you about writing commit messages.
+- Push to origin.
+- Use the `mcp__conductor__GetWorkspaceDiff` tool to review the PR diff
+- Use `gh pr create --base main` to create a PR onto the target branch. Keep the title under 80 characters and the description under five sentences (unless the user has given you other instructions).
+
+If any of these steps fail, ask the user for help.

nothx-0.1.0/.context/plans/nothx-upgrade-checklist.md

@@ -0,0 +1,167 @@
+# nothx Upgrade Checklist
+
+## Priority 1: Critical (Ship Blockers)
+
+### Error Handling
+- [ ] Replace all `except Exception` with specific exception types
+- [ ] Add retry logic with exponential backoff for AI provider calls (ai.py:131-151)
+- [ ] Add retry logic for IMAP connections (imap.py)
+- [ ] Return structured error types instead of empty `{}` on AI failures
+- [ ] Add error context to all `logger.error()` calls (include domain, operation, stack trace)
+- [ ] Validate AI response confidence is in [0.0, 1.0] range (ai.py:209)
+- [ ] Log when falling back from AI to heuristics (and why)
+
+### Testing
+- [ ] Create `tests/test_cli.py` - full coverage for cli.py (61KB untested)
+- [ ] Add integration test: full pipeline from IMAP fetch → classification → unsubscribe
+- [ ] Add test for concurrent database access
+- [ ] Add test for IMAP connection failures and recovery
+- [ ] Add test for AI provider timeout handling
+- [ ] Add test for malformed AI responses
+
+### Security
+- [ ] Move API keys to system keyring (use `keyring` package) or environment variables
+- [ ] Add option to encrypt config.json at rest
+- [ ] Sanitize domain/subject data before embedding in AI prompts (prompt injection risk)
+- [ ] Add rate limiting for HTTP unsubscribe requests
+- [ ] Add rate limiting for AI API calls
+
+---
+
+## Priority 2: High (Production Readiness)
+
+### Observability
+- [ ] Add structured logging (JSON format option for log aggregation)
+- [ ] Track metrics: classification source distribution (rules/patterns/AI/heuristics/review)
+- [ ] Track metrics: AI fallback rate and reasons
+- [ ] Track metrics: classification latency per layer
+- [ ] Track metrics: unsubscribe success/failure rates by method
+- [ ] Add correlation IDs to trace a sender through the pipeline
+- [ ] Add `--verbose` and `--debug` flags to CLI
+
+### Configuration
+- [ ] Extract all magic numbers to `ThresholdConfig`:
+  - [ ] Base score (currently hardcoded 50)
+  - [ ] Open rate adjustments (+25, +15, +5, -20, -30)
+  - [ ] Volume adjustments (+10, +5)
+  - [ ] Subject pattern weights (+5, -10, +15)
+  - [ ] Domain pattern weights (+10, -10)
+  - [ ] Confidence thresholds for each layer
+- [ ] Add config validation on load (reject invalid values)
+- [ ] Add `nothx config validate` command
+- [ ] Document all config options with defaults and valid ranges
+
+### Bug Fixes
+- [ ] Fix open rate scoring gap (25-50% has no adjustment) in heuristics.py:76-85
+- [ ] Fix UTF-8 truncation in response snippets (unsubscriber.py:68) - use `textwrap` or char-aware slicing
+- [ ] Fix cache thrashing in learner (batch updates instead of invalidate-per-action)
+- [ ] Add validation for rule actions in rules.py (don't silently skip invalid rules)
+
+---
+
+## Priority 3: Medium (Quality of Life)
+
+### Performance
+- [ ] Pre-compile all regex patterns at module load time
+- [ ] Add batch database operations for bulk classifications
+- [ ] Implement incremental cache updates in learner (not full reload)
+- [ ] Add connection pooling for IMAP
+- [ ] Profile and add benchmarks for batch classification (100, 1000, 10000 senders)
+
+### Features Missing for Real Use
+- [ ] Add `--dry-run` flag with diff output ("would unsubscribe from X, Y, Z")
+- [ ] Add undo capability (store unsubscribe actions, provide reversal where possible)
+- [ ] Add audit log command (`nothx history` or `nothx log`)
+- [ ] Add scheduling support (cron-friendly mode, or built-in scheduler)
+- [ ] Add multi-account aggregation view
+- [ ] Add export/import for rules and preferences
+
+### Pattern Matching Improvements
+- [ ] Implement pattern specificity ranking (`*.bank.com` beats `*bank*`)
+- [ ] Add negative patterns support (`keep *.bank.com except fraudulent-bank.com`)
+- [ ] Add pattern conflict detection (warn when domain matches multiple patterns)
+- [ ] Make default patterns configurable (not hardcoded in patterns.py)
+
+### AI System Improvements
+- [ ] Add provider rate limiting (respect API limits)
+- [ ] Track and log token usage for cost monitoring
+- [ ] Validate configured model exists for selected provider
+- [ ] Add timeout configuration for AI calls
+- [ ] Cache AI classifications for identical senders (short TTL)
+
+---
+
+## Priority 4: Low (Nice to Have)
+
+### Learning System
+- [ ] Implement domain generalization (recognize "financial institutions" category, not just individual banks)
+- [ ] Use sliding window for preference updates (recent actions matter more)
+- [ ] Merge AI insight path with incremental learner (resolve conflicts)
+- [ ] Add temporal decay to sender scores (inactive senders score differently)
+- [ ] Add `nothx learn reset` command to start fresh
+
+### Code Quality
+- [ ] Add dependency injection for `RulesMatcher` (remove direct DB coupling)
+- [ ] Split cli.py into submodules by command group
+- [ ] Add `py.typed` marker for PEP 561 compliance
+- [ ] Add pre-commit hooks (black, ruff, mypy)
+- [ ] Add GitHub Actions CI/CD workflow
+- [ ] Add coverage reporting with minimum threshold (80%+)
+
+### Documentation
+- [ ] Add architecture decision records (ADRs) for key decisions
+- [ ] Document the scoring algorithm with examples
+- [ ] Add troubleshooting guide for common IMAP issues
+- [ ] Add API documentation for programmatic use
+- [ ] Add changelog
+
+### Developer Experience
+- [ ] Add `nothx debug classify <domain>` - show full classification trace
+- [ ] Add `nothx debug score <domain>` - show heuristic scoring breakdown
+- [ ] Add `nothx stats` - show classification distribution, success rates
+- [ ] Add `--json` output flag for all commands (machine-readable)
+
+---
+
+## File-by-File Fixes
+
+| File | Issues |
+|------|--------|
+| `cli.py` | Needs tests, split into submodules, add --verbose/--debug |
+| `ai.py:131-151` | Add retry logic, structured errors |
+| `ai.py:209` | Validate confidence range |
+| `ai.py:214-215` | Don't silently swallow JSON parse errors |
+| `heuristics.py:76-85` | Fix 25-50% gap |
+| `heuristics.py:113-126` | Extract magic numbers to config |
+| `heuristics.py` | Pre-compile regex patterns |
+| `learner.py:51-53` | Batch cache updates |
+| `rules.py:35-40` | Don't silently skip invalid rules |
+| `unsubscriber.py:68` | UTF-8 safe truncation |
+| `imap.py:121` | Specific exceptions, not bare except |
+| `config.py` | Add validation, secrets management |
+| `patterns.py:10-82` | Make defaults configurable |
+
+---
+
+## Quick Wins (Do These First)
+
+1. [ ] Pre-compile regex patterns (30 min, immediate perf win)
+2. [ ] Fix open rate 25-50% gap (10 min, bug fix)
+3. [ ] Add `--dry-run` to unsubscribe command (1 hr, safety feature)
+4. [ ] Extract magic numbers to constants with comments (1 hr, readability)
+5. [ ] Add retry decorator to AI calls (30 min, reliability)
+6. [ ] Log classification source in output (30 min, debuggability)
+7. [ ] Add basic CLI tests for main commands (2 hr, coverage)
+
+---
+
+## Definition of "Leveled Up"
+
+When complete, this codebase should:
+- Never fail silently - all errors logged with context
+- Be observable - know what's happening without reading code
+- Be configurable - tune behavior without editing source
+- Be testable - 80%+ coverage including CLI
+- Be debuggable - trace any classification decision
+- Be production-safe - rate limits, retries, timeouts
+- Be secure - no plaintext secrets, sanitized inputs

nothx-0.1.0/.git

@@ -0,0 +1 @@
+gitdir: /Users/sai/conductor/repos/nothx/.git/worktrees/milan

nothx-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,82 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests with coverage
+        run: pytest --cov=nothx --cov-report=xml --cov-fail-under=25
+
+      - name: Upload coverage reports
+        uses: codecov/codecov-action@v4
+        if: matrix.python-version == '3.12'
+        with:
+          files: ./coverage.xml
+          fail_ci_if_error: false
+
+  lint:
+    name: Lint & Format
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Check formatting with ruff
+        run: ruff format --check .
+
+      - name: Lint with ruff
+        run: ruff check .
+
+  typecheck:
+    name: Type Check
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run mypy
+        run: mypy nothx

nothx-0.1.0/.gitignore

@@ -0,0 +1,55 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# nothx local data
+.nothx/
+
+# macOS
+.DS_Store
+
+# Logs
+*.log
+
+# Secrets (never commit)
+*.env
+.env.*
+config.json

nothx-0.1.0/CLAUDE.md

@@ -0,0 +1,106 @@
+# CLAUDE.md
+
+Guidelines for AI assistants working with this codebase.
+
+## Quick Start
+
+```bash
+pip install -e ".[dev]"   # Install with dev dependencies
+pytest                     # Run tests
+python -m nothx           # Run CLI
+```
+
+## Architecture
+
+**5-layer classification pipeline** — each layer can decide or defer:
+
+1. **User Rules** (`classifier/rules.py`) — Custom patterns, highest priority
+2. **Preset Patterns** (`classifier/patterns.py`) — Known marketing/safe domains
+3. **AI Classification** (`classifier/ai.py`) — LLM analyzes email headers
+4. **Heuristics** (`classifier/heuristics.py`) — Rule-based scoring (0-100)
+5. **Review Queue** — Uncertain cases for manual review
+
+```
+IMAP Inbox → Scanner → Classifier Engine → Unsubscriber or Review Queue
+```
+
+## Project Structure
+
+```
+nothx/
+├── cli.py              # Click commands, entry point
+├── config.py           # Dataclasses for configuration
+├── models.py           # Core enums (Action, EmailType, etc.)
+├── db.py               # SQLite layer
+├── imap.py             # Email fetching
+├── scanner.py          # Inbox scanning
+├── unsubscriber.py     # Unsubscribe execution (RFC 8058, GET, mailto)
+├── theme.py            # Rich console theme
+└── classifier/
+    ├── engine.py       # Orchestrates the 5 layers
+    ├── ai.py           # AI classification
+    ├── providers/      # Anthropic, OpenAI, Gemini, Ollama
+    ├── heuristics.py   # Scoring logic
+    ├── learner.py      # User preference learning
+    └── patterns.py     # Pattern matching
+```
+
+## Common Tasks
+
+### Adding a CLI command
+
+```python
+@main.command()
+@click.option('--flag', help='Description')
+def new_command(flag: bool):
+    """Command description."""
+    # Implementation
+```
+
+### Adding an AI provider
+
+1. Create `classifier/providers/your_provider.py`
+2. Extend `BaseAIProvider`
+3. Register in `classifier/providers/factory.py`
+
+### Adding a classification layer
+
+1. Create module in `classifier/`
+2. Implement `classify(stats: SenderStats) -> Optional[Classification]`
+3. Return `None` to defer to next layer
+4. Register in `classifier/engine.py`
+
+## Code Style
+
+- **Type hints**: All functions must have complete annotations
+- **Dataclasses**: Use for data structures
+- **Imports**: stdlib → third-party → local
+- **Naming**: `snake_case` functions, `PascalCase` classes, `UPPER_CASE` constants
+
+## Important Rules
+
+### Do:
+- Mock external services (IMAP, HTTP, AI APIs) in tests
+- Use temporary databases for test isolation
+- Gracefully degrade (AI → heuristics → review)
+- Use parameterized queries for SQLite
+
+### Don't:
+- Read email bodies — only headers (From, Subject, Date, List-Unsubscribe)
+- Log sensitive data (passwords, API keys)
+- Auto-unsubscribe protected domains (banks, .gov, healthcare)
+- Crash on external failures
+
+## Testing
+
+```bash
+pytest                              # All tests
+pytest --cov=nothx                  # With coverage
+pytest tests/test_classifier.py -v  # Specific file
+```
+
+## Runtime Paths
+
+- Config: `~/.nothx/config.json`
+- Database: `~/.nothx/nothx.db`
+- Logs: `~/.nothx/logs/`

nothx-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nothx contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.