Language Learning App with Agent Recommendations

This language learning app will have agent giving further instructions and practice on spot when detecting users with difficulties about certain grammar, vocab, etc.

Comment

Oonie

Oonie is a course-grounded, adaptive Chinese-learning prototype. It keeps a clear curriculum path, watches for concept-level learning evidence, and inserts focused support when a learner appears to need it.

Prototype scope and current limitations

This hackathon build is intentionally narrow. It demonstrates one complete learning route and one complete adaptive intervention; it is not yet a full language-learning platform.

Available to Try Now

  • The first restaurant communication dive, Arriving & Getting A Table
  • 7 interactive lessons with 105 activities
  • 8 core words and 2 grammar patterns taught in context
  • Vocabulary, grammar, sentence ordering, listening, shadowing, and culture activities
  • Packaged course audio, hints, immediate feedback, lesson progress, and completion state
  • One fully implemented adaptive rescue: repeated difficulty with the same concept triggers a short explanation followed by a recognition check and a transfer check
  • An authored rescue that works without an API key, plus an optional OpenAI-powered experiment that generates one tightly constrained rescue with two checks from the same course concept card

Visible, But Not Implemented Yet

  • Dive Groups 2 and 3 are curriculum outlines only; their lessons do not open
  • Some word and grammar cards for future dives are previews, not completed lesson content
  • The bottom Words, Grammar, Class, and Profile destinations are placeholders
  • XP and streak numbers are sample interface state
  • Progress is kept only in the current Streamlit session and URL state; there are no accounts, persistent learner profiles, or database sync
  • Shadowing is self-guided; the prototype does not record speech or score pronunciation and tones
  • Long-term mastery tracking, spaced review, placement, teacher authoring, and full curriculum ingestion are not implemented
  • Only one adaptive rescue path is fully built. The optional general-purpose model call is an experiment, not the intended production model architecture

Inspiration

The sequence and clarity of the HSK Standard Course textbook series inspired my curriculum direction. Its structured progression led me to ask a larger product question: can a language app preserve the reliability of a real course while still responding to the way each learner studies?

Many digital learning experiences sit at one of two extremes. A fixed exercise path is predictable but can miss the reason a learner is struggling. An open-ended AI tutor can feel flexible but may drift away from the course, introduce material too early, or generate assessments whose quality is difficult to guarantee. I wanted a third approach: the course remains the source of truth, while the system dynamically decides when and how to support the learner.

What Oonie Does

The prototype presents Chinese as a communication expedition rather than an unstructured chat. In the working restaurant dive, learners build vocabulary and grammar through short activities, listening, sentence construction, shadowing, and cultural context.

Behind the lesson flow, each exercise is linked to explicit concept IDs. Oonie observes concrete evidence such as incorrect answers, hint use, and unusually slow responses. A single mistake does not produce a diagnosis. When enough recent evidence points to the same concept, the app explains why support is being offered and inserts a two-minute rescue.

The rescue teaches one bounded contrast, then asks two questions: one for recognition and one for transfer. Passing both checks means the learner is ready to rejoin the lesson; it does not claim long-term mastery. The same concept should still return through later spaced review.

How I Built It

Oonie is a responsive Streamlit app written in Python. The course is represented as structured JSON rather than embedded in prompts: lessons contain exercises and concept IDs, while adaptive concept cards define the approved rule, examples, misconceptions, vocabulary boundaries, and fallback remediation. Packaged WAV files support the listening and shadowing activities.

The intervention trigger is deterministic and evidence-based. The model is not asked to decide whether a learner “knows” Chinese. By default, the demo uses a course-authored rescue, so the complete experience works offline. If an OpenAI API key is configured, the current experiment sends only the relevant concept card and a small evidence summary to the Responses API, requests a typed micro-lesson and two checks, validates the returned content, and falls back to the authored version if the call or validation fails. This bounded generation experiment demonstrates the adaptive loop; it is not the final content architecture described below.

How I Ssed GPT-5.6 Sol

I used GPT-5.6 Sol in Codex as my primary development collaborator across the entire build, from the first product outline to the submission-ready prototype. It helped me:

  • Turn the initial learning-product idea into a narrow, testable demo scope
  • Structure the HSK-inspired curriculum, concept IDs, lesson sequence, evidence rules, and adaptive-rescue data contracts
  • Draft and refine original exercises, explanations, interface copy, and the project story for human review
  • Implement and iterate on the Python and Streamlit application, responsive HTML/CSS interface, structured JSON content, audio integration, validation, and fallback behavior
  • Inspect the running experience, diagnose bugs, create smoke checks, verify the golden demo path, and prepare deployment and handoff documentation
  • Translate my hand-drawn “sticker expedition journal” direction into a visual prompt, direct the generation of the otter-diver mascot through Codex’s built-in image-generation capability, and prepare and integrate the resulting asset into the interface

