# PROP: Open-Source Building Blocks for iEvo Core Components

## Source
- Multiple sources (see per-component sections below)
- **Date**: Research conducted 2026-03-04

## Summary
For each core iEvo component, this proposal identifies the best open-source building block to use instead of building from scratch. Each recommendation is based on stars, maintenance, license, and fit for a local-first Python CLI tool.

## Component Decisions

### 1. PTY Bridge / Terminal Multiplexing

| Option | Language | Stars/Downloads | License | Verdict |
|--------|----------|----------------|---------|---------|
| pexpect | Python | 24M+ downloads | ISC | **USE for Phase 1** |
| ptyprocess | Python | Part of pexpect | ISC | Underlying lib |
| portable-pty | Rust | 2.5M downloads | MIT | **USE for Rust Phase** |
| Python `pty` stdlib | Python | Built-in | PSF | Too basic |

**Decision**: pexpect for Python-only Phase 1. portable-pty (via PyO3) when Rust hybrid is implemented. pexpect is battle-tested (part of Jupyter, Ansible) and handles the transparent bridge pattern well.

### 2. Pipeline / Workflow Engine

| Option | Language | Stars | License | Verdict |
|--------|----------|-------|---------|---------|
| Prefect | Python | 19k+ | Apache-2.0 | Overkill for agent pipeline |
| Temporal | Go+Python SDK | 14k+ | MIT | Heavy, server-based |
| Luigi | Python | 17k+ | Apache-2.0 | Maintenance-only mode |
| Dagster | Python | 12k+ | Apache-2.0 | Data pipeline focused |
| transitions | Python | 5.6k | MIT | **USE THIS** |
| pydantic + YAML | Python | Built-in | MIT | **USE THIS** |

**Decision**: Don't use a heavy workflow engine. iEvo's pipeline is a state machine (draft -> ready -> in-progress -> review -> implemented). Use `transitions` library (5.6k stars, MIT) for the state machine + pydantic models for pipeline step definitions + YAML for pipeline config. This matches the "deterministic engine over LLM routing" principle from iEVO.md.

### 3. Plugin System

| Option | Language | Stars | License | Verdict |
|--------|----------|-------|---------|---------|
| pluggy | Python | 1.5k+ | MIT | **USE THIS** |
| stevedore | Python | 200+ | Apache-2.0 | OpenStack-focused |
| entry_points only | Python | Built-in | PSF | Too basic, no hooks |
| yapsy | Python | 200+ | BSD | Unmaintained |

**Decision**: pluggy. 1400+ pytest plugins prove it works. Hook specs + hook impls + entry_point discovery. See PROP-2026-03-04-plugin-system for details.

### 4. Credential Vault

| Option | Language | Stars | License | Verdict |
|--------|----------|-------|---------|---------|
| python-keyring | Python | 6M+ downloads | MIT | **USE for Phase 1** |
| pyrage (age) | Rust+Python | 200+ | MIT | **USE for file encryption** |
| cryptography | Python | Currently used | Apache-2.0/BSD | Keep for compatibility |

**Decision**: Replace custom RSA+AES implementation with python-keyring for OS keychain integration (macOS Keychain, Windows Credential Locker, Linux Secret Service). Use pyrage (age encryption, Rust core, PyO3 bindings) for file-at-rest encryption of `.ievo/credentials.enc`. python-keyring is the standard (used by pip itself).

### 5. Streaming JSON Parser

| Option | Language | Speed | License | Verdict |
|--------|----------|-------|---------|---------|
| ijson | Python/C | Baseline | BSD | **USE for Phase 1** |
| ijson (yajl2_c) | Python+C | 35x faster | BSD | Best Python option |
| orjson | Python+Rust | Fastest bulk | Apache-2.0/MIT | Not streaming |
| msgspec | Python+C | Very fast | BSD | Schema validation, not streaming |

**Decision**: ijson with yajl2_c backend for streaming tool call parsing. It is the standard Python streaming JSON parser. For Phase 2 (Rust hybrid), replace with serde_json streaming via PyO3.

### 6. Process Supervision

| Option | Language | Stars | License | Verdict |
|--------|----------|-------|---------|---------|
| supervisord | Python | 8k+ | Custom | Legacy, XML-RPC |
| circus | Python | 1.7k | Apache-2.0 | ZeroMQ dependency |
| asyncio tasks | Python | Built-in | PSF | **USE THIS** |
| multiprocessing | Python | Built-in | PSF | Fallback |

**Decision**: Don't add an external process supervisor. iEvo agents are short-lived processes (minutes to hours), not long-running daemons. Use Python asyncio + subprocess for process management. The competitive executor (best-of-N) uses asyncio.gather() for parallel agent spawning. For Docker containers, Docker itself is the supervisor.

## Affected Components
- Modified: `src/ievo/core/config.py` (keyring integration)
- Modified: `pyproject.toml` (new dependencies)
- New dependencies: pluggy, transitions, python-keyring, pyrage, ijson

## Scores
- Applicability: 5/5
- Effort: medium (incremental adoption)
- Impact: quality, speed, reliability, UX
