System

AI Research Kernel

The kernel is the intelligence layer beneath every surface — mobile app, web, CLI, and eventually internal fund infrastructure. It is intentionally independent of any transport protocol, UI framework, or database driver.

Design Principle

If the kernel is clean, the same agent logic can power the iOS chat, a desktop research tool, a scheduled signal pipeline, and a hedge fund allocation engine — without any changes to the agents themselves.

Why a Kernel?

Most AI applications couple intelligence to infrastructure: agents call databases directly, LLM prompts are hardcoded in route handlers, data fetching is mixed with analysis logic. This makes the system brittle — swapping a data vendor or changing the UI breaks the intelligence layer.

The Thesis kernel inverts this. Agents are pure functions of their inputs. Tools are swappable adapters. The orchestrator is stateless. The result is a system that can be tested without a live API key, extended without touching existing agents, and wired to new surfaces without refactoring.

Kernel Layer Map

┌─────────────────────────────────────────────────────────────────┐ │ API / UI Surface │ │ (FastAPI route · Mobile app · CLI · Desktop) │ └───────────────────────────┬─────────────────────────────────────┘ │ AgentContext ┌───────────────────────────▼─────────────────────────────────────┐ │ InvestmentManager │ │ (Orchestrator) │ │ routes → selects agents → runs in parallel → aggregates │ └──────┬──────────┬──────────┬──────────┬──────────┬─────────────┘ │ │ │ │ │ MacroAgent NewsAgent FundAgent PriceAgent PortAgent │ │ │ │ │ ┌──────▼──────────▼──────────▼──────────▼──────────▼─────────────┐ │ Tool Layer │ │ MacroDataTool · MarketDataTool │ └──────────────────────────────────────────────────────────────────┘ │ ┌───────────────────────────▼─────────────────────────────────────┐ │ External APIs │ │ FRED API · Massive API │ └─────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────┐ │ Future Layers (Phase 3–4) │ │ MemoryInterface → pgvector RAG │ │ BaseStrategy → signal scoring, regime models │ │ RiskEngine → position sizing, drawdown guards │ └─────────────────────────────────────────────────────────────────┘

Core Abstractions

AgentContextCore Type

Input — The full request context every agent receives: symbols, intent, user_id, pre-fetched portfolio data, and session notes. Agents are pure — they read context, invoke tools, return results. No side effects.

BaseToolInterface

Data Interface — Abstract contract for external data fetching. Agents never call market data services directly — they invoke tools. This makes agent logic testable (swap real tools for mocks) and the data dependency graph explicit.

BaseAgentInterface

Intelligence Unit — Abstract contract all specialist agents implement. One method: run(ctx) → AgentResult. Must never raise — degrade gracefully with _error_result(). Must never invent data — only use what tools return. Must never issue trade instructions.

MemoryInterfaceStub → pgvector

Recall Layer — Abstract interface for cross-session agent memory. Current implementation: EphemeralMemory (in-process, non-persistent). Future: PgvectorMemory backed by PostgreSQL pgvector for semantic RAG over research history.

BaseStrategyStub → Live

Signal Generation — Converts agent evidence (AgentResult list) into directional StrategySignals: symbol, direction (bull/bear/neutral), score (-1.0 to +1.0), conviction (0.0 to 1.0). Pure function — no data fetching. Bridges research and execution.

RiskEngineStub → Live

Risk Filter — Abstract risk engine that filters and sizes strategy signals within a risk budget. Returns a RiskAssessment: approved signals, rejected signals, portfolio heat score (0–1), and human-readable risk flags.

InvestmentManagerLive

Orchestrator — Central orchestrator. Routes AgentContext to the right agents, runs them in parallel, aggregates outputs into a structured evidence bundle. Does NOT synthesize the final LLM response — that stays in the API layer, keeping the kernel transport-agnostic.

Tool Layer

Tools are the only mechanism by which agents access external data. Every tool implements BaseTool.call(**kwargs) → Any and raises ToolError on failure. Agents catch ToolError and degrade gracefully — they never propagate exceptions to the orchestrator.

Tool	Wraps	Actions
`MarketDataTool`	MarketDataService (Massive API)	`quote · bars · fundamentals · news · market_status · movers · indicator`
`MacroDataTool`	get_macro_snapshot() (FRED API)	`Fed rate · CPI · unemployment · GDP · 2Y/10Y yields · regime label`

AgentResult Contract

Every agent returns the same structured type. The orchestrator builds the evidence layer from a list of these before passing it to the LLM synthesis step.

@dataclass
class AgentResult:
    agent_key:   str           # matches kernel registry key
    name:        str           # display name
    summary:     str           # one-sentence finding
    confidence:  int           # 0–100: agent's self-assessed confidence
    signals:     list[str]     # 2–5 structured bullets
    data:        dict[str,Any] # raw typed data for downstream use
    tool_calls:  list[str]     # audit trail of tools invoked

What's a Stub

MemoryInterface, BaseStrategy, and RiskEngine are defined as abstract interfaces today. The interfaces are stable — adding a pgvector memory backend or a momentum strategy module does not require changing any existing agent code. The kernel is designed to grow into the hedge fund infrastructure without architectural rewrites.

Research Console

The kernel exposes a research console at /console — an internal web UI where you can trigger any agent combination, inspect raw evidence bundles, see which tools were called, and validate routing decisions. This is the primary tool for iterating on agent logic without going through the mobile app.

PreviousSystem Architecture NextAgent Framework