# Prototype Layout

## 目标

为 memabra 建立一个最小可运行的原型目录结构，让后续 rule-based router、replay harness、sample trajectories 和训练样本生成都能有明确落点。

## 目录结构

```text
src/memabra/
├── __init__.py
├── candidate_types.py      # 统一候选对象与决策类型
├── router.py               # Rule-based router baseline
├── telemetry.py            # 事件、reward、轨迹的运行时结构
├── reward.py               # reward 聚合逻辑
├── retrieval.py            # 后续：候选召回接口
├── memory_store.py         # 后续：长期记忆存取
├── replay.py               # 后续：trajectory 回放与评估
└── schemas.py              # 后续：schema 装载/校验

tests/memabra/
└── test_router_smoke.py    # baseline 冒烟测试
```

## 当前已落地

已创建：
- `src/memabra/__init__.py`
- `src/memabra/candidate_types.py`
- `src/memabra/router.py`
- `src/memabra/telemetry.py`
- `src/memabra/reward.py`
- `tests/memabra/test_router_smoke.py`

## 模块边界

### candidate_types.py
负责：
- `CandidateObject`
- `DecisionType`
- 后续可扩展 memory/skill/tool type-specific adapter

### router.py
负责：
- `TaskContext`
- `RouteDecision`
- `RuleBasedRouter`

当前只实现 baseline 启发式，后续升级为：
- 特征打分器
- reranker
- learned policy

### telemetry.py
负责：
- 原子事件结构
- reward breakdown
- 后续 trajectory runtime objects

### reward.py
负责：
- reward 组合与计算
- 后续权重版本化

## 设计原则

1. 先有可运行 baseline，再抽象复杂接口
2. 数据结构先简单，但字段命名与 Phase 0 schema 保持一致
3. 先保证 replayable，再考虑高性能
4. 不提前引入数据库或向量库耦合

## 下一步落点

- `retrieval.py`：定义候选召回接口
- `replay.py`：实现 trajectory 读取、回放和指标计算
- `schemas.py`：把 JSON schema 转成运行时校验入口
- `sample_data/`：放示例 candidates 和 trajectories

## 验证建议

在项目根目录运行：

```bash
source venv/bin/activate
python -m pytest tests/memabra/test_router_smoke.py -q
```

期望：
- baseline router 冒烟测试通过
- 说明最小原型骨架已可被导入和调用