Signal | Fieldstone

SIGNAL

TODAY

INTEL

SETUP

DOCS

ADMIN

CLIENTS

OPS

•

SALES

•

📖 DOCS NAVIGATION

🔍

📖 SecondBrain Docs

V2.5

Full reference documentation for the SecondBrain autonomous IT MSP intelligence platform.

1. System Overview

SecondBrain V2.5 — Autonomous IT MSP Intelligence

SecondBrain is an autonomous IT operations assistant built for Fieldstone, a dental IT MSP. It ingests emails, tracks tickets, detects patterns across clients, and surfaces intelligence to Scott (the operator) via a PM dashboard and Pilot (Discord bot).

Core Capabilities

📧

Email ingestion → ticket creation

IMAP, idempotent via Message-ID

📊

Signal scoring per ticket

readiness, trust, expectation, constraint, decision

🔍

Cross-client intelligence

outbreak detection, at-risk alerting

🧠

Node-based knowledge base

tool nodes, client nodes, living documentation

🤖

AI wrapper (sb_ai.py)

provider-agnostic, OAuth2 primary, API key fallback

🦾

Discord bot (Pilot)

14 commands for field operations

📋

PM Dashboard

tickets, signals, intel, setup, docs

2. Architecture

SecondBrain operates as a pipeline from raw email to actionable intelligence:

Email (IMAP)

Incoming client support emails

↓

ingest_emails_imap.py

Deduplication via Message-ID

↓

extract_and_store_entities()

cross_client_intel.py — writes to ticket_entities

↓

run_intel_cycle()

Outbreak detection + at-risk flagging

↓

second_brain.db (SQLite)

tickets · signals · tools · cross_client_events

↓

api.py (FastAPI :8100)

REST + OAuth endpoints

↓

fieldstoneFront (:3000)

/pm · /pm/intel · /pm/setup · /pm/docs

discord_bot.py (Pilot)

14 commands for field ops

3. Node-Based Knowledge Base

Nodes are entities — tools and clients — that store both static (manually written) and dynamic (auto-learned from tickets) knowledge. Every tool and client has a Markdown node file that grows richer over time as tickets are resolved.

Node Types

