Starforge AI Narrative
A school-life adventure game driven by multi-agent AI and RAG
An AI-driven 2D school-life narrative adventure game. The FastAPI backend implements a multi-agent system (planner, dialogue, memory, safety agents) combined with RAG retrieval and tool calling to dynamically generate NPC dialogue and story branches; the frontend is a hand-built TypeScript/Vite 2D engine. A mock-first design lets the whole stack run and be tested without a GPU.
Verified Demo Recording 1
Copied by the portfolio quality pass from existing project demo media.
Media overview
Browse the project screenshots and recorded walkthroughs.
Project links and demo readiness
live
Live Demo
Open the verified live demo when available, or use the internal run guide for manual demo preparation.
github
View GitHub
Open the public repository when available, or review the source-access status captured by this case study.
video
Demo Recording
Open the demo recording when available, or use this section as the recording checklist for the project.
documentation
README
Open the project README when available, or use this case study as the documentation baseline.
Project overview
## Overview Starforge AI Narrative is an AI-driven 2D school-life adventure game set around an American 5th-grade student's school and neighborhood. Gameplay centers on dialogue, choices and quests, where the player builds relationships with classmates and friends and cooperates to handle situations like bullying. The guiding idea is deep involvement of LLMs, RAG and AI agents so that every interaction's dialogue and story direction is generated dynamically, approaching a human-like experience. ## Technical Architecture The backend is built on **FastAPI** with a multi-agent orchestrator: `PlannerAgent` uses an LLM to dynamically plan the sequence of tools to call, `DialogueAgent` assembles RAG context and game state before generating a response, and `MemoryAgent` plus `SafetyAgent` handle memory and content safety. Tools are registered through a ToolRegistry (game_state, search_lore, web_search, roll_check). RAG is implemented via VectorStore and Embedder abstractions, supporting both mock keyword matching and vector-similarity modes. ## Mock-first Design The system revolves around swappable provider abstractions: `llm_provider` switches between `mock`, `openai`, and `local` (transformers/PyTorch), while the vector store and image generation (Stable Diffusion) also ship with mock implementations. This lets the full API and frontend boot and pass pytest suites even with no GPU or API keys, following a 'run first, swap in real models later' strategy. ## Frontend and Deployment The frontend is a hand-written 2D game engine in **TypeScript + Vite**, with managers for scene management (exploration / interior / title), quests, shops, achievements, events, saves and i18n, and support for Tiled (.tmx) maps. The project includes Docker (nginx) deployment configs, and the backend data layer is backed by async SQLAlchemy with SQLite/PostgreSQL, retaining an in-memory mode for easy testing.
My role
Solo full-stack developer (backend AI architecture, frontend game engine, testing)
Problem
Traditional text adventures hard-code dialogue and branches and feel mechanical; meanwhile AI integration usually demands costly models and GPUs, raising the bar for development and testing.
Solution
A swappable LLM provider abstraction (mock/OpenAI/local transformers) drives a multi-agent orchestration: a PlannerAgent uses the LLM to plan a tool sequence, a DialogueAgent assembles context, and Memory/Safety agents guard state and content. RAG vector retrieval ingests player-customizable world lore and character settings to generate context-appropriate dialogue and quest outcomes.
Current outcome
A working MVP prototype: in mock mode the API and frontend boot with no GPU, pytest covers dialogue, planning, vector store and save modules, and Docker deployment configs are provided.
Highlights
- Multi-agent architecture: Planner / Dialogue / Memory / Safety agents, with the LLM dynamically planning tool sequences and falling back to defaults on parse failure
- Pluggable LLM provider abstraction (mock / OpenAI / local transformers) plus a mock vector store, enabling full-feature development with no GPU
- RAG system supports player-uploaded custom world lore and character settings, auto-ingested into the vector store at startup
- Tool registry integrating callable tools: game_state, search_lore, web_search (Brave), and roll_check
- Hand-built TypeScript/Vite 2D game engine with scene management, quests, shops, achievements, saves and i18n
- Mock-first testing strategy: pytest-asyncio covers core AI and game services so everything runs before swapping in real models
Engineering challenges
- Keeping AI features developable and testable on GPU-less machines required designing a mock/stub for every external dependency
- Orchestrating multi-agent, multi-step tool planning is complex and required robust fallback handling for LLM output parsing failures
Target users
- Portfolio reviewers and interviewers
- Technical readers who need a quick view of purpose, stack, and maturity
Technical highlights
- Detected technical signals: Python, FastAPI, Pydantic, SQLAlchemy, OpenAI API, Transformers, PyTorch, TypeScript, Vite, Docker, pytest, SQLite
- README evidence exists and can support a fuller reviewed case study
- A public GitHub repository is linked for source traceability
Architecture
This case study is generated from the portfolio catalog pipeline using README, Git metadata, package/build configuration, and media signals. The final architecture narrative still needs source-level review. Current detected technology signals include: Python, FastAPI, Pydantic, SQLAlchemy, OpenAI API, Transformers, PyTorch, TypeScript, Vite, Docker, pytest, SQLite.
Data flow
A public data-flow narrative is not fully reviewed yet. If the project includes data processing, AI pipelines, or backend APIs, the next pass should document input, processing, storage, and UI/output flow end to end.
Project structure
starforge-AI-narrative/ README.md # project documentation, when available source files # implementation reviewed by local audit package/build config # detected capability signals
Setup / Run guide
This project does not expose a verified runnable web command yet. Review the README/source tree and add exact install, run, test, and build commands before interview use. No verified build command was detected. Treat the current portfolio page as a case-study placeholder until build steps are reviewed.
Future improvements
- Complete the production-quality README, screenshots, and demo recording
- Add architecture diagrams, data-flow notes, and key technical decisions
- Verify build/test status and update the portfolio release report
Interview notes
- State the current maturity and demonstrable scope first
- Focus on verified stack, source structure, and completed behavior
- Do not claim unverified deployment, video, or test coverage as finished
Next steps
- Wire in real local LLMs (Qwen2-7B) and OpenAI models to validate generation quality
- Integrate Stable Diffusion for on-the-fly scene/character/item image generation (currently mocked)