EphemeraAdmin: Import: Help:Ephemera Agent/System Overview

2026-04-01T04:29:27Z

Import: Help:Ephemera Agent/System Overview

New page

{{DISPLAYTITLE:Ephemera Agent — System Overview}}
__TOC__

== 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 <code>Instructions:</code> namespace that defines agent behavior as wiki pages
* A <code>Sources:</code> 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:

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

=== Server-Side PHP Components ===

{| class="wikitable" style="width:100%"
! File !! Responsibility
|-
| <code>proxy.php</code> || 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.
|-
| <code>llm-proxy.php</code> || 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: <code>{text, tool_calls, stop_reason}</code>.
|-
| <code>wiki_api.php</code> || 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.
|-
| <code>context.php</code> || 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.
|-
| <code>classify.php</code> || Planner LLM call. Classifies task type, extracts named entities, detects source subtypes. Contains <code>is_obviously_query()</code> fast pre-check for read-only tasks.
|-
| <code>agent.php</code> || 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.

{| class="wikitable" style="width:100%"
! Provider !! Tool Calling Mechanism
|-
| Anthropic || <code>tool_use</code> content blocks. Response extracted from <code>input</code> field (already a parsed object).
|-
| OpenAI || <code>tools</code> array with function type. Arguments are a JSON string — one <code>JSON.parse</code>, guaranteed valid.
|-
| Gemini || <code>functionDeclarations</code> via native Gemini endpoint. Response from <code>functionCall.args</code> (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.

{| class="wikitable" style="width:100%"
! Namespace !! Purpose & Rules
|-
| <code>Instructions:</code> || Out-of-universe. Machine-readable operational content. Defines agent behavior, page schemas, style guides, and workflows. Never shown to readers.
|-
| <code>Sources:</code> || In-universe. Primary evidence documents. Written from an in-world perspective. May be biased, incomplete, or contradictory — this is intentional.
|-
| <code>Talk:</code> (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.
|-
| <code>Help:</code> || 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 (<code>ephemera-keys.json</code>)
* 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
* <code>Instructions:Config</code> wiki page for runtime configuration

=== Pending Test ===

* End-to-end context assembly (requires <code>Instructions:</code> namespace to be populated)
* Planner model classification accuracy on real tasks
* XML import (requires <code>importupload</code> 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 <code>agent.php</code> 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

[[Category:Help]]
[[Category:EphemeraAgent]]

Help:Ephemera Agent/System Overview - Revision history

EphemeraAdmin: Import: Help:Ephemera Agent/System Overview