This was an iterative development workflow rather than a one-shot app generation. I repeatedly used GPT-5.6 Sol to inspect the repository, edit the implementation, run checks, compare the result with the intended learning experience, and refine the next version.

GPT-5.6 Sol is the model I used to build the prototype; it is not presented as the learner-facing model running inside the current demo. The default adaptive rescue is authored course content, while the optional runtime experiment currently uses a separate small model through the OpenAI Responses API. My longer-term learner-facing architecture is the curriculum-grounded open-source model service described below.

This separation gave me three useful layers:

  1. Curriculum: what may be taught, in what sequence, and within what boundaries
  2. Learning Evidence: what the learner actually did on concept-linked activities
  3. Adaptation: when to insert an explanation, extra practice, or later review

What Makes Oonie Different

Oonie is not intended to become a chatbot that freely generates a course around each conversation. My long-term direction is to adapt an open-source base model using my internally developed teaching materials, curriculum graph, teacher-reviewed examples, and evaluation set, then serve that model through an API.

The internal curriculum will remain the framework and source of truth. At runtime, the system should retrieve the relevant approved concepts, select and sequence validated activities, and tailor the explanation or delivery to the learner. It should not freely invent intermediate check-ins, answer keys, or assessment criteria. Where bounded content variation is useful, outputs should remain constrained by the current lesson, validated against the curriculum, versioned, and reviewable by the course team.

That architecture lets the experience become more dynamic without becoming pedagogically random. Over time, Oonie could vary the timing, length, modality, and examples of an explanation; insert targeted practice; or change the review schedule based on user habits, while preserving the goals and boundaries of the authored course.

Challenges I Ran into

  • Making the prototype honest about its boundaries while still showing a coherent product vision
  • Connecting every activity to teachable concepts so that adaptation is explainable instead of arbitrary
  • Distinguishing a one-off mistake from repeated evidence of difficulty
  • Keeping model output grounded, structured, and replaceable with a safe authored fallback
  • Carrying enough learning state through a lightweight Streamlit demo without pretending it is a production learner database
  • Building enough original lesson and audio content to make one route feel complete rather than spreading placeholder content across the whole product

Accomplishments I am Proud of

  • A complete first dive with 7 lessons and 105 activities
  • A working evidence-to-intervention loop that learners can trigger and finish
  • Course-linked JSON data that separates concepts, exercises, evidence, and remediation
  • A usable no-key fallback and a validated optional API path
  • Clear in-product disclosure of what is live, what is a preview, and what is planned

What I Learned

The most important adaptive-learning work happens before model prompting. A useful intervention depends on well-structured curriculum metadata, reliable exercise tagging, clear evidence thresholds, and an honest definition of success. I also learned that a two-question check can support an immediate teaching decision, but it should never be presented as proof of lasting mastery.

Most importantly, “personalized” should not mean “unbounded.” The strongest version of Oonie will combine teacher control, learner evidence, and a narrowly trained model service rather than asking a general-purpose model to improvise the learning experience.

What is Next

The next phase is to turn the prototype’s course cards into a versioned internal curriculum and data system. I expect to store only the information needed to improve learning and explain system decisions:

  • Learning Events: pseudonymous learner ID, exercise ID, concept IDs, selected response, correctness, response time, hint use, attempt number, timestamp, and course version
  • Concept State: recent evidence, accuracy, independence from hints, recurring misconception tags, transfer results, last-seen time, next-review time, and a state such as unseen, learning, fragile, or secure
  • Learner Preferences: goals, pace, pinyin or character support, preferred explanation length, audio speed, and accessibility settings
  • Curriculum Records: concept prerequisites, allowed vocabulary, approved explanations and activities, source/provenance, rights status, teacher review, and content version
  • Model-Service Records: retrieved curriculum IDs, model and prompt version, validation result, selected intervention, and learning outcome while avoiding unnecessary identity data and a learner’s full history

With that foundation, I can expand the curriculum, add persistent accounts and spaced review, build teacher authoring and approval tools, evaluate an open-source base model against teacher-reviewed cases, and expose the resulting service through a stable API.

Run Locally

python -m pip install -r requirements.txt
python -m streamlit run app.py

No API key is required for the authored demo. See RUN_DEMO.md for the recommended adaptive-rescue walkthrough.

To test the optional API-tailored wording, set server-side environment variables before starting Streamlit:

$env:OPENAI_API_KEY="your-api-key"
$env:OPENAI_MODEL="gpt-5-nano"
python -m streamlit run app.py

Never commit API keys. A local .streamlit/secrets.toml is also supported and ignored by git.

Deployment

  • Streamlit Community Cloud repository: maikurokosmos/oonie-demo-only
  • Branch: main
  • Entrypoint: app.py
  • Python: 3.12

See STREAMLIT_DEPLOY.md for deployment instructions and AI_ADAPTIVE_LEARNING.md for the current data contracts, trigger rules, validation requirements, and evaluation direction.

Built With

Share this project:

Updates