How generalusermodels/gum works
Project type and purpose
• From the README and file tree, GUM is an open-source Python library and CLI tool for building “General User Models.”
• It ingests unstructured observations (e.g., screenshots), applies inference and retrieval to generate confidence-weighted propositions about a user, and stores and continuously revises those user models.
File structure
• Top-level files: setup.py, pyproject.toml, CLI entry point (gum/cli.py), database utilities (gum/db_utils.py).
• Core library: gum/gum.py implements the main GUM pipeline.
• Domain objects: gum/models.py (proposition/data classes), gum/schemas.py (validation/serialization).
• Plugin-style observers: gum/observers/observer.py defines the interface; gum/observers/screen.py implements one observer.
• Prompt modules: gum/prompts/gum.py and gum/prompts/screen.py generate instruction templates for inference.
• Documentation (docs/), CI (GitHub Actions for doc deployment), utility scripts (pip-update.sh).
README for additional insights
• The “architecture” is described in prose in the paper and docs:
a) Observation collection
b) Inference to propose new user facts via prompts & LLM
c) Retrieval of relevant context
d) Revision of existing propositions
e) Continuous update loop
• No built-in web service or front end; primary interface is CLI and library API.
Main components
a. Input Layer
• Observer Plugins (gum/observers/*)
• CLI or Host Process invokes observers
b. Core Engine
• GUM Pipeline (gum/gum.py)
• Inference Module (uses gum/prompts + external LLM)
• Retrieval Module (loads relevant propositions from DB)
• Revision Module (updates existing propositions)
c. Data Layer
• Proposition Store (via gum/db_utils.py; could be SQLite/Postgres)
• Schema & Validation (gum/schemas.py)
d. Model Definitions
• Data classes and ML/logic definitions in gum/models.py
e. Integration Points
• External LLM or AI Service (e.g., OpenAI/GPT API)
• Filesystem or other storage
• CLI (gum/cli.py) / Library API
Relationships and interactions
• Observers → (raw observations) → Core Engine.Inference
• Core Engine.Inference ↔ Prompts → External LLM
• LLM response → Core Engine.Retrieval & Revision
• Core Engine outputs → Data Layer (store/update propositions)
• CLI/API calls orchestrate the above flow
Architectural patterns and design principles
• Plugin pattern for observers and prompts (observer.py interface)
• Layered architecture: Input → Processing → Storage
• Single Responsibility: each module handles a defined step (observe, prompt, infer, store)
• Dependency injection via library API for custom observers or prompt templates