A memory-aware, low-noise social agent for QQ group chats.
Candela does not rush to answer every message. It first interprets emotion, social context, and interruption risk, then chooses whether to stay silent, acknowledge, comfort, clarify, or help solve the problem. Each intervention is subsequently evaluated for its actual effect.
English | 简体中文
Quick start · System design · Web Console · Operations · Technical report
Web Console overview rendered with synthetic data. No real conversations, QQ identifiers, or deployment details are shown.
Conventional chatbots often treat receiving a message and replying to it as the same event. In group conversations, that behavior leads to interruptions, repeated explanations, tonal mismatch, and unnecessary noise. Candela places generation behind an observable social decision pipeline:
- Perceive before acting: Prism interprets emotion and needs; Lens estimates conversational roles, reply expectations, and interruption risk.
- Silence is an action: Dimmer scores nine candidate actions and only invokes generation after the reply threshold is crossed.
- Memory has provenance and scope: Aura and Loom assemble profiles, group memory, and current context without indiscriminately accumulating history.
- Generated text is still reviewed: Shade checks action fidelity, tone, and safety boundaries, requesting a rewrite when necessary.
- Every intervention is traceable: Intervention records what happened; Trace observes the subsequent window and produces effectiveness, attribution, and tuning proposals.
- Operations remain governable: Web Console supports message retrieval, emotion projection, policy tuning, prompt editing, permissions, and audit trails.
Candela is a self-hosted research beta intended for authorized QQ group deployments. It is not a general-purpose task executor: chat messages cannot trigger arbitrary code, file operations, or external tools.
flowchart LR
A["QQ / OneBot v11"] --> B["Event normalization"]
B --> C["Message and media persistence"]
C --> D["Prism\nEmotion and needs"]
C --> E["Lens\nSocial context"]
D --> F["Aura + Loom\nProfiles and memory"]
E --> F
F --> G["Dimmer\nAction decision"]
G -->|Silence| H["Intervention\nBehavior record"]
G -->|Reply| I["Glow + Shade\nGeneration and review"]
I --> H
H --> J["Trace\nEffect and attribution"]
C --> K["Console Sync"]
D --> K
E --> K
G --> K
J --> K
K --> L["Web Console"]
| Module | Responsibility | Primary output |
|---|---|---|
| Prism | Analyzes emotion, interaction needs, and confidence | 11-dimensional emotion, 8-dimensional needs, dominant labels |
| Lens | Infers dialogue mode, social action, closeness, and interruption risk | social act, bot role, reply expectation |
| Aura | Maintains structured profiles from explicit statements and stable signals | profile items with provenance, scope, and sensitivity |
| Loom | Builds compact context from messages, profiles, and memory | a response-specific memory pack |
| Dimmer | Combines perception, profiles, session state, and policy parameters | action, focus, style, avoid list, candidate scores |
| Glow | Generates natural responses under Dimmer constraints | response text and segmented output |
| Shade | Reviews tone, action fidelity, and boundaries | accept, reject, or rewrite recommendation |
| Trace | Evaluates execution, social, and acceptance outcomes | effectiveness, blame target, tuning proposal |
| Atlas | Projects high-dimensional emotion into two-dimensional semantic space | point cloud, trajectory, centroid, and baseline |
These modules are more than labels embedded in prompts. Perception, decisions, candidate scores, interventions, and outcomes all have structured models and persistent records that can be queried, joined, and audited.
The unified console runs at http://127.0.0.1:8080/ by default and provides:
- runtime overview, group message volume, action distribution, and high-risk contexts;
- combined message search by keyword, time, user, Prism, Lens, and other fields;
- Prism emotion/need statistics and Atlas two-dimensional emotion projection;
- Intervention execution, feedback recording, and Trace attribution tracking;
- group, member, policy parameter, and tuning proposal management;
- live prompt editing with placeholder validation, version retention, and default restoration;
- member, group administrator, and system administrator roles;
- auditing for authentication, administrative writes, and manual interventions.
Unauthenticated visitors can only access the overview and sign-in page. Accounts are enabled by a system administrator; members synchronized from group conversations do not receive a console password and cannot sign in by default.
- Python 3.10 or later;
- an OpenAI-compatible Chat Completions endpoint;
- a OneBot v11 implementation such as NapCat or Lagrange;
- a test group that has explicitly authorized Candela to process its messages.
Vision is optional. Prism, Lens, Trace, and memory maintenance can use separate models and credentials; when they are not configured, the system enters an observable fallback path.
git clone https://github.com/ZilaiWang/candela.git
cd candela
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
cp .env.example .envEdit .env:
# OpenAI-compatible primary model
CANDELA_LLM_BASE_URL=https://your-provider.example/v1
CANDELA_LLM_API_KEY=replace-me
CANDELA_LLM_MODEL=your-chat-model
# OneBot v11
CANDELA_ONEBOT_API_BASE=http://127.0.0.1:3000
CANDELA_ONEBOT_ACCESS_TOKEN=replace-with-your-onebot-token
CANDELA_ONEBOT_EVENT_TOKEN=replace-with-your-onebot-token
CANDELA_ONEBOT_BOT_QQ=your-bot-id
CANDELA_BETA_GROUP_IDS=comma-separated-authorized-group-ids
# Web Console
CANDELA_CONSOLE_SESSION_SECRET=replace-with-at-least-32-random-characters
CANDELA_CONSOLE_BOOTSTRAP_ACCOUNT=your-admin-account
CANDELA_CONSOLE_BOOTSTRAP_PASSWORD=replace-with-a-strong-password
CANDELA_RUNTIME_API_TOKEN=replace-with-a-long-random-tokenGenerate random secrets with:
python -c 'import secrets; print(secrets.token_urlsafe(48))'After the first administrator account has been created and successfully signed in, remove both CANDELA_CONSOLE_BOOTSTRAP_* variables from .env. Bootstrap variables never overwrite the password or role of an existing account.
# Local interactive check
candela
# OneBot event service, Web Console, and background maintenance
candela-onebotThe repository scripts can also manage a single-process deployment:
./scripts/start_bot.sh
./scripts/status_bot.sh
./scripts/restart_bot.sh
./scripts/stop_bot.sh- Set the OneBot event callback to
http://<candela-host>:8765/onebot/event. - Point
CANDELA_ONEBOT_API_BASEto the OneBot HTTP Action endpoint. - Configure the same access token on both sides.
- Add only explicitly authorized groups to
CANDELA_BETA_GROUP_IDS.
| Default endpoint | Purpose | Recommended exposure |
|---|---|---|
POST :8765/onebot/event |
OneBot event ingress | OneBot source only |
GET :8765/health |
Messaging service health check | Localhost or monitoring network |
GET :8080/ |
Web Console | Behind an HTTPS reverse proxy |
GET :8080/runtime/docs |
Runtime API documentation | Administrative network |
GET :8799/admin/status |
Process management status | Localhost only |
Production deployments should terminate HTTPS at a reverse proxy and restrict network access to OneBot Action, event ingress, and local administration ports. See Deployment and maintenance for the complete procedure.
| Configuration group | Representative variables | Purpose |
|---|---|---|
| Primary generation | CANDELA_LLM_* |
Glow response generation and general fallback |
| Dedicated perception | CANDELA_PRISM_*, CANDELA_LENS_* |
Emotion and social judges |
| Reflection and memory | CANDELA_TRACE_*, CANDELA_MEMORY_MAINTENANCE_* |
Asynchronous outcome evaluation and memory maintenance |
| Group policy | CANDELA_BETA_GROUP_IDS, CANDELA_REQUIRE_MENTION |
Enabled scope, mention rules, and cooldown policy |
| OneBot | CANDELA_ONEBOT_* |
Event authentication, action endpoint, and bot identity |
| Console | CANDELA_CONSOLE_*, CANDELA_RUNTIME_API_TOKEN |
Query store, sessions, synchronization, and API authentication |
All supported variables and secure defaults are documented in .env.example. Never commit a populated .env file.
Candela uses the same SQLite/WAL engine for two local databases with distinct responsibilities:
data/candela.sqlite3 Runtime facts: messages, perception, memory, decisions, interventions, Trace
data/candela_console.sqlite3 Query model: joined search, accounts, policy, permissions, audit
data/prompt_overrides.json Runtime prompt revisions saved by Web Console
data/backups/ Consistent database backups
The runtime database prioritizes write latency along the message path. A read-only incremental synchronizer builds the console's relational model with foreign keys, check constraints, and query indexes. Synchronization failures do not block message ingestion, and the synchronization path never mutates runtime facts.
The public repository ignores data/, databases, logs, backups, .env, and runtime prompt overrides by default. Obtain participant authorization before processing real conversations, and establish access, export, deletion, and retention procedures that comply with applicable law and platform rules.
System administrators can inspect module prompts, required placeholders, and active sources at /prompts. Saved overrides are written to data/prompt_overrides.json and take effect on the next model call without a restart. Code-defined defaults remain available for restoration at any time.
Override files may contain deployment policy and operator information, so they are excluded from the public repository. prompts/overrides.example.json demonstrates the secret-free data structure only.
candela/
├── candela/
│ ├── engine.py # Message lifecycle and module orchestration
│ ├── memory.py # Runtime facts, memory, and profile storage
│ ├── prism/ # Emotion and need perception
│ ├── lens/ # Social-context perception
│ ├── dimmer/ # Action scoring and response instructions
│ ├── aura/ # Structured profiles and learning signals
│ ├── loom/ # Memory-pack assembly
│ ├── shade/ # Response quality review
│ ├── trace/ # Intervention outcome evaluation
│ ├── atlas/ # Emotion geometry and projection configuration
│ ├── adapters/ # CLI, OneBot HTTP, and NoneBot adapters
│ └── web/console/ # Web Console, synchronizer, and static assets
├── assets/ # Public documentation images
├── prompts/ # Persona files and prompt override example
├── reports/techreport/ # Complete LaTeX technical report
├── scripts/ # Lifecycle, backup, and Trace backfill scripts
└── tests/ # Core, permission, API, and sync regression tests
python -m pip install -e ".[dev]"
ruff check candela scripts tests bot.py
ruff format --check candela scripts tests bot.py
python -m compileall -q candela scripts tests bot.py
pytest -q
bash -n scripts/*.sh
python -m buildGitHub Actions applies the same quality gates on Python 3.10 and 3.12. Historical Trace backfill supports read-only preview, batch limits, and concurrency control:
python scripts/backfill_trace.py --dry-run
python scripts/backfill_trace.py --workers 4 --batch-size 100 --limit 500The script processes only interventions without outcomes. Successful results are protected by a unique constraint, while failed items can be retried in later runs.
- v1.4.0 is the first public beta. Real-world social outcomes still require authorized replay evaluation and human sampling.
- Due Trace tasks are currently checked when later messages arrive; there is no independent persistent scheduler yet.
- OneBot implementations differ in their support for forwarded bundles, expired media, and file uploads.
- Console targets controlled, single-instance deployments and is not a multi-tenant SaaS application suitable for direct public exposure.
- Model output can be wrong. Candela's perception, review, and reflection layers reduce risk but do not guarantee correctness.
- Technical report: architecture, contracts, formulas, data model, interfaces, and operating boundaries.
- Deployment and maintenance: first deployment, systemd, backups, upgrades, recovery, and troubleshooting.
- Contributing guide: development environment, change boundaries, and verification requirements.
- Security policy: vulnerability reporting and public deployment considerations.
- Changelog: behavior changes and migration notes for public releases.
Reproducible bug reports are welcome through Issues, and focused improvements with verification results are welcome through Pull Requests. For security issues, use GitHub Private Vulnerability Reporting. Do not disclose credentials, real chat records, or exploitable details in public Issues.
Candela is released under the MIT License.