feat: Implement Airth microservice with health check and mock query handling; add ThoughtMap Phase 2 module with AI expansion functionality

Author: Elidorascodex

README_ARCHITECTURE.md

@@ -0,0 +1,52 @@
+# TEC Architecture Blueprint (Operational Extraction)
+
+This document distills the strategic blueprint into actionable implementation layers.
+
+## Stack Selections (Locked-In)
+- Core DB: PostgreSQL 15 (Flexible Server) + pgvector extension
+- ORM: Prisma (schema-first constitutional data model)
+- Vector Retrieval: pgvector (phase 1) – Azure AI Search retained for future hybrid augment
+- Agent Framework: LangChain (incremental; mock in Airth for now)
+- Microservices: Container Apps per agent (Airth first)
+- Realtime: Socket.IO (pending integration after Airth live RAG)
+- Frontend: Vite + React + Zustand + Chakra (scaffold next phase)
+- Secrets: Key Vault + Managed Identity (migration upcoming)
+
+## Data Model (Initial)
+See `prisma/schema.prisma`. Entities: LoreEntry, LoreVersion, Embedding, AgentMemory, Relation, TaskLog.
+
+## Airth Service (Phase 1)
+- Location: `services/airth/`
+- Endpoints:
+  - GET `/healthz` – health probe
+  - POST `/ask` – mock answer until embeddings pipeline connected
+- Upcoming: similarity retrieval + answer synthesis.
+
+## pgvector Enablement
+Run once against DB:
+```
+psql "$DATABASE_URL" -f scripts/enable_pgvector.sql
+```
+
+## Upcoming Work (Ordered)
+1. Embedding pipeline script (generate + store vectors)
+2. Replace Airth mock with LangChain RAG chain
+3. Frontend scaffold + Ask Airth interface
+4. Key Vault secret retrieval refactor
+5. ThoughtMap ingestion endpoint -> lore entries + embeddings
+6. Observability: correlation IDs, structured logs
+
+## Testing Strategy
+- CI: prisma format + migrate diff validation
+- Unit: Airth /healthz, expansion stubs
+- Integration (later): ephemeral Postgres + vector similarity test
+
+## Principle Mapping
+| Principle | Implementation Hook |
+|-----------|---------------------|
+| Narrative Supremacy | Canonical version pointer in LoreEntry |
+| Transparency Mandate | Prisma schema under Git + migrations |
+| Generational Responsibility | Append-only LoreVersion + audit |
+
+## Contribution Notes
+Schema changes: modify -> `npm run prisma:format` -> `npm run prisma:migrate` -> commit. Avoid manual DB drift.

SESSION_HANDOFF.md

@@ -15,19 +15,19 @@ The Guardian’s Burden anchors moral axis; Order of the Fuck-Up Fathers supplie
 | Repo Size | ⚠️ ~764MB | History bloat unresolved |
 | Sovereign Assets | Partial | Indexed, not fully cross-linked |
 
-## Decision Log (Pending)
-1. Nuclear history purge: DEFERRED (needs explicit go/no-go)
-2. Phase 2 priority: ThoughtMap AI expansion vs deeper MCP enrichment – NOT CHOSEN
-3. Local model (Ollama) vs remote API (Azure OpenAI) – NOT CHOSEN
+## Decision Log (Pending / Executed)
+1. Nuclear history purge: APPROVED (user confirmed) – NOT YET EXECUTED (awaiting final safety confirmation)
+2. Phase 2 priority: Proceed with ThoughtMap AI expansion first, then MCP enrichment
+3. Local model vs remote API: DEFER – stub stays deterministic until architecture choice
 
 ## Next Task Checklist
