A trading-signal library that ships a knowledge graph of itself.
264 trading signal functions (128 TRIGGER, 136 FILTER) and 86 technical indicator classes, every one with a machine-readable docstring — formula, inputs, parameters with ranges and defaults, typed outputs with units, and warmup.
How it is built, stored and searched is drawn in docs/architecture/ — provenance, the node and
edge schema, the search corpus, find(), ask(), both search indices and how they are
fused, and the three traversals that are easy to confuse.
And a knowledge graph — 739 nodes and 2420 edges, with two halves on one schema. One is compiled from the source above: what each computation is, what it measures, what it reads, and what part it plays. That half is exact, because it is read from the code rather than extracted from prose. The other is the trading knowledge base — market structure, instruments, risk, chart patterns, quantitative method — ingested from its eight chapters as nodes and edges beside them.
The join is what makes either half worth querying: procedure:atr-based-stop is a rule the risk
chapter states, and it uses an indicator the code defines, so one query crosses from why to
what it computes.
The point is the second thing. A library of 264 functions is only useful if you can find the right
one, and grep cannot answer "which indicators produce a bounded oscillator", "what reads RSI's
third output", or "is there already a signal for this". The graph can, and the answers are facts
about the code as it is.
The bundled viewer (python -m mangrove_kb.viz): click any node to read what it computes and walk
its edges. What each part does.
- Install
- Quick start
- Skill & graph tools
- The model in 30 seconds
- The viewer
- What is in the graph, and what is not
- Repository structure
- Development
- License
- Contributing
- Links
pip install mangrove-kbPython 3.10+. The graph, both search indices, the agent skill and the viewer all ship inside the
wheel, so KnowledgeGraph.load() needs no network and no configuration.
ask() works out of the box on the LSA index. Its second index — a pretrained encoder, worth 13/25
to 18/25 — needs the semantic extra to embed a question: onnxruntime and tokenizers, no
torch. The ONNX export of the encoder ships inside the wheel, so nothing is fetched at install time
either: mangrove-kb is 285 MB installed, mangrove-kb[semantic] is 395 MB.
pip install "mangrove-kb[semantic]"A torch-backed fallback exists for a GPU host or a model swap: mangrove-kb[semantic-torch] pulls
sentence-transformers, and pip's default torch wheel bundles the whole CUDA stack --
mangrove-kb[semantic-torch] is 5,873 MB installed, 3.4 GB of it GPU support ask() never uses.
pip install torch --index-url https://download.pytorch.org/whl/cpu # 1,438 MB instead of 5,873
pip install "mangrove-kb[semantic-torch]"CPU or GPU is chosen there and cannot be declared by the package — there is no torch-cpu on PyPI,
and the +cpu wheels carry the same version from a different index. DenseIndex.model tries the
ONNX path first regardless of which extra is installed, so semantic-torch alone still answers the
same 18/25, by falling back to it. Without either extra, ask() answers on one index rather than
two; nothing raises.
from mangrove_kb.graph import KnowledgeGraph
kg = KnowledgeGraph.load()
kg.stats() # counts + every value a filter will accept
kg.find("divergence") # search name, abbreviation, summary, authored detail
kg.find(kind="momentum", role="trigger") # by what it measures AND the part it plays
# each hit shows its params (default/min/max)
kg.get("rsi_oversold") # formula, params, typed outputs, warmup
kg.ask("how far away from my entry should the stop go") # a QUESTION, not a termfind() matches the words you use. ask() matches what you mean — it seeds from two indices, one
built from this corpus and one from a pretrained sentence model, fuses them by reciprocal rank, and
walks a hop along the edges. Every row carries reached: which seed it came from, how far, along
which relation, and that edge's own reason. Measured on twenty-five questions phrased the way a
trader asks them, find() answers 5 and ask() answers 18.
stats() first, always. It returns the complete vocabulary every other call accepts — relations,
classes, roles, statuses, input columns, output units — so you never have to guess a name. Filters
that take a vocabulary raise and list the legal values rather than returning an empty result you
would read as "there are none".
kg.neighbors("procedure:indicator-rsi", relation="uses", direction="in", limit=None)
# every signal that reads RSI -- and each edge says WHICH output it readskg.outputs(bounded=True, kind="oscillator", limit=None) # 48 outputs, each with units and range
kg.outputs("histogram") # who produces one -- MACD, and only MACDoutputs() indexes values rather than nodes: one row per output, each naming its producer. It
answers "what can I plot on one panel" — which get() can only answer one node at a time, and
which resolve() cannot answer at all, since histogram is nobody's node name.
kg.all_paths("adosc_bearish", "momentum")
# adosc_bearish --about--> momentum the claim
# adosc_bearish --uses--> indicator-adosc --instance-of--> momentum the reasonfrom mangrove_kb import RuleRegistry, sample_ohlcv
from mangrove_kb.signals import momentum # import the class module to register it
node = kg.get("procedure:signal-adosc-cross-down")
RuleRegistry.evaluate({"name": node["name"], "params": {"fast": 3, "slow": 10}}, sample_ohlcv())A node's name is the registered signal name. That join is what makes this a map of a runnable
library rather than an encyclopedia.
python -m mangrove_kb.viz > graph.htmlOne self-contained file — no CDN, no build step, no network.
Two documents ship inside the wheel, so an agent that installs the package has them without fetching anything:
| what it is | |
|---|---|
SKILL.md |
the reference for which call — the two axes, the rules of use, and a question→call table |
GUIDE.md |
the reference for what a whole job looks like — sixteen tasks end to end, with real output and the trap in each |
Both are executable documentation: every example in them is re-run by the test suite against the committed graph, so an example that drifts fails the build rather than misleading a reader.
mangrove_kb.graph.KnowledgeGraph is the whole query surface:
| question | call |
|---|---|
| what is in here at all? | stats() — always first; returns every value the other calls accept as a filter |
| what shapes can I even ask for? | schema() — the 12 (subject, relation, object) triples that actually occur |
| the user gave me a name, not an id | resolve("rsi_oversold"), or get(), which resolves too |
| is there already a signal for X? | find("keyword") — ranked by where it matched |
| a question in ordinary words, not a term | ask("how far should the stop go") — meaning over two indices, then a hop |
| everything of a class, or in a role, or both | find(kind=…, role=…) |
| what needs volume? what is retired? what takes a window? | find(requires=…), find(status=…), find(param=…) |
| everything under a subject, whatever kind | find(under="risk management") — Concepts, Procedures, Facts and Judgments together |
| what is claimed, and what to do about it | find(primitive="Fact"), find(primitive="Judgment") |
| what does this compute — formula, params, outputs? | get(id) — searches already show each hit's params |
| which values are bounded / in these units? | outputs(bounded=True, units=…) |
| what produces an output called X? | outputs("X") |
| what reads this indicator? what does this read? | neighbors(id, relation="uses", direction="in"|"out") |
| the neighbourhood around something | subgraph(id, radius=1) |
| how are these two related? | path(a, b) — one shortest route |
| every way they connect, and why | all_paths(a, b) — all routes, shortest first |
| now actually run what I found | RuleRegistry.evaluate({"name": node["name"], …}, df) |
Every bounded return states its own truncation. A Result carries total, truncated and a
note — a short list is never mistakable for a complete one, and limit=None gets everything.
Filters that take a vocabulary raise and name the legal values rather than returning an empty result
you would read as "there are none".
Every computation is classified on two independent axes, and they answer different questions.
| axis | relation | question | inherited? |
|---|---|---|---|
| class | instance-of (indicators) · about (signals) |
what character is this concerned with? | over kind-of, yes |
| role | has-role |
what part does it play in a strategy? | never |
The six classes — averaging, flow, momentum, oscillator, pattern, volatility — are
divisions of technical analysis by what a computation measures. They are kind-of technical
analysis, not kind-of Indicator, because they span both layers. Two more classes, social
and onchain, divide alternative data -- readings that are not the market's own price and
volume -- by what is read, and hang from concept:alternative-data beside technical analysis.
An indicator measures its class; a signal is about its class. Different claims, so different relations:
ADOSC --instance-of--> momentum it measures rate of change
adosc_bearish --about--------> momentum it is concerned with it...
adosc_bearish --uses---------> ADOSC ...because of what it reads
Momentum is defined as measuring rate of change. A signal emits a boolean and measures nothing, so it is not an instance — and keeping the two edges distinct is what lets the graph explain a classification instead of merely asserting it.
A role is not a type. filter is not a kind of signal; it is a part some signals play, and the
same computation could play another part in another strategy. So role is never inherited and never
appears as a class. (Grounded in Steimann, DKE 2000, and Guarino & Welty's OntoClean, CACM 2002.)
Seven relations in total: instance-of, kind-of, part-of, about, has-role, uses,
supersedes. kg.schema() lists the 12 (subject, relation, object) shapes that actually occur, so
you can plan a traversal against what exists rather than discovering emptiness one query at a time.
python -m mangrove_kb.viz > graph.html writes one self-contained page — no server, no build step,
no network — with the whole graph in 2D and 3D, filterable, searchable, and every node's authored
detail one click away.
| Pane | Where | What it holds |
|---|---|---|
| Rail | left | filters, by kind of node and kind of edge |
| Map | middle | 739 nodes, 2420 edges |
| Panel | right | everything the library records about whatever you clicked |
Click any node or edge to pin its detail. Everything authored is here — description, formula,
reference, usage_example — and inputs, parameters and outputs come as tables, each with its
type, default, units and range, rather than a wall of JSON.
Sections fold, and the choice sticks: fold Edges once and it stays folded on the next node.
Provenance & extras holds the module and a call you can copy.
Ranges are read carefully, because three different facts used to render identically:
| Shown | Means |
|---|---|
0 … 100 |
bounded both ways |
≥ 0 |
floored, no ceiling |
unbounded |
[-inf, inf] — stated, not missing |
true/false |
boolean, not a [0,1] interval |
not authored |
nobody has written the range down |
Two traps. warmup_bars is an expression in the node's own parameters (window * 3 - 1), so
evaluate it against the parameters you intend to use. And units are heterogeneous by design: a
percentage, a price and an index number are different things and are labelled differently.
Every heading carries a ? that says what that section holds, and so does every edge type — point at it, tab to it, or tap it:
Every name under Edges is a link: click it and the panel moves there, with a back button to
return. Edges are grouped incoming and outgoing, and each type asserts something different:
| Edge | Claim |
|---|---|
instance-of |
this indicator measures that family — RSI measures momentum |
about |
this signal is concerned with that family without measuring it |
uses |
this reads that one, and carries which of its outputs flow in |
has-role |
the part it plays in a strategy: trigger or filter |
part-of |
a component of the other |
kind-of |
a subtype of the other |
instance-of and about are the pair to keep straight. An indicator produces the quantity, so it is
an instance of the family; a signal emits a boolean, so it is about the family instead — and the
uses edge beside it is the reason.
739 nodes at once is a picture, not an answer. show only keeps part of the graph around the
selected node, and the choices combine — neighbors + ancestors gives you both:
| Keeps | |
|---|---|
| everything | no trim |
| neighbors | one hop, in or out |
| descendants | everything built on this node |
| ancestors | everything this node is built from |
The count on each choice says how many nodes you would be left with before you click, and a
choice that would leave a single node is disabled. show or hide does the same one edge type at a
time, and its number is exact: hide uses on RSI and the eight signals that read it go, and nothing
else does.
The two compose — an edge type set to hide is dropped from the lineage walk as well, so the counts
above change to match. A bar over the map says how much is in view and how to get back; Esc clears
it, and clearing returns the view you had rather than refitting the whole graph.
Hiding a hub can leave a few nodes floating with nothing visibly joining them. That is honest: the thing that connected them is the thing you hid.
Nodes group by ontology primitive, edges by relation category, and each splits into the
derived kind beneath it — so signal and indicator are separable inside Procedure, and about
is separable from has-role inside descriptive.
Sub-kinds are shades of their parent's hue, never new colours: every dot in that group is a procedure, and the darker teal is the 77 indicators among them.
Parent and child are AND-ed. Unticking Procedure hides every procedure whatever the children
say, and the children grey out to show why — so the canvas can never empty for a reason that is not
visible in the rail.
Density spreads or tightens the layout. Labels switches between always / never / on hover / on zoom — at 739 nodes, off is often clearer than on.
Search reads every authored field, not just names — formula, interpretation, applications, and the names and descriptions of inputs, params and outputs.
Results rank by where the query hit, and the badge says which: NAME first, then ABBREV,
SUMMARY, DETAIL. So the thing actually called "divergence" comes before the things that merely
mention it, and the long tail costs you nothing.
This is the same ranking kg.find() uses — SEARCH_TIERS is exported from Python into the page
rather than reimplemented in JS, and a test asserts the two agree on real queries.
The same graph, same filters, same inspector — drag to rotate, scroll to zoom, right-drag to pan. In either view, double-click a node to hide or show what hangs off it, which is how you make a hub with 234 signals attached readable.
A green ring marks the selected node; a yellow ring marks a deprecated one — it still runs,
it just has a canonical replacement. Nothing else is ringed: 333 of 739 nodes are ratified, so
marking that would be decoration rather than information.
Light, dark and follow-the-system are top right, and the choice is remembered.
The knowledge half. All eight knowledge-base chapters are in the graph as nodes and edges, not
as documents: 202 Concepts (what a market is made of), 397 Procedures (of which the bare
procedure:* ones are formulas a chapter states and nothing implements), 74 Properties, and — the
two worth knowing about — 23 Facts and 16 Judgments. A Fact holds what is true of a subject,
a Judgment what to do about it. They are separate primitives because they answer to different
standards: a Fact is settled by measurement, a Judgment by argument.
kg.find(under="risk management", limit=None) # 74 nodes, every primitive
kg.find(under="risk management", primitive="Judgment") # 5 -- what to actually do
kg.neighbors("concept:market-impact", relation="about", direction="in")
# fact:square-root-market-impact-rule · procedure:almgren-chriss-market-impact-modelA statement lives in exactly one place. Until it concerns a particular node it sits in a Fact or
Judgment; once it earns an about edge it moves onto that edge as its why — so the reason an
answer is an answer travels with the connection, not in a list somewhere else.
The library half. Of 264 registered signals, 234 are modelled in the graph, along with 77 of the 86 indicator classes. That gap is deliberate:
- Frame-based signals with no indicator beneath them — a signal reading raw price with no measurement in between has no class to derive, and would sit in the graph as an unclassifiable node.
- Verdict indicators — SuperTrend, PSAR, ATRTrailingStop, Divergence, TTMSqueeze, MultiTFTrend.
Their outputs are verdicts, not measurements: a direction, a flip flag, a boolean. An indicator
measures; these decide. Each is kept, deprecated, for anything already calling it, and all but
ATRTrailingStop have a measurement class in the graph in its place (
SuperTrendBands,ParabolicSAR,SwingDelta,SqueezeDepth,MultiTFSlope) with the decision moved into the signals. ATRTrailingStop is a trade-management rule, not an indicator; its four signals stay registered and deprecated because stored strategies name them. - Alternative-data signals that compute inline - the ten older on-chain signals (Nansen-sourced
columns) and the ten DeFi Pro signals read a data column directly rather than through an
indicator, so the builder has no class to derive and they stay out of the graph. The four
enabled signals that read an alternative-data indicator (
social_price_divergence, an exit for long positions, and the three X attention signals) are modelled under thesocialclass. The five livex_*rules are also defined here and modelled as live X provider rules, with an explicit social class and provider contract rather than an invented indicator. - Signals disabled for new strategies - four Deep42 social signals (
social_sentiment_surge,social_sentiment_capitulation,social_crowd_bullish,social_crowd_cooling) and the two Solana holder signals (holder_growth_trend,whale_share_divergence) lost to price-filtered references in strategy backtests. They stay registered and deprecated because stored strategies name them; each docstring'sDisabled-Reasonhas the numbers.
The live X rules preserve their existing names, parameters and mention-volume thresholds.
The consumer calls mangrove_kb.signals.social.configure_x_provider(factory) with its lazy
provider factory. Importing the package makes no provider request. Historical evaluators call
RuleRegistry.validate_evaluation_mode(rule, "historical") before replay; a live X reading
cannot stand in for a past bar. RuleRegistry.evaluate defaults to mode="historical" and raises
LiveSignalNotAllowed for a live rule; a live caller passes mode="live". Runtime descriptors and graph nodes expose this distinction.
The graph is regenerated from a clean tree on every build, and a test rebuilds it into an empty path and diffs against the committed file — so it cannot drift from the code it describes.
Renames are never breaking. A signal's registered name is the contract; a superseded duplicate
keeps working and carries a supersedes edge to its canonical replacement plus a deprecation
warning.
MangroveKnowledgeBase/
├── mangrove_kb/ ← the pip package
│ ├── graph.py ← the query library (stats · find · get · outputs ·
│ │ neighbors · subgraph · path · all_paths)
│ ├── registry.py ← RuleRegistry: evaluate a signal by name
│ ├── docstring_parser.py ← docstring → structured metadata
│ ├── signals/ ← 264 signal functions
│ ├── indicators/ ← 86 indicator classes
│ ├── viz/ ← the self-contained graph viewer
│ ├── data/ ← the graph, bundled at build time
│ └── skills/knowledge-graph/ ← SKILL.md + GUIDE.md, bundled at build time
├── ontology/
│ ├── build_signal_indicator_ontology.py ← the ONLY thing that writes the graph
│ └── signal-indicator-ontology.json ← the ontology of record
├── skills/knowledge-graph/ ← the agent skill and its guide (source of truth)
├── knowledge-base/ ← 11 trading-education documents
├── notebooks/ ← signal explorer + validation
├── data/ ← 7 sample OHLCV datasets
└── tests/ ← the suite
The graph is derived. Authored values live in docstrings; everything else is read from the code.
Never edit signal-indicator-ontology.json by hand — change the docstring or the builder and rebuild:
python ontology/build_signal_indicator_ontology.pypip install -e ".[dev]"
pytest tests/ -q
flake8 mangrove_kb/ --max-line-length=120Free for noncommercial use under the PolyForm Noncommercial License 1.0.0 — personal study, hobby projects, research, teaching, and use by charitable, educational, public-research and government organizations.
Commercial use requires a paid license. Using mangrove-kb in a product or service you sell, or internally in a for-profit business, needs one — contact support@mangrove.ai.
Releases published before this change remain under the MIT license they shipped with.
Mangrove is named after the mangrove tree — an ecosystem where everything is interconnected, resilient, and thriving. We think trading knowledge works the same way: the best strategies and the most reliable tools don't come from hoarding information behind paywalls, they come from a community that shares openly. If you want to contribute, join the discord and reach out to the team directly.
Part of the Mangrove ecosystem — join us on Discord.
The Mangrove app - try today for free, no subscription or payment required.
If you find this useful, please star the repo — it helps others discover it and keeps the project growing.






