Status — heygen-avatar
As of: 2026-05-05 (Session 1 — initial build)
Current phase: Code-complete, smoke test pending
What's done
| Area |
Status |
Notes |
| Config schema + validation |
✅ Complete |
HeygenConfig, PersonaConfig, LiteConfig, KnowledgeSource types + validateConfig() 6 guards |
| Knowledge ingestion pipeline |
✅ Complete |
text, markdown, PDF, URL, BFS crawl → assembleKnowledge() with word-count truncation |
| CLI persona builder |
✅ Complete |
npx heygen-avatar init — 10-question wizard → writes heygen.config.ts |
| Server session handler |
✅ Complete |
createHeygenSessionHandler (Web Fetch API) + withExpress adapter |
useHeygenAvatar hook |
✅ Complete |
Full session lifecycle, two-phase SDK init, Lite mode wiring, cleanup |
| Lite mode conversation engine |
✅ Complete |
attachLiteLoop — accumulation pattern, BYOLLM, conversation history |
<HeygenAvatar> component |
✅ Complete |
forwardRef, AvatarHandle, loading/error states |
| Entry points + build |
✅ Complete |
Dual ESM/CJS build, CLI binary functional (151 lines), types exported |
Python module (heygen_avatar) |
✅ Complete |
create_session_token, fastapi_route, IngestPipeline |
| Example apps |
✅ Complete |
example/nextjs + example/backend scaffolded and typechecked |
| Tests (TypeScript) |
✅ 40/40 passing |
9 test files |
| Tests (Python) |
✅ 7/7 passing |
2 test files |
| Vault entry |
✅ Complete |
This document |
| GitHub repo |
✅ Created |
https://github.com/arijitchowdhury80/heygen-avatar |
| Manual smoke test |
⚠️ Pending |
Requires HEYGEN_API_KEY. Infrastructure ready at example/nextjs. |
| README (public docs) |
❌ Not started |
Needed before npm publish |
| npm publish |
❌ Not started |
After README + smoke test |
| PyPI publish |
❌ Not started |
After npm publish |
What's next (Session 2)
- Fill
HEYGEN_API_KEY in example/nextjs/.env.local and run the smoke test
- Write
README.md in repo root (getting started, API reference, config options)
- Merge
feature/heygen-avatar-package → main on GitHub
- Publish to npm:
npm publish
- Publish to PyPI:
python -m build && twine upload dist/*
- Add
heygen-avatar as a dependency to RE-Avatar project
Known issues
| ID |
Issue |
Severity |
Target |
| KI-001 |
session.py data["data"]["token"] has no KeyError guard |
P2 — non-blocking; would crash only if HeyGen changes response shape |
Session 2 |
| KI-002 |
crawl_urls in ingest.py uses broad except Exception: continue — silently swallows crawl errors |
P2 — non-blocking; add warnings.warn instead |
Session 2 |
Open questions
| ID |
Question |
Status |
| OQ-1 |
Should heygen_avatar Python module be its own repo or stay in the monorepo? |
Open — depends on whether Python consumers exist independently of the npm package |
| OQ-2 |
Should example/ be a separate GitHub repo or stay as a subfolder? |
Open |
| OQ-3 |
Versioning: should npm and pip packages version together? |
Open |