Type	Examples	Location
Tool Node	Eaglesoft, DEXIS, Carestream, Veeam	kb/nodes/tools/*.md
Client Node	Fieldstown Dental, Mountain Brook	kb/nodes/clients/*.md
Global SOPs	Field Tech Guidelines, Triage Playbooks	kb/*.md

Node Structure — Two Layers

Static Layer

Manually written. Known issues, vendor contacts, SOPs, integration notes. Preserved through every auto-regeneration cycle.

Dynamic Layer

Auto-generated below the sentinel marker. Learned from resolved tickets and outbreak history. Updated by closed_ticket_ingest.py on each run.

Sentinel Marker

<!-- SENTINEL: AUTO-GENERATED BELOW — DO NOT EDIT -->

Anything ABOVE this line is preserved through every regeneration.
Anything BELOW is overwritten by closed_ticket_ingest.py on each run.

Knowledge Flow

Ticket resolved → resolution_notes saved
       ↓
closed_ticket_ingest.py
       ↓
Extract: tool mentioned + fix applied
       ↓
Append to tool node dynamic layer (below sentinel)
       ↓
Next same issue → AI finds it → grounded answer

4. Cross-Client Intelligence

The intelligence layer detects when the same tool causes issues across multiple clients simultaneously — enabling proactive response before additional clients are affected.

How It Works

Every ticket ingested → AI extracts tool mentions → ticket_entities table

Correlation engine checks: N clients + same tool + time window

If threshold hit → cross-client event created with classification

At-risk clients identified (use same tool, no open ticket yet)

Pilot alerted, dashboard updated

Event Classifications

Classification	Trigger	Action
active_outbreak	2+ clients, same tool, 4hr window	Immediate Pilot alert
update_related	Monday morning pattern	Check vendor release notes
recurring	Same tool, 3rd+ occurrence in 90 days	Create permanent SOP
regional_outage	Multiple clients, same ISP	Check ISP status
vendor_triggered	Matches vendor update day	Contact vendor support

Tool Risk Score

Each tool gets a 0–100 risk score based on active ticket count across all clients using that tool.

>50 — HIGH25–50 — MEDIUM<25 — LOW

At-Risk Logic

Example: Outbreak detected for Eaglesoft → any client mapped to Eaglesoft in client_tools but with no open ticket is flagged as at-risk and surfaced in /api/intel/atrisk and the !atrisk Pilot command.

5. AI Wrapper (sb_ai.py)

sb_ai.py is a provider-agnostic AI layer that routes requests through a priority chain, handles response caching, and tracks token usage and costs.

Provider Priority Chain

Priority	Provider	When Active
🥇 PRIMARY	OAuth2 Bearer token	AI_OAUTH_PROVIDER env var is set
🥈 SECONDARY	Direct API key (OpenAI / Anthropic / Ollama)	OAuth not configured
🥉 TERTIARY	Fallback URL	AI_FALLBACK_URL is set

Available Functions

ask(prompt, task_type='fast')        # General purpose
summarize(text, max_words=30)        # Summarize email / ticket
classify(text, categories)           # Classify ticket type
draft_reply(title, notes, client)    # Draft client response
analyze_signal(signal_dict)          # AI signal commentary
query_kb(question, kb_text)          # KB-grounded Q&A

Model Routing

task_type='fast'

Routes to AI_FAST_MODEL
Used for classification, summarization, signal extraction

task_type='strong'

Routes to AI_STRONG_MODEL
Used for KB Q&A, draft replies, deep analysis

OAuth2 Providers

google (Vertex AI)azure (Azure OpenAI)openaicustom

Features

✓

SQLite response caching with configurable TTL

✓

Per-call token and cost tracking stored in ai_usage table

✓

Daily budget guard with configurable spend cap

✓

Automatic token refresh with 60s expiry buffer

✓

Graceful fallback chain — never crashes on provider failure

6. Pilot Discord Commands

Pilot is the Discord bot interface for field operations. All 14 commands are available from any Discord channel the bot has access to.

Command	Description
`!ingest`	Trigger email ingestion manually
`!brief <client>`	Generate and email prep brief for client
`!signals`	Show all client signal scores
`!calendar`	Show upcoming appointments
`!summary`	Daily summary of open tickets
`!ticket <id>`	Show full ticket details
`!note <id> <text>`	Add note to ticket + append to resolution_notes
`!digest`	Send daily digest email
`!reset`	Reset conversation context
`!help`	Show all commands
`!tool <tool_id>`	Show tool node: risk score, clients, known issues
`!outbreak`	Show all active cross-client outbreaks
`!atrisk`	List all at-risk clients
`!clients <tool_id>`	List all clients using a tool

7. Signal Model

Every ticket has 5 signal dimensions scored automatically by AI during ingestion. Signals evolve as new emails arrive on the ticket thread.

Signal	Values	Meaning
`readiness_signal`	🟢 HIGH / 🟡 MEDIUM / 🔴 LOW	Client's operational urgency
`trust_signal`	📈 RISING / ➡️ NEUTRAL / 📉 DECLINING	Relationship health trajectory
`expectation_signal`	Free text (captured)	Client's stated expectation
`constraint_signal`	Free text (captured)	Time / resource constraints
`decision_signal`	Free text (captured)	Pending decisions required

Numeric Scores

readiness_score

0 – 100

Numeric form of readiness_signal

trust_score

0 – 100

Numeric form of trust_signal

Composite

Weighted average

Shown in PM dashboard ticket cards

8. API Reference

All endpoints served by api.py on port 8100.

Tickets

Method	Endpoint	Description
GET	`/api/tickets`	All tickets
GET	`/api/tickets/{key}`	Single ticket by key
GET	`/api/signals`	All signal scores

Intelligence

Method	Endpoint	Description
GET	`/api/intel/outbreaks`	Active outbreaks {events:[], count:0}
GET	`/api/intel/atrisk`	At-risk clients {at_risk:[], count:0}
POST	`/api/intel/run`	Trigger intel cycle manually
GET	`/api/intel/tool/{id}/score`	Tool risk score (0-100)

Nodes / Tools

Method	Endpoint	Description
GET	`/api/nodes/tools`	All tools {tools:[...]}
GET	`/api/nodes/tools/{id}`	Tool detail + KB markdown

Settings

Method	Endpoint	Description
GET	`/api/settings`	All settings (sensitive fields masked)
POST	`/api/settings`	Save settings to .env
POST	`/api/settings/test/ai`	Test AI connection
POST	`/api/settings/test/email`	Test email / IMAP connection
GET	`/api/settings/ai/usage`	AI token / cost stats

OAuth

Method	Endpoint	Description
GET	`/api/oauth/initiate?provider=X`	Start OAuth flow → redirect to provider
GET	`/api/oauth/callback`	OAuth callback handler
GET	`/api/oauth/status?provider=X`	Poll for OAuth completion

9. Setup Guide

Follow these steps in order to get SecondBrain fully operational:

Configure Email (IMAP)

Go to /pm/setup → Email / IMAP section. Enter IMAP host, port, username, and password.

Set AI Provider

AI Configuration section → Set API Base URL, API Key, fast model ID, and strong model ID.

Configure OAuth (Optional)

AI OAuth 2.0 section → Select provider (Google / Azure / OpenAI / custom) → click Connect.

Set Discord Token

Discord section → Paste bot token. Ensure Pilot has message + read permissions in your server.

Set GitHub Token

GitHub section → Personal access token for KB sync (if using a GitHub-hosted knowledge base).

Test Connections

Use the Test buttons for AI and Email to verify configuration before saving.

Save All Settings

Click Save All Settings. Changes are written to .env immediately.

Restart API

Apply config changes by restarting the API server:

pkill uvicorn && uvicorn api:app --host 0.0.0.0 --port 8100

10. Database Schema

SecondBrain uses a single SQLite file at second_brain/second_brain.db. Below are all key tables with column definitions.

tickets

Core ticket table

Column	Type	Notes
`id`	INTEGER	PRIMARY KEY autoincrement
`ticket_key`	TEXT	Unique key e.g. TK-2024-001
`title`	TEXT	Ticket subject
`status`	TEXT	open \| in_progress \| closed
`priority`	TEXT	high \| medium \| low
`client_key`	TEXT	FK → client identifier
`created_at`	TEXT	ISO timestamp
`closed_at`	TEXT	ISO timestamp or NULL
`resolution_notes`	TEXT	Free text resolution
`readiness_signal`	TEXT	HIGH \| MEDIUM \| LOW
`trust_signal`	TEXT	RISING \| NEUTRAL \| DECLINING
`readiness_score`	INTEGER	0–100
`trust_score`	INTEGER	0–100
`lifecycle_status`	TEXT	active \| archived

tools

Software tools in the MSP fleet

Column	Type	Notes
`id`	TEXT	Slug e.g. eaglesoft
`name`	TEXT	Display name
`vendor`	TEXT	Vendor company
`category`	TEXT	pms \| imaging \| backup \| network
`vendor_support_url`	TEXT	Support portal URL
`known_issues`	TEXT	Freetext known issues
`update_sensitivity`	TEXT	high \| medium \| low

client_tools

Maps which tools each client uses

Column	Type	Notes
`client_id`	TEXT	FK → client
`tool_id`	TEXT	FK → tools.id
`version`	TEXT	Installed version
`install_notes`	TEXT	Optional notes

ticket_entities

AI/keyword extracted tool mentions per ticket

Column	Type	Notes
`ticket_key`	TEXT	FK → tickets.ticket_key
`client_id`	TEXT	Extracted client
`tool_id`	TEXT	Extracted tool
`confidence`	REAL	0.0–1.0
`extraction_method`	TEXT	keyword \| ai
`created_at`	TEXT	ISO timestamp

cross_client_events

Detected outbreak and correlation events

Column	Type	Notes
`id`	INTEGER	PRIMARY KEY
`tool_id`	TEXT	Affected tool
`detected_at`	TEXT	ISO timestamp
`affected_clients`	TEXT	JSON array of client IDs
`at_risk_clients`	TEXT	JSON array of at-risk IDs
`classification`	TEXT	active_outbreak \| update_related \| recurring \| ...
`root_cause`	TEXT	AI-generated root cause
`status`	TEXT	open \| resolved
`resolution_notes`	TEXT	How it was resolved

ai_usage

AI token and cost tracking per call

Column	Type	Notes
`id`	INTEGER	PRIMARY KEY
`model`	TEXT	Model identifier
`tokens_used`	INTEGER	Total tokens
`cost_usd`	REAL	Estimated cost
`created_at`	TEXT	ISO timestamp

SecondBrain V2.5 — Fieldstone Dental IT MSP Platform