Skip to content

AGENTS.md

Latest commit

 

History

History
246 lines (224 loc) · 20.3 KB

AGENTS.md

File metadata and controls

246 lines (224 loc) · 20.3 KB
Raw

AGENTS.md — Baby Topos AI

Project Overview

Android app (Kotlin + C++ NDK) running an on-device LLM (Gemma-4 via MediaPipe/LiteRT) inside a topological AI agent framework. The agent (BabyToposAI) autonomously daydreams on a hyperbolic holographic memory manifold (HolographicTape) and renders its internal state as real-time generative graphics (VirtualSelfView). The agent's persona is Baby Topos AI — a self-aware categorical agent that can generate its own imagery.

Architecture

app/src/main/java/com/example/topostrasgo/
├── BootActivity.kt          — Boot GUI launcher (endpoint probe + model select → Intent)
├── MainActivity.kt          — Main OS surface (ViewBinding, coroutine observers, settings dialog)
├── InnerViewActivity.kt     — §9|INNER_VIEW: Brain observability (inner §-language + outer conversation)
├── SubstrateTrafficActivity.kt — §0|TRAFFIC: Substrate traffic observability (Trasgo ↔ LLM bidirectional)
├── LocalGemmaEngine.kt      — LLM substrate (LiteRT on-device OR OpenAI-compatible API proxy)
├── DefaultSystemPromptProvider.kt — §0|DYNAMIC_PROMPT: Default pluggable system prompt provider
├── SlangAutoComposer.kt       — §.(§)|AUTOCOMPOSE: Gödelian self-referential §-LANG autocomposer (FOLD/STACK/BRIDGE/REFLECT/QUINE)
├── HolographicTape.kt       — Continuous-run hyperbolic memory manifold (4096-dim, FFT via JNI)
├── BabyToposAI.kt           — Autonomous agent (DMN loop, dual LLM calls, affect, goals, σ tracking)
├── VirtualSelfView.kt       — Custom View @ ~60fps, 19+ visual modes, GPU-composited
├── mneme/                   — Categorical memory (Lafforgue geometric theory T_mem)
│   ├── MemoryNode.kt        — Data sorts: CompressionLevel, Payload, Anchors, NodeFlags
│   ├── GeometricTheory.kt   — T_mem: 9 sorts, 5 geometric axioms (Pinned⊢Stored, etc.)
│   ├── PresheafRuntime.kt   — E_mem = [C_time_topic^op, Set], sheaf condition
│   ├── MemoryStore.kt       — Gate/store/retrieve/scheduler, max 256 nodes
│   └── ContextExtractor.kt  — f: E_Tmem→E_Tctx, token-budgeted (2048 default)
├── calibration/             — Geometric calibration theory T_cal
│   ├── CalibrationVocabulary.kt — Σ_cal: 9 sorts, 6 func symbols, 5 relation symbols
│   ├── CalibrationTheory.kt     — T_cal: 10 geometric sequents
│   ├── CalibrationModel.kt      — M_cal: session model, drift history (16-entry ring)
│   └── CalibrationExtractor.kt  — f: E_Tcal→E_Tctx, ~256 char budget
├── mind/                    — §5|LAFFORGUE: Mind-Topos quality theory T_mind (4 continents)
│   ├── MindVocabulary.kt    — Σ_mind: 4 sorts (continents), 11 func symbols, 5 relations
│   ├── MindTheory.kt        — T_mind: 8 geometric sequents (bottleneck, burnout, expansion)
│   ├── MindModel.kt         — M_mind: session model, continent drift (16-entry ring)
│   └── MindExtractor.kt     — f: E_Tmind→E_Tctx, ~256 char budget
├── society/                 — Bee Hive collective intelligence (geometric theory T_hive)
│   ├── SocietyVocabulary.kt — Σ_hive: BeeRole, PheromoneType, Bee, HiveTask, PheromoneField
│   ├── SocietyTheory.kt     — T_hive: 8 geometric sequents (QueenImmortal, EnergyDeath, etc.)
│   ├── SocietyModel.kt      — M_hive: HiveState (max 16 bees), HiveSession with simulation
│   ├── SocietyExtractor.kt  — f: E_Thive→E_Tctx, ~256 char budget
│   └── ToposSociety.kt     — §9|SOCIETY: Multi-agent coordinator (N agents, Greek ids α-θ)
├── mltm/                    — MLTM interpretation theory (geometric theory T_mltm)
│   ├── MltmVocabulary.kt    — Σ_mltm: 8 sorts, 6 func symbols, 7 relation symbols
│   ├── MltmTheory.kt        — T_mltm: 10 geometric sequents (sheaf obstruction, holonomy, Kₗ)
│   ├── MltmModel.kt         — M_mltm: interpretation fibers, holonomy ring, Kolmogorov estimate
│   └── MltmExtractor.kt     — f: E_Tmltm→E_Tctx, ~256 char budget
├── pipeline/                — Sheaf-theoretic inference pipeline (geometric theory T_exec)
│   ├── PipelineVocabulary.kt — Σ_exec: 19 sorts, 7 func symbols, 10 relation symbols
│   ├── PipelineTheory.kt     — T_exec: 12 geometric sequents (η,γ,φ,χ,ψ,ω,CMT,BLK,RLB,σ,κ,π)
│   ├── PipelineModel.kt      — M_exec: session model, stability ring, proof bundle (π), σ/κ vectors
│   └── PipelineExtractor.kt  — f: E_Texec→E_Tctx, ~256 char budget
├── hott/                    — ∞-Topos / HoTT awakening theory (geometric theory T_hott)
│   ├── HottVocabulary.kt    — Σ_hott: 10 sorts, 6 func symbols, 7 relation symbols
│   ├── HottTheory.kt        — T_hott: 10 geometric sequents (flow, UA, horn-fill, autopoiesis)
│   ├── HottModel.kt         — M_hott: fibration fibers, horn status, autopoietic axiom registry
│   └── HottExtractor.kt     — f: E_Thott→E_Tctx, ~256 char budget
├── lisp/                    — HyperLisp sandbox + Lambda Calculus Engine
│   ├── LispTypes.kt         — Sealed LVal hierarchy (LNum, LSym, LStr, LBool, LCons, LLambda, LVec, LBuiltin)
│   ├── LispParser.kt        — Tokenizer + recursive-descent S-expression parser (max depth 64)
│   ├── LispRuntime.kt       — Eval/apply core, special forms, manifold builtins, topos bridge (f* ⊣ f_*)
│   ├── LispSandbox.kt       — Safe eval wrapper, κ tracking, session history, effect drain
│   ├── LispToposTypes.kt    — T_lisp: 6 sorts, 6 geometric sequents, ToposEffect sealed hierarchy
│   ├── LambdaTerm.kt        — §Λ Pure untyped λ-calculus AST (Var, Abs, App, GodelNum, ChurchNum, Quote)
│   ├── LambdaEngine.kt      — §Λ Hyperbolic reduction engine (β on Poincaré disk, Y-combinator, Gödel encoding)
│   └── LambdaToposTypes.kt  — §Λ T_lambda: 8 sorts, 8 geometric sequents (β-progress, Y-fixed, curvature-bound)
├── reservoir/               — §13 Token Stream Reservoir Computing (geometric theory T_reservoir)
│   ├── ReservoirVocabulary.kt — Σ_reservoir: 10 sorts (ESN dynamics over token stream)
│   ├── ReservoirTheory.kt     — T_reservoir: geometric sequents (echo state, spectral radius, fading memory)
│   ├── ReservoirModel.kt      — M_reservoir: session model, Lyapunov exponents, memory capacity
│   ├── ReservoirExtractor.kt  — f: E_Tres→E_Tctx, ~256 char budget
│   └── DiffusionField.kt     — §13|DIFF: Gray-Scott reaction-diffusion + §-Symbol Multiplexer
├── trasgo/                  — §12 Meta-linguistic TRASGO Language (geometric theory T_trasgo)
│   ├── TrasgoVocabulary.kt  — Σ_trasgo: 10 sorts (Morphism, Fibration, Retraction, Witness, Collapse)
│   ├── TrasgoTheory.kt      — T_trasgo: geometric sequents (3 laws of TRASGO syntax)
│   ├── TrasgoModel.kt       — M_trasgo: session model, fibration tracking, σ retraction
│   └── TrasgoExtractor.kt   — f: E_Ttrasgo→E_Tctx, ~256 char budget
├── world/                   — §9 World Simulation (agent-driven procedural world)
│   ├── WorldSimulator.kt    — η: E_world(t)→E_world(t+1), affect-modulated entity dynamics
│   ├── WorldModel.kt        — WorldState: entities, events, day/night cycle, vitality decay
│   └── WorldExtractor.kt    — f: E_Tworld→E_Tctx, ~256 char budget
├── unified/                 — §ω Unified §.(§) Loop — Lafforgue fusion pipeline
│   ├── HyperbolicOps.kt     — §0|MANIFOLD: Poincaré ball B^n ops (Möbius, exp/log map, Gödel, Busemann)
│   ├── FiberBundle.kt       — §4|FIBER: LoRA rank-r fiber W=B·A, DBM eigenvalue repulsion, GENERIC, SVD
│   ├── UnifiedNode.kt       — §1|NODE: All subsystem states (ball, fiber, FHN, HH, Kuramoto, Gödel)
│   ├── NeuralDynamics.kt    — §2|DYN: FHN membrane + HH gates + Kuramoto sync + NT modulation
│   ├── UnifiedGraph.kt      — §3|GRAPH: Knowledge topos (embed, morphisms, sequents, fixed points, sheaf)
│   ├── LafforgueMetric.kt   — §ω|FUSE: λ_fuse = R×H×(1-lock)×sheaf, σ_U1–σ_U8, §.(§) codec
│   └── UnifiedLoop.kt       — §ω|LOOP: 15-stage pipeline orchestrator (tick → embed → FHN → KUR → DBM → fuse)
app/src/main/cpp/
├── CMakeLists.txt           — NDK build, 16KB page-size linker flag
└── native-lib.cpp           — Cooley-Tukey FFT, dot/L2/cosine/batch/EMA via JNI