-- [ ] Decide purge now vs later (record in this file under Decisions Executed)
-- [ ] Implement ThoughtMap Phase 2 AI expansion (expand_node, synthesize_branch)
-- [ ] Wire Ctrl+Space hotkey to expansion
-- [ ] Persist save format version bump (add `schemaVersion: 2`)
-- [ ] MCP adapter: export node graph to Memory Core ingestion stub
-- [ ] Pre-commit large file guard (>10MB unless LFS tracked)
-- [ ] Lightweight Jest smoke test for TS utils + Python self-test
+- [x] Decide purge now vs later (recorded APPROVED, execution pending)
+- [x] Implement ThoughtMap Phase 2 AI expansion stubs (Python module extraction pending commit)
+- [ ] Wire Ctrl+Space hotkey to expansion (pending module extraction)
+- [ ] Persist save format version bump (schemaVersion: 2 in new save routine)
+- [ ] MCP adapter: connect to real graph instead of dummy
+- [x] Pre-commit large file guard (>10MB unless LFS tracked)
+- [ ] Lightweight Jest smoke test + Python self-test script
 
 ## Interfaces Planned
 ### Python Expansion Stub
@@ -48,11 +48,11 @@ Returns list of plausible child node titles (mock until model configured).
 | Model hallucination in expansion | Keep stub deterministic until validation layer added |
 
 ## Suggested Order of Operations (If Continuing Immediately)
