ai-shifu: a self-hosted AI teaching agent you author once

The problem AI-Shifu is built around

Most course material is written once and delivered identically to everyone. AI-Shifu starts from the opposite assumption. The README describes the project as a scalable one-on-one teaching agent: you provide expertise and teaching intent once, and the system expands it into personalized learning experiences, adapting to each learner's profile with tailored explanations, interactive probing and assessments. The tagline on the repository page is "Write Once, Teach Personally."

The intended audience is narrow and explicit. The README names course creators, enterprise training teams, and educators. In each case the input is a framework or syllabus rather than a finished script, and the output is a per-learner session. That is a different shape from a course platform: the unit of work is the interaction, not the video or the slide deck.

The project is developed by the AI-Shifu Team together with the Research Center of Intelligent Software Engineering at Harbin Institute of Technology. The repository is Apache-2.0 licensed, written primarily in Python, and the last push was on 2026-09-10. The most recent tagged release is v2.3.1, dated 2026-09-09.

How the teaching agent expands a framework into a session

The README describes four capabilities rather than an internal pipeline. A personalized explanation engine generates learning paths and tone from learner background, goals and level. Interactive Q&A decomposes questions, asks clarifying questions, and suggests next actions during a session. Course assembly takes high-level frameworks and intent and elaborates them into lessons, activities and assessments. The fourth is the outcome: reduced production and delivery overhead, with each learner getting a dedicated tutor.

What the README does not do is describe the retrieval or generation architecture. ARCHITECTURE.md exists at the top level of the repository, so the detail lives there rather than in the README, and anyone evaluating the system for a production rollout should read that file before assuming how learner profiles are stored or how a session is resumed. Treat the four capabilities as product claims, not as a specification.

The deployment shape is clearer. The stack is split into a backend image, aishifu/ai-shifu-api, and a frontend image, aishifu/ai-shifu-cook-web, which the README calls Cook Web and describes as both the learner interface and the authoring console. Two Compose files are provided. docker-compose.latest.yml tracks the :latest tags for both images. docker-compose.yml pins each image to a specific release tag, which the README recommends for staging, production mirrors and CI. Choosing between them is the first real decision an operator makes.

Installing AI-Shifu with Docker Compose

The README's quick start assumes Docker and Docker Compose are already installed. Clone the repository, move into the docker directory, and copy the full environment template. The README notes that this template already matches the bundled MySQL service and that Redis is optional.

git clone https://github.com/ai-shifu/ai-shifu.git
cd ai-shifu/docker
cp .env.example.full .env

The only mandatory edit is an LLM API key. The README gives OPENAI_API_KEY, ERNIE_API_KEY and GLM_API_KEY as examples of the keys the template accepts, and states that at least one must be set. Everything else in .env has a working default for Docker.

# edit .env and set at least one LLM key, for example:
# OPENAI_API_KEY=sk-...
docker compose -f docker-compose.latest.yml up -d

After the containers start, open http://localhost:8080 for Cook Web. Log in with any phone number; the universal verification code for demos is 1024, configurable through UNIVERSAL_VERIFICATION_CODE. The first verified user is automatically promoted to Admin and Creator, and the bundled demo course is assigned to that account.

For a reproducible environment, swap the Compose file for the pinned one. The README presents this as the recommended path for staging and production mirrors.

docker compose -f docker-compose.yml up -d

If you intend to modify the code, the repository ships dev_in_docker.sh. It builds the backend and frontend images from your local source tree and launches docker-compose.dev.yml with hot reload and bind mounts, so you do not need Python or Node runtimes on the host. Source-based installation outside Docker is not covered in the README; it points to INSTALL_MANUAL.md instead.

The defaults you must change before anyone else logs in

Three defaults in the quick start are demo conveniences, and the README says so. The universal verification code 1024 is described as for demo and testing only, to be changed or disabled in production. SECRET_KEY defaults to a demo value and should be regenerated; the README supplies the command.

python -c "import secrets; print(secrets.token_urlsafe(32))"

The third is the login flow itself. Any phone number is accepted, with verification handled by the universal code. That is a reasonable onboarding shortcut for a local evaluation and an unacceptable one for anything reachable from a network. The README does not document how to wire a real SMS provider, so if you need one, that is a gap to resolve before deployment rather than after.

