seams 0.1.2

High-throughput sentence extractor for Project Gutenberg texts with dialog-aware detection
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67

# Python API Design Strategy and Implementation Approach

* **Task ID:** python-api-design-strategy_54.stevejs.md
* **Reviewer:** stevejs
* **Area:** docs
* **Motivation (WHY):**
  - PRD Section 11 specifies Python module requirements but API design is unclear
  - Current Rust API uses borrowed strings which don't map cleanly to Python
  - Need to determine if CLI-only approach is better than Python bindings
  - Must design user-facing Python API without exposing Rust implementation details
  - Critical decision affects project architecture and publication strategy

* **Acceptance Criteria:**
  1. Clear decision on Python API approach (CLI wrapper vs native bindings vs hybrid)
  2. If native bindings: Python API design that hides Rust implementation details
  3. Performance comparison of different Python integration approaches
  4. Updated PRD Section 11 reflecting chosen approach
  5. Clear rationale for design decisions documented

* **Design Options to Evaluate:**

**Option A: CLI-Only Approach**
- Python calls seams binary via subprocess
- Pros: Simple, no FFI complexity, leverages existing CLI
- Cons: Subprocess overhead, no streaming API

**Option B: Native PyO3 Bindings**
- Direct Rust-Python bindings with owned string API
- Pros: Best performance, streaming possible
- Cons: Complex FFI, API design challenges

**Option C: Hybrid Approach**
- CLI for corpus processing, bindings for single-text processing
- Pros: Best of both worlds
- Cons: Two different APIs to maintain

* **Deliverables:**
  - Research document comparing approaches with performance implications
  - Python API design mockup for chosen approach
  - Updated PRD Section 11 with concrete API specification
  - Decision rationale document
  - Remove or update obsolete API references in current PRD

* **Research Areas:**
  1. Performance overhead of subprocess vs FFI for typical workloads
  2. Python ecosystem preferences for text processing tools
  3. Memory management implications of different approaches
  4. Maintenance burden of each approach

* **Success Metrics:**
  - Python API is simple and Pythonic
  - Performance is acceptable for target use cases
  - Implementation complexity is manageable
  - API hides Rust implementation details completely

* **References:**
  - PRD Section 11: Python Module Requirements
  - Current Rust API using DetectedSentenceBorrowed
  - Python text processing tool ecosystem (spaCy, NLTK patterns)

## Pre-commit checklist:
- [ ] All deliverables implemented
- [ ] Tests passing (`cargo test`)
- [ ] Claims validated (design approach is well-reasoned)
- [ ] Documentation updated (PRD Section 11 reflects chosen approach)
- [ ] **ZERO WARNINGS**: `./scripts/validate_warning_free.sh` passes completely
- [ ] **Design validation**: Python API design reviewed and approved