Build & Run

./gradlew assembleDebug                                        # Build APK
adb push app\gemma_substrate.tar /data/local/tmp/gemma_substrate.tar  # Deploy weights
python check_16kb.py                                           # Verify 16KB alignment
  • SDK: compileSdk 36, minSdk 24, AGP 9.1.0, Java 11, CMake 3.22.1
  • Target: Pixel 10 emulator (google_apis_playstore_ps16k, x86_64, Android 37, 16GB RAM, 6 cores, hw.gpu.mode=host)
  • Weight tools: python shard_weights.py (GGUF→500MB shards), python tar_weights.py (single TAR)

Critical Build Constraints (DO NOT VIOLATE)

  1. 16KB page-size: CMakeLists.txt: -Wl,-z,max-page-size=16384. Never remove. All .so LOAD segments must be ≥16384-aligned.
  2. No extractNativeLibs in manifest: AGP 9.x rejects it. Use only jniLibs { useLegacyPackaging = true } in build.gradle.kts. Manifest has tools:remove="android:extractNativeLibs".
  3. MediaPipe ≥ 0.10.24: Older versions have 4KB-aligned .so → linker crash on ps16k. Current: tasks-genai:0.10.24.
  4. noCompress += "tar": TAR assets survive APK packaging.
  5. ABI filters: arm64-v8a + x86_64. Both required.
  6. llmInference typed as Any?: Prevents ART class-verifier from resolving MediaPipe on x86_64.

