# jevDemo

**Repository Path**: Caleb_F/jev-demo

## Basic Information

- **Project Name**: jevDemo
- **Description**: 准备为jev模型的工业化做准备
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-09-22
- **Last Updated**: 2026-09-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# jev-demo — Jev Agent Router

用 TypeSafe 的 System One 模型 **Jev** 做快速意图路由：一次请求同时拿
`intent`(Choice) / `urgency`(Score) / `needs_human`(Noul)，概率如何用由本服务决定。

## 分层

```
jev_router/api.py       Web 层     FastAPI：参数校验、错误码、/healthz、/metrics
jev_router/service.py   Service 层 长度/历史校验、PII 脱敏、Jev 故障降级（is_degraded）、决策打点
jev_router/decision.py  纯决策     阈值 → HANDLE / HUMAN / FALLBACK，可单测、可校准
jev_router/manager.py   Manager 层 SDK 封装：pin 模型、超时/重试预算、并发上限、熔断、统一异常、request_id 日志
jev_router/breaker.py   熔断器
jev_router/intents.py   Intent 枚举 = criteria 与 handler 的唯一数据源
jev_router/config.py    RouterSettings，全部可由 ROUTER_* 环境变量覆盖
jev_router/metrics.py   Prometheus 指标（决策计数、Jev 延迟/错误/tokens、熔断状态）
jev_router/dispatch.py  HandlerRegistry / Dispatcher：业务方注册各意图的处理函数
jev_router/evaluate.py  离线校准：标注集 → 采集 verdict → 回放扫阈值
jev_router/route_input.py  RouteInput / Turn：当前消息 + 历史 + 用户标签
jev_router/cli.py       开发用 CLI
data/labeled.jsonl      标注集样例（20 条，中英混合）
```

## 请求格式

```json
POST /route
{
  "message": "still not working",
  "history": [{"role": "user", "content": "app crashes"}, {"role": "agent", "content": "try reinstalling"}],
  "user_tags": ["enterprise"]
}
```
`history` / `user_tags` 可选。带上下文时 state 以 JSON 对象发给 Jev，问题 instructions 已声明"只判断最新一条消息、历史仅作参考"。

## 接入业务 handler

```python
from jev_router.dispatch import Dispatcher, HandlerRegistry
from jev_router.intents import Intent

registry = HandlerRegistry()

@registry.intent(Intent.BILLING)
async def billing(decision, message):
    return await ticket_system.create(message, priority=decision.is_priority)

registry.on_human(lambda d, m: human_queue.push(m))
registry.on_fallback(lambda d, m: default_queue.push(m))

result = await Dispatcher(registry).dispatch(decision, message)
```

## 本地开发

```bash
./run.sh                 # 跑 7 条内置样例（首次弹窗要 key）
./run.sh "我要退款"       # 路由自定义消息
./run.sh --serve         # http://127.0.0.1:8000/docs
./run.sh --test          # ruff + pytest
```

## 生产部署

```bash
docker build -t jev-router .
docker run -p 8000:8000 -e TYPESAFE_API_KEY=... -e ROUTER_JEV_MODEL=jev-1.13.0 jev-router
```

- **模型必须 pin 版本**（`ROUTER_JEV_MODEL`）。`jev-latest` 会随发版移动，三个阈值是针对具体版本校准的。
- **降级**：Jev 超时/限流/5xx/熔断打开时 `/route` 仍返回 200，`action=fallback, is_degraded=true`；调用方按此走默认队列。
- **日志**：`TYPESAFE_LOG_LEVEL=debug` 会打印完整请求/响应体（含用户消息），生产禁用。发往 Jev 的消息已脱敏手机号/邮箱。
- **限流**：官方 1,200 RPM / 250k tokens/s（账号级）；`ROUTER_MAX_CONCURRENCY` 控进程内并发，429 时 SDK 会按 `Retry-After` 退避。
- **成本**：$0.042 / M input tokens，输出免费。

## 阈值校准

```bash
uv run python -m jev_router.evaluate data/labeled.jsonl --floors 0.4,0.55,0.7   # 调 Jev 采集并缓存 verdict
uv run python -m jev_router.evaluate data/labeled.jsonl --replay --floors 0.5,0.6  # 只回放缓存，不花钱
```
换模型版本时重新采集；只调阈值时回放即可。标注集格式每行 `{"message": ..., "expected": "<intent>|human"}`。

## 指标

`GET /metrics`（Prometheus 文本）：`router_decisions_total{action,intent,degraded}`、
`router_jev_latency_seconds`、`router_jev_errors_total{kind}`、`router_jev_input_tokens_total`、`router_breaker_state`。

## 文档
- Python SDK: https://docs.typesafe.ai/sdk/python/usage
- 模型/限流/价格: https://docs.typesafe.ai/models