Concepts
개념
Two programs, one protocol
두 프로그램, 하나의 프로토콜
What runs where, how a message travels, and where the project is heading.
무엇이 어디서 돌고, 메시지가 어떻게 오가며, 프로젝트가 어디로 가는지.
The client
클라이언트
app/ is a Kotlin Compose Multiplatform application. Almost everything lives in commonMain: the screens, the view models and the network client. Each platform contributes only an entry point and, for Android, iOS and desktop, the shared Ktor CIO engine in cioMain.
app/ 은 Kotlin Compose Multiplatform 앱입니다. 거의 모든 것이 commonMain 에 있습니다: 화면, 뷰모델, 네트워크 클라이언트. 각 플랫폼은 진입점만, 그리고 Android · iOS · 데스크톱은 cioMain 의 공유 Ktor CIO 엔진만 보탭니다.
| Source set소스셋 | Holds내용 |
|---|---|
commonMain | UI, view models, protocolUI, 뷰모델, 프로토콜 |
cioMain | Ktor CIO HTTP/WebSocket engineKtor CIO HTTP/WebSocket 엔진 |
androidMain · iosMain | Activity / UIViewController entryActivity / UIViewController 진입점 |
desktopMain | Jewel window, command-line flagsJewel 창, 명령줄 옵션 |
wasmJsMain | Browser entry, Ktor JS engine브라우저 진입점, Ktor JS 엔진 |
The server
서버
api/ is a FastAPI application. A model (Qwen 3) owns its prompt, sampling defaults and the tools it may call; a single transformers-based engine (on upstream PyTorch or torchnative) owns the weights and the generation loop. A session binds a client to a model; models are loaded lazily and shared by sessions.
api/ 은 FastAPI 앱입니다. 모델(Qwen 3)은 프롬프트, 샘플링 기본값, 호출 가능한 도구를 가지고, transformers 기반 단일 엔진(upstream PyTorch 또는 torchnative 위)은 가중치와 생성 루프를 가집니다. 세션은 클라이언트를 모델에 묶습니다. 모델은 처음 쓸 때 로드되고 세션끼리 공유됩니다.
One message, end to end
메시지 하나의 여정
- The client creates a session:
POST /api/models/qwen3/sessions/. - 클라이언트가 세션을 만듭니다:
POST /api/models/qwen3/sessions/. - It opens
/api/chat/streamingand sends three frames: the session id, the history, the prompt. /api/chat/streaming을 열고 프레임 세 개를 보냅니다: 세션 id, 대화 기록, 프롬프트.- The server streams text back.
<think>…</think>frames bracket reasoning;<tool_call>frames report tool activity. - 서버가 텍스트를 흘려 보냅니다.
<think>…</think>프레임이 추론을 감싸고,<tool_call>프레임이 도구 활동을 알립니다. - If the model called tools, the server runs them in parallel, adds the results to the history and generates again.
- 모델이 도구를 호출했다면 서버가 병렬로 실행해 결과를 기록에 넣고 다시 생성합니다.
<EOS>ends the answer and the socket closes.<EOS>가 답을 끝내고 소켓이 닫힙니다.
The details are in Streaming protocol.
자세한 내용은 스트리밍 프로토콜에 있습니다.
The road to on-device
온디바이스로 가는 길
The server exists because phones cannot yet run the Python model code. Python Multiplatform embeds CPython in Kotlin Multiplatform; once Gemstone adopts it, the model moves into the app and the network step disappears. That is the project's intent. The server is the bridge, not the destination.
서버가 있는 이유는 아직 휴대폰이 Python 모델 코드를 돌릴 수 없기 때문입니다. Python Multiplatform 은 CPython 을 Kotlin Multiplatform 에 임베딩합니다. Gemstone 이 이를 채택하면 모델이 앱 안으로 들어오고 네트워크 단계가 사라집니다. 그것이 이 프로젝트의 의도입니다. 서버는 다리이지 목적지가 아닙니다.
Status: planned (#42). See FAQ & status.