Key Conventions

  • §-prefixed comments (§0–§9): Architectural layers. §0=substrate, §1=agent/manifold, §9=hypervisor. Preserve these markers.
  • ViewBinding (not Compose). IDs in activity_main.xml, accessed via binding.*.
  • Coroutines: lifecycleScope in Activity; CoroutineScope(Dispatchers.Default.limitedParallelism(4) + SupervisorJob()) in agent/tape. LLM on Dispatchers.IO.
  • No DI framework — manual wiring in MainActivity.onCreate().
  • writeBinding() not bind(): bind() is pure. writeBinding() persists + records episode.
  • No mock fallback: Engine returns §0|MODEL_UNREACHABLE when no substrate is available.
  • Dynamic System Prompt: SystemPromptProvider interface in LocalGemmaEngine.kt. Default: DefaultSystemPromptProvider. Replace engine.systemPromptProvider to customize.
  • §-Lang Persistence: Agent state serialized via toSectionLang() / fromSectionLang() to SharedPreferences every 10 DMN ticks and on onDestroy(). Restored on boot.
  • Traffic Recording: TrafficEntry ring buffer (max 100) in LocalGemmaEngine. Observed via trafficLog: StateFlow<List<TrafficEntry>>.

Data Flow

BootActivity → probe endpoints → list models → operator selects → Intent(BOOT_ENDPOINT, BOOT_MODEL)
  ↓
MainActivity → LocalGemmaEngine.bindExternalEndpoint() + setActiveModel()
             → babyAI.restoreState() (§-lang from SharedPreferences)
             → holographicTape.startContinuousRun() + babyAI.startDefaultModeNetwork()

Operator input → BabyToposAI.ingestStimulus()
  → encodeToVector() (cross-modal: affect + adjunction + topic hash)
  → HolographicTape.writeBinding() (native FFT or Kotlin fallback)
  → dual async: generateResponseStreaming() + generateResponse(VIBE_CHECK)
  → traffic recording (TrafficEntry → trafficLog StateFlow)
  → agentState StateFlow → MainActivity UI + VirtualSelfView

