Skip to content

About

Open-source trading signals and technical indicators for quantitative finance and algorithmic trading

Resources

Stars

9 stars

Watchers

1 watching

Forks

Repository files navigation

MangroveKnowledgeBase

A trading-signal library that ships a knowledge graph of itself.

PyPI version License: PolyForm Noncommercial 1.0.0 Python 3.10+ Graph and both search indices ship in the wheel Graph: 739 nodes, 2420 edges Agent skill + guide

Discord PyPI Downloads

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 knowledge graph viewer, with the rsi_oversold signal selected

The bundled viewer (python -m mangrove_kb.viz): click any node to read what it computes and walk its edges. What each part does.

Contents


Install

pip install mangrove-kb

Python 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.


Quick start

1 · Ask the graph before you read the source

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 term

find() 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".

2 · Work out what a change breaks

kg.neighbors("procedure:indicator-rsi", relation="uses", direction="in", limit=None)
# every signal that reads RSI -- and each edge says WHICH output it reads

3 · Ask about the values, not the nodes

kg.outputs(bounded=True, kind="oscillator", limit=None)   # 48 outputs, each with units and range
kg.outputs("histogram")                                   # who produces one -- MACD, and only MACD

outputs() 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.

4 · Explain an answer

kg.all_paths("adosc_bearish", "momentum")
# adosc_bearish --about--> momentum                                  the claim
# adosc_bearish --uses--> indicator-adosc --instance-of--> momentum  the reason

5 · Run what you found

from 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.

6 · View it in a browser

python -m mangrove_kb.viz > graph.html

One self-contained file — no CDN, no build step, no network.


Skill & graph tools

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.

The tools

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".


The model in 30 seconds

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.


The viewer

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

The inspector — what a node actually carries

The inspector showing BollingerBands: folded sections, then Inputs, Parameters and Outputs as tables

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:

The ? beside the uses row, with its explanation shown to the left of the panel

Following an edge

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.

The Action panel — trim the graph to the question

The Action section with neighbors and ancestors both selected, and a bar over the map reading 'showing 17 of 714'

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.

The rail — two-level filters

The filter rail: Procedure splits into signal, formula and indicator; Concept into entity type, class and domain; and the knowledge half as Fact and Judgment

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 — ranked, and it tells you why

Search results for 'divergence', badged NAME and SUMMARY by which field matched

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.


3D

The same graph in 3D

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.


What is in the graph, and what is not

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-model

A 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 the social class. The five live x_* 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's Disabled-Reason has 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.


Repository structure

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.py

Development

pip install -e ".[dev]"
pytest tests/ -q
flake8 mangrove_kb/ --max-line-length=120

License

Free 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.


Contributing

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.

Links

GitHub Issues.

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.

About

Open-source trading signals and technical indicators for quantitative finance and algorithmic trading

Resources

Stars

9 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages