How ianloe/twinsphere works
TwinSphere is an on-premises personal AI digital twin: users provide documents and memories, then chat with a persona-shaped assistant grounded in that knowledge. The main paths run through FastAPI: ingestion parses and indexes content; chat retrieves vector and graph context, generates a response with a local LLM, and applies voice rules. The graph follows documented and excerpted relationships; some UI proxy wiring and conversation-session integration are not shown in the sampled source.
Main entry points: twin_engine.py Twin engine · pipeline.py Ingestion pipeline · main.py FastAPI · nginx.conf Frontend proxy
Components 15
User interaction
- Chat UI
frontend/index.html - Admin UI
frontend/admin.html - Frontend proxy
frontend/nginx.conf
API orchestration
- FastAPI
api/main.py - Conversation sessions
api/middleware/session.py
Knowledge ingestion
- Ingestion pipeline
ingestion/pipeline.py - Document chunker
pipeline/chunker.py - Entity extractor
pipeline/entity_extractor.py
Retrieval and generation
- Ollama embedder
pipeline/embedder.py - Twin engine
pipeline/twin_engine.py - Persona specification
persona/example_persona.yaml
Knowledge stores
- Vector store
vector/qdrant_client.py - Knowledge graph
graph/neo4j_client.py
Other components
- User
- Local LLM
Connections 19
- User → Chat UI: asks twin
README.md - User → Admin UI: submits content
README.md - Chat UI → Frontend proxy: serves through
README.md - Admin UI → Frontend proxy: serves through
README.md - Frontend proxy → FastAPI: proxies requests
README.md - FastAPI → Twin engine: calls chat
api/main.py - FastAPI → Ingestion pipeline: routes ingestion
api/main.py - Ingestion pipeline → Document chunker: chunks documents
ingestion/pipeline.py - Ingestion pipeline → Entity extractor: extracts entities
ingestion/pipeline.py - Ingestion pipeline → Ollama embedder: embeds content
ingestion/pipeline.py - Ingestion pipeline → Vector store: stores vectors
ingestion/pipeline.py - Ingestion pipeline → Knowledge graph: writes graph
ingestion/pipeline.py - Twin engine → Ollama embedder: embeds query
pipeline/twin_engine.py - Twin engine → Vector store: searches memories
pipeline/twin_engine.py - Twin engine → Knowledge graph: expands context
pipeline/twin_engine.py - Twin engine → Entity extractor: matches entities
pipeline/twin_engine.py - Twin engine → Persona specification: loads persona
pipeline/twin_engine.py - Twin engine → Local LLM: generates response
pipeline/twin_engine.py - FastAPI → Conversation sessions: persists turns