Design Python binding interface

[meganerd]

Summary

• Evaluates three approaches: CLI subprocess wrapper, cgo shared library, gRPC server
• Recommends CLI subprocess wrapper (pysiftrank package) for simplicity and maintainability
• Includes full Python API design: SiftRank class, data classes, implementation sketch
• Documents comparison matrix across effort, distribution, maintenance, and performance

Key design decisions:

• Subprocess wrapper avoids cgo complexity and platform-specific builds
• ~50ms process overhead is negligible vs seconds-to-minutes LLM API calls
• Full feature parity from day one (batch mode, comparison, all CLI flags)
• Pure Python package distributable via PyPI

Test plan

• Design document covers all three approaches with pros/cons
• Recommended approach includes concrete API design and implementation sketch
• Python API covers all siftrank features (rank, batch, compare, cost tracking)

Refs: siftrank-29

🤖 Generated with Claude Code