Help:Ephemera Agent/System Overview

Project Summary

Encyclopedia Ephemera is a self-expanding, AI-assisted MediaWiki system for collaborative science-fiction worldbuilding. Set in the populated Solar System of the year 2300, it combines a structured wiki knowledge base with a browser-based LLM agent interface that can read, write, and reason about wiki content using natural language.

The system is built around a core principle: all agent behavior, content standards, and editorial policies are defined inside the wiki itself, making the system self-documenting and self-configuring.

This approach is referred to throughout the documentation as the wiki-native configuration model: core behavior lives in wiki pages, not hard-coded prompt files.

The system integrates:

• A MediaWiki installation as the knowledge base and instruction store
• A browser-based LLM agent UI (Ephemera Agent) with multi-provider support
• A PHP context-assembly pipeline that gathers relevant wiki content before generation
• A structured Instructions: namespace that defines agent behavior as wiki pages
• A Sources: namespace for in-universe evidence documents with Talk page interpretation
• Native tool calling for all supported LLM providers (no JSON parsing fragility)
• Wikipedia API integration for real-world scientific and historical grounding
• Bulk import tools for JSON and MediaWiki XML dump formats

System Architecture

High-Level Call Flow

The system has two parallel request paths from the browser:

Component	Role
Browser → proxy.php	Wiki API calls from the agent loop (read/write pages, search, tokens)
Browser → llm-proxy.php	Direct LLM calls with no context assembly (simple queries, maintenance)
Browser → agent.php	Context-aware generative tasks (article creation, editing, source generation)
agent.php → wiki_api.php	All wiki and Wikipedia content retrieval during context assembly
agent.php → context.php	Context assembly pipeline (classify → gather → rank → trim)
agent.php → classify.php	Planner LLM call: task classification and entity extraction
agent.php → llm-proxy.php	Generator LLM call with assembled context in system prompt

Server-Side PHP Components

File	Responsibility
proxy.php	CORS-aware MediaWiki API proxy. Forwards browser requests to the local wiki API, rewrites Set-Cookie headers for cross-origin session management, handles multipart file uploads for XML import.
llm-proxy.php	Multi-provider LLM proxy with native tool calling. Translates a unified tool schema (OpenAI format) to each provider's native format. Returns a normalised response envelope: {text, tool_calls, stop_reason}.
wiki_api.php	Pure MediaWiki API wrapper. Fetch pages, batch-fetch pages, get links, search, extract talk page sections, parse JSON blocks, estimate tokens, rank by frequency. Also contains Wikipedia API functions.
context.php	Context assembly pipeline. Resolves the instruction dependency graph, performs 1-hop link expansion, retrieves sources and filtered talk pages, deduplicates, ranks by keyword overlap, trims to token budget.
classify.php	Planner LLM call. Classifies task type, extracts named entities, detects source subtypes. Contains is_obviously_query() fast pre-check for read-only tasks.
agent.php	Main orchestrator. Runs: config load → pre-check → classify → build_context → assemble augmented system prompt → forward to generator via llm-proxy.php.

Native Tool Calling

All LLM providers are called using their native tool/function calling APIs — not prompt-only JSON discipline. This eliminates the entire class of JSON parsing failures that plague prompt-based agent systems.

Provider	Tool Calling Mechanism
Anthropic	tool_use content blocks. Response extracted from input field (already a parsed object).
OpenAI	tools array with function type. Arguments are a JSON string — one JSON.parse, guaranteed valid.
Gemini	functionDeclarations via native Gemini endpoint. Response from functionCall.args (already parsed).
Custom	OpenAI-compatible format forwarded as-is to any endpoint that supports the OpenAI tool calling protocol.

All providers return results through a normalised envelope so the JavaScript agent loop uses one code path regardless of which model is active.

Wiki Namespace Design

The wiki is organised around four distinct content layers. Strict separation between layers is a core design principle.

Namespace	Purpose & Rules
Instructions:	Out-of-universe. Machine-readable operational content. Defines agent behavior, page schemas, style guides, and workflows. Never shown to readers.
Sources:	In-universe. Primary evidence documents. Written from an in-world perspective. May be biased, incomplete, or contradictory — this is intentional.
Talk: (for Sources)	Interpretive layer. Contains reliability assessments, bias analysis, and editorial notes. Not canonical evidence. Filtered (never dumped whole) when included in context. Talk pages are interpretive and are never treated as primary evidence.
Main namespace	Reader-facing encyclopedia articles. Synthesized from Sources, guided by Instructions.
Help:	Human-readable documentation for the Ephemera Agent tool itself.

Design Principles

• Separation of concerns — Instructions ≠ Sources ≠ Encyclopedia ≠ Talk. Each layer has one job.
• Evidence-based synthesis — encyclopedia articles derive from sources, not from LLM imagination alone.
• Wiki-native configuration — agent behavior is defined in wiki pages, editable without code changes.
• Modularity — instruction pages are composable via dependency graphs.
• Agent-first design — the system is built for LLM interaction, not just human editing.
• Interpretability — bias and reliability are explicitly modeled, not assumed away.
• Epistemic humility — sources can be wrong, biased, or contradictory. That is not a bug.
• Auditability — every agent edit is watchlisted and metadata-stamped for review.
• No JSON fragility — native tool calling APIs are used throughout.
• Tiered inference — cheap fast models for planning, expensive models for generation.

Safe Usage Guidelines

See Help:Ephemera Agent#Safe Usage Guidelines on the main help page.

Current Status

Implemented and Working

• Full agent loop with native tool calling (Anthropic, OpenAI, Gemini, Custom)
• Multi-tier model routing (planner / generator independently configured)
• Wiki browser with preview rendering, LCS diff, search, back navigation
• Red link autogeneration (click-to-generate and batch modes)
• Post-edit: watchlist, talk page metadata, auto-preview of edited page
• Bulk import: JSON (3 formats) and MediaWiki XML dump
• Credentials file loading (ephemera-keys.json)
• Settings persistence via localStorage
• Mode indicator and context preview panel in UI
• Context assembly PHP pipeline (all four PHP files)
• Wikipedia API integration for real-world grounding
• Instructions:Config wiki page for runtime configuration

Pending Test

• End-to-end context assembly (requires Instructions: namespace to be populated)
• Planner model classification accuracy on real tasks
• XML import (requires importupload permission)
• Red link autogen quality with full context pipeline

Known Limitations

• The LCS diff algorithm is O(m×n) — may pause on very large pages
• Preview rendering lacks the wiki's full CSS — some templates render incorrectly
• Local LLM servers require a tunnel (ngrok) since agent.php runs on the remote server
• Batch operations may hit the 20-iteration agent loop limit on very large tasks

Long-Term Vision

Encyclopedia Ephemera is designed to evolve into a self-expanding, agent-driven knowledge system where content, behavior, and interpretation all live within the wiki itself:

• Autonomous content growth — red link detection and generation creates a self-completing wiki
• Consistency maintenance — agents audit for contradictions, missing citations, and continuity errors
• Multi-perspective historiography — the same event seen through multiple biased sources
• Scalable worldbuilding infrastructure — the system grows with the fiction, not against it
• Self-improving instructions — agents can propose and draft changes to their own instruction pages