Project Information

Technology Stack

Build Status

Container Images

MUCGPT is a system that enables users to interact with a large language model (LLM) through a web interface. This interaction is facilitated by an agentic system that can access several tools. To get a feel for it, take a look at our demo frontend.

Roles and rights management is facilitated by access to an OpenID Connect provider.

Users can create their own assistants and share them within the organisation. A personal assistant is a configuration of the MUCGPT agent, particularly the activated tools and system prompts.

See the open issues for a full list of proposed features (and known issues).

Table of contents

• Built With
• Getting Started
• Roadmap
• Documentation
• Contributing
• License
• Contact

⚒️ Built With

Backend

• Python 3.10, 3.11 or 3.12
• FastAPI
• LangGraph

Frontend

• React
• Typescript
• Javascript

Deployment

• Node.js 20+
• Git
• Python 3.12
• uv
• Docker

🏃‍♂️‍➡️ Getting started

• Install uv: https://docs.astral.sh/uv/getting-started/installation/
  • Using UV during development
• Install Node.js 20+

⚙️ Configure the environment

Configuration can be found in form of an .env file

cd stack
cp .env.example .env

Below is an example of how to configure the MUCGPT_CORE_MODELS environment variable in your .env file. This variable defines the available LLM models for the core backend as a JSON array. Each object in the array specifies the model type, name, endpoint, API key, token limits, and a description.

MUCGPT_CORE_MODELS='[
  {
    "type": "OPENAI",
    "llm_name": "<your-llm-name>",
    "endpoint": "<your-endpoint>",
    "api_key": "<your-sk>",
    "max_output_tokens": "<number>",
    "max_input_tokens": "<number>",
    "description": "<description>"
  }
]'

Field descriptions:

• type: The provider type (e.g., OPENAI).
• llm_name: The name or identifier of your LLM model.
• endpoint: The API endpoint URL for the model.
• api_key: The API key or secret for authentication.
• max_output_tokens: Maximum number of tokens the model can generate in a response.
• max_input_tokens: Maximum number of tokens accepted as input.
• description: A human-readable description of the model.

Replace the placeholder values with your actual model configuration.

🐋 Run with Docker

To start all required services using podman or docker run:

# in case of podman run
podman compose  --build up
# in case of docker run
docker-compose  --build up

This command launches the following components:

• Frontend: A modern web interface built with React, providing users with an intuitive and responsive experience directly in their browser.
• Core-Service: Manages the agent to call LLMs. Also orchestrates tool usage.
• Assistant-Service: Manages assistants. An assistant is a configuration for an MUCGPT agent.
• Assistant-Service-Migration: Does database migrations on startup.
• API Gateway: Serves as the unified entry point for all client requests, efficiently routing traffic to backend services while managing authentication and security.
• Keycloak: A robust, open-source identity and access management system responsible for authentication, authorization, and user administration.
• PostgresDB: A reliable PostgreSQL database used to securely store and manage app statistics.

Once all services are running, you can access:

• The frontend at localhost:8083 (Username: mucgpt-user, Password: mucgpt)
• The Keycloak admin panel at localhost:8100 (Username: admin, Password: admin)
• The PGAdmin panel at localhost:5050 (Username: admin, Password: admin)

Keycloak simulates a Single Sign-On (SSO) service, allowing you to log in to the frontend using the provided credentials (mucgpt-user / mucgpt).

🛤️ Roadmap

%%{init:
{
  "theme": "base",
  "themeVariables": {
      "primaryColor": "#F8B6B8",
      "primaryTextColor": "#222222",
      "primaryBorderColor": "#F6A6A6",
      "lineColor": "#FFE5B4",
      "secondaryColor": "#B6E2D3",
      "tertiaryColor": "#FFFFFF",
      "background": "#FFF8F0",
      "fontSize": "20px",
      "fontFamily": "Inter, Segoe UI, Trebuchet MS, Verdana, Arial, sans-serif"
  }
}
}%%
timeline
  title 🚀 MUCGPT Roadmap

  section 🎉 Open Source
    2024-06 : 🟢 Open Source : Public release for everyone!

  section 🖥️ UI & Experience
    2024-07 : 💾 Chat History : Save chats in your browser
    2024-08 : ⚙️ LLM Config : Tune the LLM to your needs
    2024-09 : 🗣️ Easy Language : Simplify any text

  section 🤖 Custom Assistants
    2025-01 : 🛠️ Build Assistants : Create your own helpers

  section 🌐 MUCGPT 2.0: Agent Mode
    2025-07 : 🧩 Microservices : API-Gateway, Core, Assistant-Service
    2025-07 : ☁️ Share Assistants : Share & use tools (Summarize, Brainstorm, Simple Language)
    2025-08 : 🔍 Websearch & Slides : Search the web, create presentations
    2025-09 : 🧠 Deep Research : Advanced research tools
    2025-10 : 📂 Knowledge Base : Assistants with their own KB & retrieval
    2025-12 : 🛡️ MCP Tools : Connect many MCP tools (e.g., DLF)

Loading

📃 Documentation

Architecture Overview

MUCGPT uses a modern microservices architecture optimized for scalability and maintainability:

• Frontend: User interface layer built with React
• API Gateway: Entry point for all client requests
• Core Service: LLM agent orchestration and tool integration
• Assistant Service: Configuration management for assistants
• PostgreSQL: Database for persistence
• Keycloak: Authentication and user management

The architecture of MUCGPT is structured into these primary components: the frontend, the core service for handling tools and the communication with the LLM, and the assistant service. Additionally, it features an API Gateway, a database, and integrates Single Sign-On (SSO) for authentication.

The frontend is based on a template from Microsoft Azure and is implemented using React, Typescript and Javascript.

The framework used to implement the backends (the core- and the assistant service) of MUCGPT is called FastAPI. It is a modern, fast (high-performance), web framework for building APIs with Python based on standard Python type hints. The core service uses LangGraph to connect to LLMs. Each service provides specialized functionality:

• Core Service: Manages LLM interactions and orchestrates tools. It uses LangGraph to create an agent architecture that can process user requests, call appropriate tools, and generate responses.

• Assistant Service: Manages the creation, modification, and sharing of assistant configurations. These configurations define which tools are available to an agent and what system prompts guide their behavior.

• Migration Service: Handles database migrations for the Assistant Service, ensuring schema updates are applied consistently.

The API Gateway is developed in Java based on the Spring Cloud Gateway, providing robust routing, security, and scalability for all services. IT@M distributes the gateway as a container image: ghcr.io/it-at-m/refarch/refarch-gateway. For detailed documentation, see the gateway documentation.

Authentication is managed using Keycloak, a robust open-source identity and access management solution. Keycloak handles user authentication, authorization, and user management for the MUCGPT platform, enabling secure Single Sign-On (SSO) across all services. For more details on customizing authentication or extending user management, refer to the Keycloak Migration Framework documentation.

Langfuse is an open-source LLM observability platform that supports agent tracing and prompt management. It is optional in MUCGPT.

For more information, see the MUCGPT Features documentation.

🖊️ Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please open an issue with the tag "enhancement", fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Open an issue with the tag "enhancement"
2. Fork the Project
3. Create your Feature Branch (git checkout -b feature/AmazingFeature)
4. Commit your Changes (git commit -m 'Add some AmazingFeature')
5. Push to the Branch (git push origin feature/AmazingFeature)
6. Open a Pull Request

More about this in the CODE_OF_CONDUCT file.

📝 License

Distributed under the MIT License. See LICENSE file for more information.

📬 Contact

it@M - [email protected]