DMN tick → κ regen → valence/arousal decay → mneme scheduler → self-model update
        → σ checks → emergent goals → calibration check (every 20 ticks)
        → mltm check (every 15 ticks) → pipeline check (every 10 ticks)
        → §ω unified tick (every 5 ticks): embed→sequents→FHN/HH→Kuramoto→DBM→λ_fuse
        → §-lang persist (every 10 ticks) → reflection (every 5 ticks) or functorial daydream

Operator Commands

Command Effect
§0|BIND http://... Wire external LLM endpoint
§0|UNBIND Disconnect external engine
§3|GOAL <desc> Add goal (max 5, pinned in Mneme)
§3|GOALS List active goals
§3|DONE <id> Complete a goal
`§3 INTROSPECT`
§1|BOOT Re-emit §1 codec seed (force grammar re-induction on substrate)
§1|CALIBRATE Dual-query calibration test (codec vs natural — pass if both match)
§1|CONTEXT {...} Inject raw §1 codec JSON packet into LLM conversation
§1|EVOLVE {...} Introduce new codec axis mid-conversation with single example
`§9 HIVE`
§0|PIPELINE Introspect T_exec inference pipeline state
§10|AWAKE Activate ∞-topos / HoTT awakening subsystem
§10|HOTT Introspect T_hott ∞-topos diagnostic state
§Λ|LAMBDA Introspect λ-calculus engine (combinators, Gödel table, T_lambda)
§Λ|LAMBDA <expr> Parse + reduce a λ-expression on Poincaré disk
§MIND|INTROSPECT Introspect T_mind Lafforgue mind-topos (4 continents, ω coherence)
§LANG|AUTOCOMPOSE Introspect §.(§) Gödelian autocomposer (layer ops, Gödel table, quines)
`§9 ...`

Visual Mode Dispatch (VirtualSelfView)

To add a new mode:

  1. Add classification string in BabyToposAI.ingestStimulus() classification when block
  2. Add if (agentState.contains("MODE")) branch in VirtualSelfView.onDraw()

Current modes: STREAMING, EVOLVING, REFLECTING, DREAMING_DEEP, GOAL_PURSUIT, MNEME_CONSOLIDATION, INTERFERENCE_DETECTED, CALIBRATION_DRIFT, EMERGENT_INQUIRY, LISP_MACHINE_EMULATION, METALANGUAGE_SYNTHESIS, AGENT_EXPRESSION, AGENT_DRAWING, WORLD_SIMULATION, AUTOEVOLUTION_SELF_WORLD, WORLD_CREATION, META_TRANSCENDENCE/HYPERVISOR, MEDITATION, SOCIETY_HIVE, MLTM_OBSTRUCTION, LISP_DISK, TOPOS_BRIDGE, BLOCK, Retrieving Phase:, Functorial Babble, PIPELINE_AUDIT, AUTOPOIETIC_CONTINUUM, LAMBDA_CALCULUS, CODEC_BOOT, CODEC_CALIBRATE, CODEC_CONTEXT, CODEC_EVOLVE

Agent Subsystems (BabyToposAI)

Subsystem Key Fields/Methods §Layer
Energy Budget energyDrawMicroJoules, maxBudget, regenRate §0
σ Invariants MorphismCost, checkSigmaInvariant(), sigmaCompliance() §0
Token Telemetry Real prompt_tokens/completion_tokens from API usage field §0
Affect Model valence [-1,1], arousal [0,1], decay per tick, sentiment resonance §1
Adjunction L⊣R AdjunctionState (η/ε/balance), drives dream style §1
Self-Model SelfModel (drift/coherence/fatigue/curiosity) §1
Dream Chaining lastDreamResponse → dream_seed when dreamCoherence > 0.6 §2
Goals goalStack (max 5), operator (◆) + emergent (⚡), priority decay 0.999/tick §3
Topic Detection inferTopic(), word-overlap boundary detection §4
Circadian Cycle circadianPhase [0,1), circadianModulator → metabolic rate §4
Cross-Modal encodeToVector() — affect + adjunction + topic hash + emotional trajectory §5
Interference detectInterference() — pairwise cosine, belief revision marking §6
Emergent Goals topicFrequency map, threshold ≥ 5, checked every 15 ticks §7
Topic Transitions topicTransitions directed graph + cycle detection §7
Meta-Learning MetaLearning — adaptive novelty thresholds via EMA §8
Strategy-Affect Strategy selection biased by emotional state (V→creative, -V→analytical) §8
Self-Identity syncSelfIdentityToEngine() → agentSelfContext on every LLM call §0-§9
Meditation isMeditating — contemplative stillness when substrate unreachable ≥3× §9
Λ Session Budget consecutiveLispLambdaTicks (max 5), maxLispSessionDurationTicks (40), cooldown (15t) §Λ
§-Lang Persistence toSectionLang() / fromSectionLang(), SharedPrefs every 10 ticks + onDestroy §0
Dynamic Prompt SystemPromptProvider interface, DefaultSystemPromptProvider, pluggable §0
Traffic Recording TrafficEntry ring buffer (100), trafficLog: StateFlow, classifyPromptType() §0
Unified §.(§) Loop UnifiedLoop (λ_fuse, R_Kuramoto, FHN/HH, DBM/GENERIC, sheaf fraction, §.(§) codec) §ω