-1. Commit this handoff file
-2. Implement stubs (done partially in repo once committed)
-3. Choose purge strategy; if YES, perform after verifying new stubs committed
-4. Integrate expansion UI + persistence version bump
-5. Add tests + hook install script
+1. Extract ThoughtMap notebook code into module + hotkey
+2. Execute nuclear purge (after commit) OR postpone
+3. Replace MCP adapter dummy with live exporter
+4. Add synthesis UI action (branch summary)
+5. Decide model integration path (Azure vs local) and implement
 
 ## Handoff Prompt (For New Chat Seed)
 ```

infra/main.bicep

@@ -41,6 +41,7 @@ var tags = {
 
 var resourceNames = {
   containerApp: '${applicationName}-app-${resourceToken}'
+  airthContainerApp: '${applicationName}-airth-${resourceToken}'
   containerAppsEnvironment: '${applicationName}-env-${resourceToken}'
   containerRegistry: 'tecregistry${resourceToken}'
   keyVault: '${applicationName}-kv-${resourceToken}'
@@ -351,6 +352,91 @@ resource containerApp 'Microsoft.App/containerApps@2023-05-01' = {
   }
 }
 
+// Airth Agent Container App
+resource airthContainerApp 'Microsoft.App/containerApps@2023-05-01' = {
+  name: resourceNames.airthContainerApp
+  location: location
+  tags: tags
+  identity: {
+    type: 'UserAssigned'
+    userAssignedIdentities: {
+      '${managedIdentity.id}': {}
+    }
+  }
+  properties: {
+    managedEnvironmentId: containerAppsEnvironment.id
+    configuration: {
+      ingress: {
+        external: true
+        targetPort: 8000
+        allowInsecure: false
+        traffic: [
+          {
+            weight: 100
+            latestRevision: true
+          }
+        ]
+      }
+      registries: [
+        {
+          server: containerRegistry.properties.loginServer
+          identity: managedIdentity.id
+        }
+      ]
+      secrets: [
+        {
+          name: 'openai-api-key'
+          value: openAiApiKey
+        }
+        {
+          name: 'db-connection-string'
+          value: 'postgresql://${dbAdminUsername}:${dbAdminPassword}@${postgreSQL.properties.fullyQualifiedDomainName}:5432/tecdb'
+        }
+      ]
+    }
+    template: {
+      containers: [
+        {
+          image: '${containerRegistry.properties.loginServer}/elidoras-airth:${containerImageTag}'
+          name: 'airth'
+          resources: {
+            cpu: json(environmentName == 'prod' ? '0.75' : '0.5')
+            memory: environmentName == 'prod' ? '1.5Gi' : '1Gi'
+          }
+          env: [
+            {
+              name: 'PORT'
+              value: '8000'
+            }
+            {
+              name: 'OPENAI_API_KEY'
+              secretRef: 'openai-api-key'
+            }
+            {
+              name: 'DATABASE_URL'
+              secretRef: 'db-connection-string'
+            }
+          ]
+        }
+      ]
+      scale: {
+        minReplicas: environmentName == 'prod' ? 2 : 1
+        maxReplicas: environmentName == 'prod' ? 5 : 2
+        rules: [
+          {
+            name: 'http-scaler'
+            http: {
+              metadata: {
+                concurrentRequests: '80'
+              }
+            }
+          }
+        ]
+      }
+    }
+  }
+}
+
 // Role Assignments
 resource acrPullRole 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
   scope: containerRegistry
@@ -385,6 +471,7 @@ resource keyVaultSecretsRole 'Microsoft.Authorization/roleAssignments@2022-04-01
 // Outputs
 output containerAppFQDN string = containerApp.properties.configuration.ingress.fqdn
 output containerAppUrl string = 'https://${containerApp.properties.configuration.ingress.fqdn}'
+output airthAppUrl string = 'https://${airthContainerApp.properties.configuration.ingress.fqdn}'
 output keyVaultName string = keyVault.name
 output storageAccountName string = storageAccount.name
 output postgreSQLHostname string = postgreSQL.properties.fullyQualifiedDomainName

package.json

@@ -9,14 +9,19 @@
     "build": "tsc",
     "start": "node dist/server.js",
     "start:prod": "npm run build && npm start",
-  "test": "jest",
-  "test:smoke": "echo 'placeholder smoke test'",
+    "test": "jest",
+    "test:smoke": "echo 'placeholder smoke test'",
+    "thoughtmap:run": "python tec_mcp_server/thoughtmap.py",
+    "py:selftest": "python tec_mcp_server/self_test.py",
     "lint": "eslint src/**/*.ts",
-  "format": "prettier --write src/**/*.{ts,tsx}",
-  "hooks:refresh": "chmod +x .git/hooks/pre-commit tools/precommit/large-file-guard.sh",
+    "format": "prettier --write src/**/*.{ts,tsx}",
+    "hooks:refresh": "chmod +x .git/hooks/pre-commit tools/precommit/large-file-guard.sh",
     "axiom:validate": "ts-node src/scripts/validateAxioms.ts",
     "db:migrate": "ts-node src/server/database/migrate.ts",
-    "db:seed": "ts-node src/server/database/seed.ts"
+    "db:seed": "ts-node src/server/database/seed.ts",
+    "prisma:generate": "prisma generate",
+    "prisma:migrate": "prisma migrate dev --name init",
+    "prisma:format": "prisma format"
   },
   "keywords": [
     "ai",
@@ -30,8 +35,7 @@
   "license": "GPL-3.0",
   "dependencies": {
     "@azure/openai": "^1.0.0-beta.12",
-    "@types/bcrypt": "^5.0.2",
-    "@types/jsonwebtoken": "^9.0.6",
+    "@prisma/client": "^5.16.1",
     "bcrypt": "^5.1.1",
     "cors": "^2.8.5",
     "dotenv": "^16.4.5",
@@ -60,6 +64,7 @@
     "jest": "^29.7.0",
     "nodemon": "^3.1.0",
     "prettier": "^3.2.5",
+    "prisma": "^5.16.1",
     "ts-jest": "^29.1.2",
     "ts-node": "^10.9.2",
     "typescript": "^5.4.5"

prisma/schema.prisma

@@ -0,0 +1,74 @@
+// Prisma schema – Master Lore Database (Phase 1)
+// Acts as constitutional data layer. pgvector extension required.
+
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+model LoreEntry {
+  id                 String       @id @default(cuid())
+  slug               String       @unique
+  title              String
+  type               String
+  canonicalVersionId String?      @map("canonical_version_id")
+  createdAt          DateTime     @default(now()) @map("created_at")
+  versions           LoreVersion[]
+  embeddings         Embedding[]
+  memories           AgentMemory[] @relation("LoreMemory")
+  relationsFrom      Relation[]   @relation("FromRelations")
+  relationsTo        Relation[]   @relation("ToRelations")
+}
+
+model LoreVersion {
+  id          String    @id @default(cuid())
+  loreEntry   LoreEntry @relation(fields: [loreEntryId], references: [id])
+  loreEntryId String    @map("lore_entry_id")
+  content     String
+  author      String?
+  hash        String    @unique
+  createdAt   DateTime  @default(now()) @map("created_at")
+}
+
+model Embedding {
+  id          String    @id @default(cuid())
+  loreEntry   LoreEntry @relation(fields: [loreEntryId], references: [id])
+  loreEntryId String    @map("lore_entry_id")
+  vector      Unsupported("vector")
+  model       String
+  dim         Int
+  createdAt   DateTime @default(now()) @map("created_at")
+}
+
+model AgentMemory {
+  id          String     @id @default(cuid())
+  agent       String
+  content     String
+  importance  Float      @default(0)
+  loreEntry   LoreEntry? @relation("LoreMemory", fields: [loreEntryId], references: [id])
+  loreEntryId String?    @map("lore_entry_id")
+  createdAt   DateTime   @default(now()) @map("created_at")
+}
+
+model Relation {
+  id        String    @id @default(cuid())
+  from      LoreEntry @relation("FromRelations", fields: [fromId], references: [id])
+  fromId    String    @map("from_id")
+  to        LoreEntry @relation("ToRelations", fields: [toId], references: [id])
+  toId      String    @map("to_id")
+  kind      String
+  createdAt DateTime  @default(now()) @map("created_at")
+}
+
+model TaskLog {
+  id        String   @id @default(cuid())
+  agent     String
+  input     String
+  outputRef String?  @map("output_ref")
+  status    String   @default("pending")
+  createdAt DateTime @default(now()) @map("created_at")
+}

scripts/enable_pgvector.sql

@@ -0,0 +1,2 @@
+-- Enable pgvector extension (idempotent)
+CREATE EXTENSION IF NOT EXISTS vector;

services/airth/airth_service.py

@@ -0,0 +1,34 @@
+"""Airth Microservice (Phase 1 Skeleton)
+
+FastAPI service providing /healthz and /ask endpoints.
+RAG pipeline placeholder – returns deterministic mock until embeddings pipeline active.
+"""
+from __future__ import annotations
+from fastapi import FastAPI
+from pydantic import BaseModel
+import hashlib
+
+app = FastAPI(title="Airth Service", version="0.1.0")
+
+class AskRequest(BaseModel):
+  query: str
+  max_context: int | None = 5
+
+class AskResponse(BaseModel):
+  answer: str
+  sources: list[str]
+  strategy: str = "mock"
+
+@app.get("/healthz")
+def health():  # liveness/readiness simple variant
+  return {"status": "ok"}
+
+@app.post("/ask", response_model=AskResponse)
+def ask(req: AskRequest):
+  h = hashlib.sha256(req.query.encode()).hexdigest()[:8]
+  answer = f"[Airth mock] Hash:{h} – query acknowledged. RAG pipeline pending."
+  return AskResponse(answer=answer, sources=["lore:placeholder"], strategy="mock")
+
+if __name__ == "__main__":  # pragma: no cover
+  import uvicorn
+  uvicorn.run(app, host="0.0.0.0", port=8000)

services/airth/requirements.txt

@@ -0,0 +1,6 @@
+fastapi==0.111.0
+uvicorn==0.30.1
+langchain==0.2.7
+psycopg[binary]==3.1.19
+openai==1.35.0
+python-dotenv==1.0.1

tec_mcp_server/self_test.py

@@ -0,0 +1,22 @@
+"""Quick self-test to ensure critical modules import."""
+from importlib import import_module
+
+MODULES = [
+    'tec_mcp_server.ai_expander',
+    'tec_mcp_server.thoughtmap'
+]
+
+def main():
+    failed = []
+    for m in MODULES:
+        try:
+            import_module(m)
+        except Exception as e:  # pragma: no cover
+            failed.append((m, repr(e)))
+    if failed:
+        print("FAIL", failed)
+        raise SystemExit(1)
+    print("OK modules loaded")
+
+if __name__ == '__main__':
+    main()