feat(accent): add /MarkAccent/stream/ NDJSON endpoint + dev helpers

Add a streaming variant of /MarkAccent/ that processes the input as a
sequence of (line, sentence) chunks and emits one NDJSON object per
chunk in input order. Each line carries `{"chunk": line_idx,
"subchunk": sub_idx, ...AccentResponse}` so clients can render output
incrementally while keeping document position. Underlying chunk-fanout
and concurrency limiting live in pipeline.stream_accent_chunks; the
route is a thin StreamingResponse wrapper.

Streaming benefits compound: OJAD's phrasing predictor degrades on
long inputs (a single misaligned mora cascades across the paragraph),
so per-sentence chunks both stay short enough for OJAD to handle and
fan out under the bounded semaphore.

Also adds test.sh — a small bash smoke-test helper that POSTs a sample
text to either /MarkAccent/ or /MarkFurigana/ and pretty-prints the
per-moji (surface|furigana|accent_marking_type) rows. STREAM=1 switches
to the streaming endpoint, ENDPOINT= picks which router. Useful while
iterating on overrides; not wired into CI.

.gitignore adds data/ and output/ for ad-hoc test fixtures we don't
want committed.

Refs #47.

Author: torrid-fish

.gitignore

@@ -216,4 +216,7 @@ __marimo__/
 .streamlit/secrets.toml
 
 # Secrest files
-secret*
+secret*
+
+data/
+output/

api/accent/routes.py

@@ -1,8 +1,9 @@
 """FastAPI routers for MarkAccent and MarkFurigana.
 
 Each endpoint is a thin wrapper around its data layer:
-  - /MarkFurigana/  → `furigana.fetch_furigana`
-  - /MarkAccent/    → `pipeline.process_accent_chunk`
+  - /MarkFurigana/        → `furigana.fetch_furigana`
+  - /MarkAccent/          → `pipeline.process_accent_chunk`
+  - /MarkAccent/stream/   → `pipeline.stream_accent_chunks` (NDJSON)
 
 Two separate routers (rather than one shared one) keep the OpenAPI
 tagging clean and let main.py register each with its own
@@ -15,10 +16,11 @@
 
 import httpx
 from fastapi import APIRouter, Depends
+from fastapi.responses import StreamingResponse
 
 from api.accent.furigana import fetch_furigana
 from api.accent.models import AccentResponse, FuriganaResponse, Request
-from api.accent.pipeline import process_accent_chunk
+from api.accent.pipeline import process_accent_chunk, stream_accent_chunks
 from api.dependencies import get_http_client
 
 logger = logging.getLogger("api")
@@ -57,3 +59,19 @@ async def mark_accent(
     """Receive POST request, return an AccentResponse object."""
     logger.info(f"[API] Received Request Text: {request.text}")
     return await process_accent_chunk(request.text, client)
+
+
+@accent_router.post("/MarkAccent/stream/", tags=["MarkAccent"])
+async def mark_accent_stream(
+    request: Request,
+    client: httpx.AsyncClient = Depends(get_http_client),
+) -> StreamingResponse:
+    """Split the input on `\\n` (line) and then on full-width sentence
+    terminators (sub-chunk), process each piece in parallel under a bounded
+    semaphore, and stream one NDJSON line per piece in input order.
+    """
+    logger.info(f"[API] Received streaming request: {request.text!r}")
+    return StreamingResponse(
+        stream_accent_chunks(request, client),
+        media_type="application/x-ndjson",
+    )

test.sh

@@ -0,0 +1,102 @@
+#!/bin/bash
+# Send a test text to the local API and print one
+# (surface|furigana|accent_marking_type) line per moji.
+#
+# Usage:
+#   ./test.sh                                  # default text on MarkAccent
+#   ./test.sh "三月五日（土）"                  # custom text
+#   PORT=8000 ./test.sh                        # different port
+#   ENDPOINT=MarkFurigana ./test.sh            # furigana endpoint (accent="-")
+#   STREAM=1 ./test.sh $'first\nsecond'        # streaming endpoint, NDJSON
+
+set -euo pipefail
+
+TEXT="${1:-3月5日(土)}"
+PORT="${PORT:-8000}"
+ENDPOINT="${ENDPOINT:-MarkAccent}"
+STREAM="${STREAM:-0}"
+
+if [[ "$STREAM" == "1" ]]; then
+  URL="http://127.0.0.1:${PORT}/api/${ENDPOINT}/stream/"
+else
+  URL="http://127.0.0.1:${PORT}/api/${ENDPOINT}/"
+fi
+
+PAYLOAD=$(uv run python -c \
+  'import json, sys; print(json.dumps({"text": sys.argv[1]}))' "$TEXT")
+
+if [[ "$STREAM" == "1" ]]; then
+  # Streaming mode: pipe NDJSON straight to a per-line viewer.
+  read -r -d '' STREAM_VIEWER <<'PY' || true
+import sys, json
+
+seen = 0
+for raw in sys.stdin:
+    raw = raw.strip()
+    if not raw:
+        continue
+    seen += 1
+    d = json.loads(raw)
+    chunk = d["chunk"]
+    sub = d.get("subchunk", 0)
+    status = d["status"]
+    err = d.get("error")
+    result = d.get("result") or []
+    print(f"--- chunk {chunk}.{sub}  status={status}  words={len(result)} ---")
+    if err:
+        print(f"  ERROR: {err}")
+        continue
+    for w in result:
+        surface = w["surface"]
+        accents = w.get("accent") or []
+        if not accents:
+            print(f"  ({surface}|{w['furigana']}|-)")
+            continue
+        for a in accents:
+            moji = a["furigana"]
+            t = a["accent_marking_type"]
+            print(f"  ({surface}|{moji}|{t})")
+if seen == 0:
+    print("(empty stream — no non-blank input lines)")
+PY
+
+  # -N disables curl's output buffering so each NDJSON line lands in the
+  # viewer as soon as the server flushes it.
+  curl -sN -X POST "$URL" \
+    -H 'Content-Type: application/json' \
+    --data-raw "$PAYLOAD" \
+  | uv run python -c "$STREAM_VIEWER"
+  exit 0
+fi
+
+# Non-streaming mode (original behaviour).
+HTTP_STATUS=$(curl -s -o /tmp/test_sh_body.$$ -w '%{http_code}' \
+  -X POST "$URL" -H 'Content-Type: application/json' --data-raw "$PAYLOAD" \
+  || true)
+if [[ "$HTTP_STATUS" != "200" || ! -s /tmp/test_sh_body.$$ ]]; then
+  echo "Request to $URL failed (HTTP ${HTTP_STATUS:-no-response})." >&2
+  echo "Is the server running? Try: uv run uvicorn main:app --host 127.0.0.1 --port ${PORT}" >&2
+  rm -f /tmp/test_sh_body.$$
+  exit 1
+fi
+
+read -r -d '' FORMAT_SCRIPT <<'PY' || true
+import json, sys
+
+data = json.load(sys.stdin)
+if data.get("status") != 200 or not data.get("result"):
+    print("ERROR:", data.get("error") or data)
+    sys.exit(1)
+
+for w in data["result"]:
+    surface = w["surface"]
+    accents = w.get("accent") or []
+    if not accents:
+        print(f"({surface}|{w['furigana']}|-)")
+        continue
+    for a in accents:
+        print(f"({surface}|{a['furigana']}|{a['accent_marking_type']})")
+PY
+
+uv run python -c "$FORMAT_SCRIPT" < /tmp/test_sh_body.$$
+rm -f /tmp/test_sh_body.$$