darkglass 1.4.0

Structured AI system with emebeddable chatbot

Darkglass

Darkglass is a lightweight, embeddable chatbot designed for small colleges, providing prospective students with automated responses while logging interactions for administrative review.

Demo

Design

The system is built on a minimalist architecture, utilizing FastAPI and SQLite to provide zero-configuration deployment on lightweight Linux VMs without the overhead of external databases.

Configuration

Add a [gemini] section with your API key and optional model (defaults to gemini-3.1-flash-lite-preview):

[gemini]
api_key = "mysecretkey"
model = "gemini-3.1-flash-lite-preview"

You can also include a [context] section to provide a default prompt for the agent:

[context]
prompt = "You are a helpful agent for Acme College."

To enable a secure administrative dashboard, add a [google] section with a client_id to use for authentication.

[google]
client_id = "your-google-client-id.apps.googleusercontent.com"

To restrict dashboard access to specific addresses, add a [roles] section with an admins list. When admins is non-empty, only addresses listed will be allowed access.

[roles]
admins = ["[e-mail]", "[e-mail]"]

Usage

1. Set API keys, system prompt, and authorized users in darkglass.toml
2. Run uvx darkglass or pipx run darkglass to launch production server
3. Use the demo page to test the config: http://localhost:8000/static/demo.html
4. Update reverse proxy configs as required to route requests to darkglass.
5. Add the following snippet to your site, replacing the URL based on your chosen production endpoint:

<script src="https://darkglass.example.com/static/webchat.js"></script>

Demo Snippet

For quick demo purposes, the following snippet can be pasted into browser dev tools on any page to add a chat interface against a server running on localhost:

let darkglass = document.createElement('script')
darkglass.src = 'http://localhost:8000/static/webchat.js'
darkglass.defer = true
document.body.appendChild(darkglass)

Mock Data

For demonstration purposes, the interface will correctly respond to the following queries even with no LLM API keys configured:

• "What is 1+1?"
• "What is the capital of France?"