# JANUS: A Trading Stack Where the LLM Can Only Reduce Position Size
*No token, no presale, no claimed returns. Four MIT-licensed repos and an argument.*
THE SOFTWARE IS OF COURSE PROVIDED AS-IS, ZERO WARRANTIES AND SHOULD NOT BE USED IN PRODUCTION.
I hope the reader understands that. Comments and suggestions for improvement, and forks with real improvements, of course, are very much welcome.
---
Most "AI trading bots" wrap an OpenAI key in a Telegram bot and sell a fantasy. The LLM picks the trade, sizes the position, and hallucinates a strategy. When it hallucinates a losing one, the account is gone.
This stack is the opposite. The LLM sits in the pipeline, but its only authority is to downsize or veto. It cannot upsize. It cannot invent an action the deterministic engine did not already rank. Every trade passes a verifier enforcing nine invariants. If the decision engine cannot certify an admissible action, the pipeline returns flat.
---
## The four repositories
### AGOP — the decision engine
`https://github.com/starwalkerz/AGOP`
AGOP ranks alternatives under multiple criteria, a strategic counter-party, and uncertain outcomes. The output is a ranked list with lower confidence bounds, a Nash equilibrium for the adversarial interaction, and a survivor set that has passed three deductive filters.
In design-by-contract mode, it refuses a user-supplied capacity parameter `K` and derives it from the problem's own structure:
K = max(1, floor(n_wl_classes / (1 + H(σ_DM) * H(σ_CP))))
where `n_wl_classes` is the Weisfeiler–Lehman structural class count and the two entropies are the Shannon entropies of the Nash strategies. A `verifies_theorem_5` decorator enforces, on every call, that the fixed point has converged in one step and that every returned alternative has a strictly positive lower confidence bound, adoption status one, positive composite score, and membership in the survivor set.
The engine cannot be talked into a ranking. Hand it a problem with no admissible action and it raises before returning. Hand it a well-formed problem and the ranking is byte-for-byte reproducible from the seed. Everything downstream depends on this.
### KAIROS — the anomaly detector
`https://github.com/starwalkerz/kairos`
KAIROS asks *is this point unusual relative to the model we already believe*, not *is this point unusual relative to its neighbours*. The model is a set of declared Gaussian-modulated Gaussian cycles. KAIROS subtracts the cyclical baseline and examines the residual. The detection threshold is the Bayes threshold under equal priors and equal costs. Quantum amplitude estimation runs on IQM hardware with a classical fallback that is exact for the problem sizes involved.
KAIROS does not learn. The cycles are declared by the operator. If the declared cycles are wrong, the residual is wrong, and KAIROS says so.
### Causalitybot — the causal geometry reader
`https://github.com/starwalkerz/Causalitybot`
Causalitybot translates causal set theory into non-chronological pattern recognition for order flow. Market structure is treated as emergent geometry generated by causally linked transactions. Imposing a uniform clock on a system with no fundamental clock is treated as the original sin of technical analysis. The poset replaces the clock. Institutional orders and liquidity vacuums generate causal horizons; surviving future paths form attractors; bottlenecks are price levels through which every future path must pass, scored by how thin their volume is relative to the neighbours.
Research-grade, single-pair, parameter-sensitive. A thesis with executable content.
### JANUS — the orchestrator
`https://github.com/starwalkerz/janus`
JANUS takes the three above plus an LLM and asks *how do we let the language model analyse without letting it trade*. The answer is a three-phase pipeline with nine invariants:
snapshot → PRE_AGOP modules → axes → AGOP
→ POST_AGOP modules → risk bound
→ PRE_LLM modules → LLM → verifier → paper broker
PRE_AGOP modules patch axes. POST_AGOP modules contribute risk multipliers in [0, 1] or veto. PRE_LLM modules veto or contribute context. No module does two of those. The risk bound is the product of the strategy cap, the Kelly coefficient, the Kelly fraction, and the composed module multiplier. The LLM reads the full context and returns a delta in [0, 1]. The verifier checks the delta against the bound, checks the action against the AGOP ranking, and checks that no module vetoed.
The LLM cannot upsize. It cannot invent an action outside the ranking. It cannot override a toxic-flow gate or a contract violation. Any breach returns a flat intent at size zero.
---
## What makes this different from every AI trading bot on this forum
### The LLM is bounded, formally
The nine invariants are runtime predicates. The `verify_trade_intent` decorator is the only path from decision logic to execution.
I5 — `position_size <= risk_bound.upper_position_size`. The risk bound is computed by the deterministic engine before the LLM runs. The LLM's output is a multiplier on that bound. A hallucinated size of 0.5 against a bound of 0.02 is clamped to 0.02.
I1 — `action in ranking(AGOP) ∪ {FLAT}`. A hallucinated SHORT when AGOP ranked only LONG and FLAT is replaced with FLAT. Hallucinations pointing outside the decision space are treated as no decision at all.
The verifier runs before the broker. The trade does not happen if the verifier disagrees.
### STIRPES observes without feeding back
The optional STIRPES module classifies the *shape* of JANUS's decisions. It extracts a fingerprint per tick — AGOP ranking, survivor set, topological classes, lower confidence bounds, composite scores, Nash strategies, module contributions, verdict — and commits a hash to a settlement layer.
STIRPES is unidirectional. It reads from the orchestrator, writes to the chain, never writes back. The orchestrator does not import STIRPES. Delete the STIRPES directory and the pipeline still runs.
A system that trained on its own classification would collapse onto the dominant clade: every iteration reinforces past behaviour, fingerprints cluster tighter, classification grows more confident, the fixed point is a strategy producing one decision forever. STIRPES prevents this by never feeding back. The chain is a one-way interface between the classification and everyone who queries it.
The record is a public good. Anyone can query which clades exist, how many ticks fall in each, how the topology of the strategy's decisions evolves over time. JANUS is not the beneficiary.
---
## Two optional layers
**Quantum econophysics.** Two modules run on IQM Resonance when a token is configured, fall back to Qiskit Aer when Qiskit is installed, fall back to exact classical evolution otherwise. The tunneling module encodes the nearest heavy-volume barrier as a potential on a discretized Baaquie Hamiltonian and patches AGOP's barrier axis from the resulting tunneling probability. The herding module encodes cross-asset return correlations as an Ising cost Hamiltonian and runs QAOA to measure the magnetization order parameter, which becomes a risk multiplier.
On four to eight qubits the classical fallback is faster than IQM and produces the same result. The quantum path matters when the circuit exceeds classical matrix exponentiation, beyond current NISQ coherence. The modules are included because the algorithms are correct and the physical interpretation is meaningful, not because they beat the classical fallback today.
**Opportunity modules.** Four modules invert the interpretation of KAIROS anomalies and Causalitybot horizons. Where the dampening modules treat these signals as reasons to trade smaller, the opportunity modules treat them as reasons to trade at all. They patch AGOP's axes so directional actions rank higher when a high-conviction, low-downside opportunity qualifies, gated on a downside score. A synthesizer reads all three and produces a consensus context for the LLM.
This is where the system's most interesting behaviour lives, and where the false-positive risk is highest. The downside gating protects against dangerous environments but not against false signals in safe ones.
---
## What this is not
Not an investment product. Not a signal service. No token, no presale, no subscription. The GitHub links are the only links.
Not a claim of profitability. The system ships a paper broker. It has been tested against synthetic snapshots and reference instances. It has not been tested against live market data. Adversarial order-book behaviour is unknown.
Not a "trustless AI." No ZK proof of LLM correctness exists — nobody has solved that problem. The claim is narrower: the LLM cannot exceed its authority, and the audit log records what it did.
Not a replacement for judgement. The deterministic layers do the arithmetic; the LLM does the interpretation; the verifier enforces the boundary. The inputs are still yours. Miscalibrated AGOP axes produce wrong rankings. Wrong KAIROS cycles produce wrong residuals. The stack makes wrongness auditable, not impossible.
---
## Start here
`janus/contracts.py` — the nine invariants and the `verify_trade_intent` decorator. The docstring says exactly what is checked and what happens when a check fails.
`janus/orchestrator.py` — the pipeline. `_decide` runs the phases and the LLM; `tick` populates the audit record and hands off to STIRPES.
`janus/stirpes/README.md` — the unidirectionality proof. Short. The recorder accepts AGOP output and module contexts, returns a hash, nothing else. No core file imports STIRPES. The import graph is acyclic with STIRPES as a sink.
Run with `python run.py` — FastAPI server with a browser UI on `127.0.0.1:8400`. Seeds a synthetic snapshot; "Run AGOP" shows which modules fired, which verdict was produced, what the LLM did with the bound. No LLM key required — the deterministic layers alone produce a full audit.
---
## Summary
Four repositories, one stack. A decision engine that refuses a convenient capacity parameter. An anomaly detector that does not pretend to learn. A causal reader that produces a thesis with executable content. An orchestrator that gives the LLM exactly one authority — reduce, never increase — and enforces it with nine runtime invariants. An optional observation layer that classifies decision shape and commits it to a chain without feeding back.
Whether it makes money is a separate question. What it can prove is that the LLM cannot lose the account by hallucinating a size larger than the risk engine authorised.
-
https://github.com/starwalkerz/AGOP-
https://github.com/starwalkerz/kairos-
https://github.com/starwalkerz/Causalitybot-
https://github.com/starwalkerz/janusRead the code.
