PhantomReason 0.1.3

Symbolic AI reasoning engine built on PhantomTrace absence arithmetic. Trace-based memory, fact management, and semantic retrieval for standalone use or as an augmentation layer over LLMs.

PhantomReason

A symbolic AI reasoning engine built on PhantomTrace absence arithmetic.

PhantomReason is not a neural network. It represents knowledge as sparse binary vectors where each dimension is either present or absent -- the two fundamental states of PhantomTrace arithmetic. Learning happens by toggling these states through the same operations that define the algebra: combine, compare, add, erase, and toggle.

The result is a lightweight symbolic system that can store facts, answer questions, parse sentence structure, and generate constrained text -- all without gradient descent, matrix multiplication, or floating-point weights.

Why This Exists

Large language models are powerful but opaque. They hallucinate, forget instructions, and offer no mechanism to inspect why they produced a given answer.

PhantomReason takes a different approach:

• Every fact has a traceable strength stored as a PhantomTrace number. You can inspect it, reinforce it with add, weaken it with erase, and watch it decay over time.
• Predictions are distance-based. The model ranks candidates by how close their trace vectors are to the current context. The scoring is transparent and deterministic.
• Contradictions are resolved symbolically. When a new fact conflicts with an old one, the old fact's strength is erased rather than silently overwritten.
• Memory is explicit. Episodes, facts, and symbols each have their own trace store with named banks. Nothing is hidden in a billion-parameter matrix.

This makes PhantomReason suitable as a standalone symbolic reasoner for constrained domains, or as an augmentation layer that can sit alongside an LLM to provide grounded fact memory, symbolic confidence tracking, and interpretable retrieval.

Installation

pip install phantomreason

Requires Python 3.11+ and PhantomTrace (installed automatically).

Performance

Initial model setup involves computing sparse trace vectors for the vocabulary and training corpus. On a typical machine:

Operation	Time
Import + model init (dim=512)	~1-2 seconds
Training on a few sentences	~30-40 seconds
Subsequent startup with persisted state	~3-5 seconds
Individual predictions	<1 second (warm cache)
route_prompt queries	0.1-4 seconds

The first run is the slowest because trace vectors must be computed for every word in the training data. After the model saves its state, restarts are fast because the vectors are loaded from disk rather than recomputed.

Quick Start

from phantomreason import PhantomLanguageModel

model = PhantomLanguageModel(dim=512, sparsity=47)

model.train_on_text(
    "aurora paints dawn softly. chefs simmer herbs slowly. "
    "gardeners water orchids gently.",
    epochs=1,
)

model.register_fact("chefs", "simmer", ["herbs", "slowly"])
model.register_fact("gardeners", "water", ["orchids", "gently"])

routed = model.route_prompt("what do chefs simmer?")
print(routed["fact_answer"])  # "herbs slowly"
print(routed["sample"])       # "chefs simmer herbs slowly."

prediction = model.predict_next(model.tokenize("aurora paints"))
print(prediction)  # "dawn"

Note on fact recall: route_prompt matches the question's predicate against stored fact predicates. The predicate in the question must match the stored form exactly (e.g., ask "what do chefs simmer?" not "what does chef simmer?"). Verb form normalization covers common auxiliaries (is/are/was/were) but not all inflections.

Core Concepts

Trace Vectors

Every word the model knows is represented as a sparse vector of AbsentNumber objects. Each slot is either present (the word is associated with that dimension) or absent (it is not). The vector has a fixed number of present slots controlled by the sparsity parameter.

Operations

All reasoning uses PhantomTrace operations from the absence-calculator library:

Operation	PhantomTrace	Use in Agent
combine(a, b)	State overlap	Building context signatures from word vectors
compare(a, b)	Directional difference	Measuring distance between vectors
add(a, b)	State accumulation	Composing semantic probes, strengthening facts
erase(a, b)	State removal with flip	Weakening facts, resolving contradictions
toggle(x)	Flip present/absent	Learning updates, vector modification
n(value)	Create a present number	Fact strength initialization

Trace Stores

The model maintains four separate trace stores:

• Trace store -- word vectors with context and topic memory banks
• Symbol store -- intent, action, form, and role classifications
• Episode store -- interaction history for episodic memory retrieval
• Fact store -- subject-predicate-object triples with forward and inverse lookup

Each store holds a primary vector and one or more named banks per entry, all subject to the same sparsity constraint.

Fact Lifecycle

Facts have a strength value stored as a PhantomTrace AbsentNumber:

1. A new fact starts with strength n(1) -- a present 1.
2. Teaching the same fact again adds n(1) to its strength.
3. A contradicting fact (same subject + predicate, different object) erases the old fact's strength.
4. Periodic decay erases n(1) from old facts, letting stale knowledge fade.
5. A fact becomes inactive when its strength drops to an absent state.

This mirrors how PhantomTrace arithmetic treats presence and absence: knowledge does not disappear, it transitions from present to absent.

Training and Ingestion

model.train_on_text("gardeners water orchids gently.", epochs=1)

model.ingest_text_corpus(long_text, trace_budget_per_sentence=96)

model.ingest_file("corpus.txt")

model.ingest_url("https://example.com/article")

The seed_lexicon.txt file included in the repository provides 60 dictionary-style definitions that bootstrap the model's vocabulary and fact base. Ingesting the full lexicon at dim=512 takes several minutes.

HTTP Service

PhantomReason includes an HTTP service:

phantomreason-serve --host 127.0.0.1 --port 8080 --dim 512 --sparsity 47

Or with authentication:

export PHANTOM_AGENT_API_TOKEN='your-secret-token'
phantomreason-serve --host 127.0.0.1 --port 8080

Endpoints

Method	Path	Auth	Description
GET	/health	No	Service and model status
GET	/evaluate	Yes	Run the built-in evaluation harness
POST	/query	Yes	Route a prompt through the reasoning pipeline
POST	/teach	Yes	Train on new text
POST	/ingest	Yes	Ingest text, file, or URL
POST	/focus	Yes	Set focus mode or focus text
POST	/checkpoint	Yes	Save model state to disk

Example Requests

# Query
curl -X POST http://localhost:8080/query \
  -H "Authorization: Bearer $PHANTOM_AGENT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "what do chefs simmer?"}'

# Teach
curl -X POST http://localhost:8080/teach \
  -H "Authorization: Bearer $PHANTOM_AGENT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "vector means an ordered list used for state", "epochs": 1}'

# Ingest from URL
curl -X POST http://localhost:8080/ingest \
  -H "Authorization: Bearer $PHANTOM_AGENT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/article"}'

Data Storage

Runtime state is stored in the current working directory by default:

• words -- the learned vocabulary, one word per line
• phantom_model_state.json -- all vectors, banks, facts, episodes, and symbols

Set PHANTOM_DATA_DIR to store state in a custom location:

export PHANTOM_DATA_DIR=/var/lib/phantomreason
phantomreason-serve --host 127.0.0.1 --port 8080

Evaluation

Run the built-in evaluation harness to verify the model works correctly:

phantomreason-eval

This tests fact recall, contradiction handling, decay behavior, and sentence parsing.

As an LLM Augmentation Layer

PhantomReason is designed to complement large language models, not replace them. A future integration package can use the agent as:

• A grounded fact store. Teach the agent verified facts and query it before passing context to an LLM. The agent's symbolic confidence scores tell you which facts are reliable.
• A contradiction detector. When new information conflicts with stored knowledge, the agent's erasure mechanics make the conflict explicit rather than silently overwriting.
• An interpretable memory layer. The agent's trace vectors and fact strengths are fully inspectable -- you can trace why a particular answer was retrieved.
• A retrieval filter. Use the agent's rank_candidates and retrieve_fact to select relevant context for an LLM prompt, with transparent distance scores.

The boundary is clean: PhantomReason handles memory, confidence, and symbolic retrieval. The LLM handles natural language generation and broad world knowledge.

Interactive Mode

For experimentation and debugging:

python -c "from phantomreason import PhantomLanguageModel, run_interactive_test; run_interactive_test(PhantomLanguageModel(dim=512, sparsity=47))"

The first run takes 30-40 seconds while trace vectors are computed. Subsequent runs with persisted state start in under 5 seconds.

Commands in interactive mode:

Command	Description
teach <text>	Train on new text
ingest <file>	Ingest a local text file
scrape <url>	Ingest from a URL
focus <text>	Prime focus mode on specific text
focus on / focus off	Toggle focus mode
inspect <prompt>	Show the top-ranked candidate and its trace comparison
Any other text	Route through the full reasoning pipeline

Project Structure

phantomreason/
  __init__.py       Package exports
  model.py          Core reasoning engine (PhantomLanguageModel)
  traces.py         PhantomTrace operation wrappers
  stores.py         Sparse trace vector storage (TraceStore)
  storage.py        Vocabulary and state path management
  corpus.py         Text normalization, sentence splitting, URL fetching
  service.py        HTTP service with auth and metrics
  evaluate.py       Built-in evaluation harness

Requirements

• Python 3.11+
• phantomtrace >= 0.5.0

No other dependencies. No PyTorch, TensorFlow, NumPy, or any ML framework.

License

MIT