There is a smaller trap in the Compose file choice. docker-compose.latest.yml pulls :latest, so two machines started a week apart can run different code with no change to your configuration. For a teaching system where a prompt or model change alters learner-visible output, that drift is worth avoiding. The pinned file exists precisely for this reason, and the README's own wording recommends it for staging and production mirrors.

What AI-Shifu does not do yet

The roadmap is unusually candid, and it is the best guide to whether this project fits. Three items are unchecked: a writing AI agent for rapid script generation and maintenance, a knowledge base, and speech input and output.

The knowledge base item matters most. AI-Shifu generates from the framework and intent you supply, not from a corpus of your documents that it retrieves at answer time. If your requirement is "answer questions from our internal handbook with citations," this is the wrong tool today; a retrieval-augmented pipeline over your own documents is the shape you want. The README's Q&A capability decomposes questions and asks clarifiers, but nothing in the README describes grounding answers in an external document store.

TTS is the one modality that is present. The README documents Volcengine HTTP v1 support through three variables: VOLCENGINE_TTS_APP_KEY as the AppID, VOLCENGINE_TTS_ACCESS_KEY as the token used in the Authorization header, and VOLCENGINE_TTS_CLUSTER_ID, which defaults to volcano_tts. In Shifu settings you select the provider name volcengine_http and pick a voice or model. Speech input is not mentioned, and the roadmap lists speech input and output together as unfinished, so read the TTS section as output only.

Internationalization has its own boundary. Shared translations live under src/i18n/<locale>/**/*.json and are consumed by both the backend and Cook Web, with conventions in docs/i18n.md. The frontend language list exposes only en-US and zh-CN, so adding a third interface language means touching the locale list, not just dropping in a JSON file.

How AI-Shifu differs from a chat wrapper or a course platform

The obvious alternative is putting your material into a general chat interface and letting learners prompt it. The difference is authoring. With a chat wrapper, the creator writes nothing structured and the learner supplies all the context; quality depends on how well each learner prompts. AI-Shifu inverts that: the creator supplies a framework and intent, and the system elaborates it into lessons, activities and assessments, then runs the session. The cost is that the creator must produce a framework in AI-Shifu's format rather than paste prose.

The second alternative is a conventional LMS with a discussion forum. An LMS gives you enrollment, grading records, cohort scheduling and audit trails that AI-Shifu's README never claims. What it does not give you is a per-learner explanation that adapts to background and level. If your requirement is compliance tracking, an LMS is the right answer and AI-Shifu is not.

The third is building on an agent framework directly. That gives you control over retrieval, memory and evaluation, at the cost of building the authoring console, the learner interface, the i18n plumbing and the TTS integration yourself. AI-Shifu's value is that those pieces already exist as a Compose stack. The trade is that you inherit its roadmap: no knowledge base, no speech input, and a writing agent still on the list.

Licence and the cost of staying current

AI-Shifu is Apache-2.0, with the licence text in LICENSE.txt. That is a permissive licence, so self-hosting inside a company and modifying the source are both within its terms. It is not legal advice, and any team embedding the system in a commercial product should have counsel read the file rather than take this paragraph's word for it.

Upgrade cost is low if you stay on Docker. Pulling new images and restarting the stack is the whole procedure when you use docker-compose.latest.yml. The pinned file trades that convenience for reproducibility, and you pay for it by editing the tag yourself on each upgrade. The README does not document rollback, schema migration or data compatibility across releases, so a team running a pinned version should check the release notes for v2.3.1 and v2.3.0 before moving, and should back up the MySQL volume first. That is a real gap, not a formality: nothing in the README tells you whether a downgrade is possible.

Running cost is dominated by the LLM key rather than by the project. Each learner session spends tokens against whichever provider you configured, and the README is silent on per-session token budgets or rate limits. If you pilot with a small group, watch the provider dashboard, not the container logs.

Editorial conclusion

Adopt AI-Shifu if you already have course material and want a self-hosted one-on-one tutor layer in front of it, and if you can supply an LLM API key and run Docker Compose. Do not adopt it if you need speech input or output, a knowledge base, or an automated writing agent, since the README lists all three as unchecked roadmap items. Before committing, verify that the pinned tags in docker-compose.yml match a release you are willing to run, and confirm that the demo verification code 1024 and the default SECRET_KEY have been replaced in your .env.

Frequently asked questions

Official sources

1. ai-shifu/ai-shifu on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases