TMBSPACESHIPS Knowledge Graph

A full-stack knowledge graph application that extracts, structures, and explores physics and propulsion concepts from @TMBSPACESHIPS tweets — a retired 38-year USAF PhD engineer who posts about plasma physics, electromagnetic propulsion, fusion energy, and advanced aerospace technology.

What it does

• Extracts topics, entities, and themes from 583 tweets using Claude AI
• Builds a graph database (SurrealDB) with bidirectional links between tweets, topics, entities, themes, and images
• Explores the graph through a web UI with interactive D3.js force-directed visualization
• Chats with Claude, which navigates the graph using tool-use to answer questions about the content

Architecture

Tweets (583) ──discusses──> Topics (852) ──belongs_to──> Themes (15)
    │                           │    ↕                       ↕
    │──cites──> Entities (236) ─┘  relates_to          theme_overlap
    │               ↕
    │──has_image──> Images (308)
    │           associated_with
    └───────────── entity_relates_to

Node types: tweet, topic, theme, entity, image Edge types: discusses, cites, has_image, belongs_to, relates_to, associated_with, entity_relates_to, theme_overlap

Stack

Layer	Technology
Database	SurrealDB 3.0 (graph DB with SurrealKV backend)
Backend	Python / FastAPI
AI	Anthropic Claude (extraction + chat)
Frontend	Vanilla JS + D3.js force-directed graph
API Client	httpx (X/Twitter API v2)

Setup

Prerequisites

• Python 3.14+
• uv (Python package manager)
• SurrealDB 3.0+
• Anthropic API key
• X/Twitter API credentials (for fetching tweets)

Install

git clone https://github.com/postrv/tmbspaceships.git
cd tmbspaceships
cp .env.example .env
# Edit .env with your API keys
uv sync

Run SurrealDB

surreal start --user root --pass root surrealkv:./surreal_data --bind 0.0.0.0:8000

Fetch tweets (optional — requires X API credentials)

uv run python x_client.py

Run the ingestion pipeline

This uses Claude to extract topics, entities, and themes from the tweets, then derives bidirectional graph edges:

uv run python ingest.py

Start the API server

uv run uvicorn main:app --port 8001

Open http://localhost:8001/ui for the web interface.

API Endpoints

Endpoint	Description
GET /stats	Graph statistics
GET /search/topics?q=	Full-text topic search
GET /search/tweets?q=	Full-text tweet search
GET /search/entities?q=	Entity search
GET /themes	List all themes
GET /themes/{id}	Theme detail with topics + connected themes
GET /topics	Top topics by mention count
GET /topics/{id}	Topic detail with relations, entities
GET /topics/{id}/tweets	Tweets discussing a topic
GET /topics/{id}/entities	Entities associated with a topic
GET /entities/{id}	Entity detail with topics, related entities
GET /entities/{id}/topics	Topics associated with an entity
GET /entities/{id}/related	Co-cited entities
GET /graph/viz	Graph data for D3 visualization
GET /graph/neighborhood/{table}/{id}	All connections from any node
GET /bridge?a=&b=	Tweets connecting two topics
POST /chat	Claude chat with graph navigation
GET /clusters	Topic clustering analysis

Chat

The /chat endpoint runs an agentic loop where Claude uses 20 graph query tools to explore the knowledge graph before synthesizing an answer. Ask it things like:

• "How does antigravity connect to plasma physics?"
• "What papers does TMBSPACESHIPS reference most?"
• "Explain the E-M-K axis framework"

Environment Variables

See .env.example for all configuration options. Key variables:

Variable	Required	Description
ANTHROPIC_API_KEY	Yes	For AI extraction and chat
X_BEARER_TOKEN	For fetching	X/Twitter API bearer token
SURREALDB_URL	No	Default: ws://localhost:8000/rpc
SURREALDB_USER	No	Default: root
SURREALDB_PASS	No	Default: root

License

MIT