# Syntology

> The modern ontology for AI: a provenance-tagged knowledge graph indexing
> AI/ML research — papers, authors, citations, code implementations, and
> peer reviews — built for real-time traceability from publication to
> graph. Every edge in the graph carries its own source (deterministic
> extraction vs. LLM-derived, with a confidence score for the latter);
> nothing is presented as fact without a way to check where it came from.

Syntology is privately held, pre-launch, and the graph API is live and
open at the URL below — no waitlist, no account, no card; a trial token
gets any agent or script querying in one request. This file describes
what is actually true today (updated 2026-08-23), not a roadmap
presented as current state — see the "Not yet live" section for what
the public pages illustrate but don't yet serve live.

## Primary

- [Syntology](https://syntology.ai/): the live site — project overview,
  and a small real-time widget (paper/author/repo counts queried live
  from the graph, refreshed every 10 minutes) that is the one part of
  the marketing pages backed by live data end to end.
- [/developers](https://syntology.ai/developers): **start here if you are
  an agent or a script, not a human browsing.** Documents the trial-token
  flow below in full, with a working curl example.
- [/about](https://syntology.ai/about): who built this and why.
- [/attribution](https://syntology.ai/attribution): upstream sources and
  their licence terms. Paper-to-code links in this graph are derived in
  part from the archived Papers with Code dataset (snapshot 2025-07-28,
  `pwc-archive/links-between-paper-and-code` on Hugging Face), used under
  CC BY-SA 4.0 and modified. If you redistribute those rows onward, that
  licence travels with them; this page carries the full attribution.
- [llms-full.txt](https://syntology.ai/llms-full.txt): the extended
  reference, including the reviewer-bot API's full request/response
  contract (marked, honestly, as not yet deployed).

## What's real right now

- A Neo4j graph with `Paper`, `Author`, `CodeRepo`, `Review`, `Method`,
  `Dataset`, and `Concept` nodes, each edge carrying a `provenance` field
  naming its source (`deterministic:*`, `external:*` or `llm:*`).
  `CITES` and `PROPOSES` carry a confidence score. `AUTHORED_BY`,
  `IMPLEMENTED_BY` and `DISCUSSES` return `confidence: null` -- for the
  first two that is correct (a header parse and a published listing are
  mechanisms, not probabilities, and a fabricated 1.0 would be worse than
  a null), and for `DISCUSSES` it is a real gap in the extractor's output.
  Every null claim carries a `confidence_basis` string saying which of the
  two it is, so you never have to guess. This paragraph used to promise a
  score on every LLM-derived edge; it was not true of `DISCUSSES`, and
  saying so is cheaper than the alternative.
- **A real, queryable graph API, reachable two ways:**
  - **Human/browser**: `GET https://syntology.ai/api/graph/ask?q=...`,
    Cloudflare-Turnstile-gated (solve the challenge on `/demo` first).
  - **Agent/script**: get a short-lived trial bearer token —
    `POST https://syntology.ai/api/oauth/trial/token` — then either call
    `GET /api/graph/ask` with `Authorization: Bearer <token>`, or use the
    MCP server directly (Streamable HTTP transport,
    `https://syntology.ai/mcp` — see `/developers` for the exact request
    shapes and OAuth discovery metadata at
    `/.well-known/oauth-authorization-server`). Two limits apply at once
    and they are different numbers: **20 queries per token** (30-minute
    expiry) and **50 free questions per IP address per day**. The token
    budget comes back in the mint response; both come back as response
    headers (`X-Token-Queries-Remaining`, `X-Free-Questions-Remaining`).
    A decline or an empty result still counts against the daily
    allowance — it costs a real graph round trip — but never against a
    paid balance. No signup, no card. Listed on the official MCP registry
    (`ai.syntology/graph`).
  - **The MCP server exposes 17 tools, not just one**: `graph_ask` (any
    natural-language question, same pipeline the REST endpoint uses)
    plus 16 typed tools for callers that want a direct resolve-and-call
    instead of NL parsing — `get_paper`, `get_code_for_paper`,
    `get_harvested_code_for_paper`, `get_code_for_method`, `get_code`,
    `get_citation_path`,
    `get_concepts_for_paper`, `get_reviews_for_paper`,
    `get_papers_by_author`, `get_papers_by_institution`,
    `get_reference_implementation`, `list_reference_implementations`,
    `compose`, `assembly`, `explore_paths`, and `have`. All 17 are
    callable on the same free trial token; nothing here is withheld from it.
  - **`get_harvested_code_for_paper`** lists the functions we lifted out of
    a paper's own repositories and says, for each, whether it ran in our
    sandbox. Every entry names the repository and file it was harvested
    from for THIS paper, its role (canonical, reimplementation, ...) and
    whether that repository's licence lets us serve the code. When the
    same code was first harvested from another repository, the entry says
    so rather than showing that repository's path as this paper's.
  - **`get_code`** fetches one code sample by its identity (`code_sha256`)
    with every judgement recorded against it: verification level and
    report, measured behaviour, and whether that behaviour fingerprint is
    `degenerate` (the test inputs came back unchanged or constant, so it
    cannot distinguish the code). Code from a repository whose licence does
    not permit redistribution is returned as a pointer to its source, not
    inline.
  - **`have`** answers "do you hold code for this?" before you spend
    anything, and does not draw down your query budget. Method name,
    arXiv id or paper title in; `verified_code` / `unverified_code` /
    `no_code` / `unknown_name` out. A `no_code` asserts absence only for
    the exact name it resolved; `unknown_name` asserts nothing at all and
    lists near matches.
  - **`assembly`** returns a paper's claimed method as typed, wired,
    swappable bricks with the assembly's own verification level.
    **`explore_paths`** returns a multi-hop traversal RECORD (seeds, kept
    edges, provenance, where fan-out was sampled) — candidates to confirm
    with the typed tools, never an answer.
  - **`get_reference_implementation`** (new 2026-08-26): a verified,
    self-contained Python reference implementation of a named method,
    generated from the method's own paper and machine-verified —
    verification levels V0 (imports) through V3 (two independently
    generated implementations agree behaviorally AND paper-derived
    property tests pass on both). Refuses rather than serving below
    your `min_level` floor (default 2). Reference code with `llm:`
    provenance and a measured verification level, attributed to its
    source paper — not audited production code.
  - **`list_reference_implementations`** (new 2026-08-30): browse the
    verified-code index — method name, origin paper, publication year,
    verification level, language, no source attached — before calling
    `get_reference_implementation` for one by name. Optional `query`
    substring-matches method name and paper title; `min_level` filters
    the floor; `limit` caps the response (default 50, max 200). The
    human-facing equivalent is [/code](https://syntology.ai/code).
  - Every answer cites the real graph edge(s) it's grounded in — see
    `answer_kind`/`claims`/`paths` in the response shape.
  - **Optional `code_samples=true`** (REST query param, or the
    `code_samples` argument on the MCP `graph_ask` tool; default false):
    attaches declared code repositories for every paper in the answer,
    under a `code_samples` key with an honest maturity label
    (`"status": "declared_links_only"`) and per-row `provenance`. The
    payload will grow richer (role-classified repos, entry points)
    without a breaking change.
  - **Optional `strict_provenance=true`** (same two call sites): drops
    every `llm:`-provenance claim from the answer, keeping only
    `deterministic:`/`derived:`/`external:` ones — for a caller that
    wants zero model-derived claims even at the cost of a thinner
    answer. The drop is always disclosed in the response's `gaps` field,
    never silent.
- Peer reviews are ingested raw, per reviewer, never averaged into a
  single score, and never carry a reviewer-identity field — reviewer
  anonymity is preserved by design, permanently, not as a gap to fill in
  later.
- Corpus coverage: NeurIPS/ICML/ICLR (2020–2025), 25,045 papers, is what's
  live in the graph today — real, queryable, fully covered by Method/
  Concept extraction (tens of thousands of edges, run at full scale, not
  a pilot) plus a narrower, real, corroborated layer of method-to-method
  relationships (generalizes/improves-on/related-to/evaluated-on).
  CVPR/ICCV/ECCV, ACL/EMNLP/NAACL (incl. Findings tracks), and AAAI/IJCAI
  are being processed through the same pipeline (real corpus expansion,
  not paused) but are not yet loaded into the live graph — this file will
  say so the moment that changes, not before.

## Not yet live — described on the public pages as illustration, not data

- `/demo`, `/methodology`: interactive walkthroughs of the query
  experience and pipeline. Their headline numbers and the demo's six-paper
  example table are static illustrative content, not a live query against
  the graph — and technical note for any automated reader: that example
  content is rendered client-side by an embedded JS bundle, not present
  in the page's raw HTML, so a crawler that doesn't execute JavaScript
  will not see it. The live-data widget on these pages (paper/author/
  repo counts) is the one exception and is genuinely real-time. The real
  query pipeline described above under "What's real right now" is a
  separate, actually-live thing from this illustrative demo page — use
  the API, not this page, if you're an agent.
- `/ethos`: values and principles, static content.
- An LLM-generated peer-review tool is in active development and
  validated internally against real benchmarks (see llms-full.txt for
  its full request/response contract), but is not deployed anywhere
  publicly reachable yet.

## Contact

- Security: see `/.well-known/security.txt`.
- General: media@syntology.ai