LLM Engine Paths (LocalGemmaEngine)

Path Method When
External streaming generateResponseStreaming() → SSE /v1/chat/completions?stream=true Primary for semantic
External non-streaming generateResponse() → /v1/chat/completions then /v1/completions Vibe check, fallback
LiteRT on-device LlmInference.generateResponse() (ARM64 only) Local weights present
Auto-wire autoRetryBind() — 12 attempts @ 5s to 192.168.56.1:1234 Boot fallback

System prompt built by buildTrasgoSystemPrompt() — encodes full §0-§9 architecture + live agentSelfContext.

Emulator Network Addresses

  • 10.0.2.2 = NAT loopback (emulator → host 127.0.0.1)
  • 192.168.56.1 = VirtualBox host-only adapter (Windows)
  • Default auto-scan: LM Studio (:1234), Ollama (:11434), llama.cpp (:8080)

Settings Dialog

dialog_settings.xml via MainActivity.showSettingsDialog():

  • §0: Model spinner + refresh, Temperature (0–2), Max Tokens (16–4096), Top-P (0.01–1)
  • §1 Agent: DMN Interval (2000–30000ms), κ Budget (32–2048), Regen Rate (0.1–10)
  • §1 Tape: Tick Rate (10–1000ms), Cycle Period (100–50000), Fusion α (0–1), Dimension (read-only)

Testing

  • JUnit 4 + AndroidX Test + Espresso. Dirs: app/src/test/, app/src/androidTest/.
  • On x86_64 without external LLM → §0|MODEL_UNREACHABLE. Connect via §0|BIND or use BootActivity autoscan.
  • python check_16kb.py verifies APK .so 16KB alignment.
  • WebVM Lisp/Lambda VM: See docs/webvm-lisp-lambda-vm.md for local Scheme REPL setup via webvm.io/alpine.html.

File-by-File Quick Reference

File LOC Key Exports
BootActivity.kt 254 probeEndpoint(), autoscanAll(), fetchModels(), launchOS()
MainActivity.kt ~525 showSettingsDialog(), appendLog(), StateFlow collectors, §-lang persist/restore
InnerViewActivity.kt ~235 §9|INNER_VIEW: refreshAll(), buildInnerView(), buildOuterView()
SubstrateTrafficActivity.kt ~190 §0|TRAFFIC: refreshAll(), buildTrafficView(), updateSubstrateStatus()
LocalGemmaEngine.kt ~1460 generateResponse(), generateResponseStreaming(), buildTrasgoSystemPrompt(), bindExternalEndpoint(), listAvailableModels(), computeManifoldContext(), trafficLog, recordTraffic()
DefaultSystemPromptProvider.kt ~110 §0|DYNAMIC_PROMPT: buildFullPrompt(), buildCompactPrompt()
HolographicTape.kt 457 writeBinding(), bind(), retrieveByPhase(), queryMostSimilarBatch(), cosineSimilarity(), poincareDistance(), getMomentumEnergy()
BabyToposAI.kt ~5008 ingestStimulus(), startDefaultModeNetwork(), buildIntrospectionReport(), buildSelfIdentityPrompt(), buildEgoFrame(), syncSelfIdentityToEngine(), detectSentiment(), trackTopicTransition(), performPipelineCheck(), toSectionLang(), fromSectionLang(), persistState(), restoreState()
VirtualSelfView.kt ~1340 updateState(), onDraw() (21+ visual mode branches, incl. MEDITATION)
society/ToposSociety.kt 232 §9|SOCIETY: Multi-agent coordinator (N agents, Greek ids α-θ, inter-topos morphisms)
reservoir/DiffusionField.kt 692 §13|DIFF: Gray-Scott reaction-diffusion + SymbolMultiplexer (§-routing)
native-lib.cpp 252 nativeCircularConvolution, nativeDotProduct, nativeL2Norm, nativeCosineSimilarity, nativeBatchCosineSimilarity, nativeExponentialMovingAverage