Refract
GitHub

Refract

A traceable LLM agent that turns one news event into a grounded, personalised insight for a company, a sole proprietor, a self-employed person or a private individual.

Type
Pet project, open source
Status
Active, v0.2.0
Role
Built alone, end to end
Stack
Python, any OpenAI-compatible LLM
One beam of news. Point at it or tap it to refract it into what matters to each reader.

Example: one news event refracted through one reader

One piece of news means different things to different readers. Refract passes it through the profile of each one and splits it into what matters to them. Pick an example:

News

The central bank holds the key rate at 14%

Reader

A building-materials wholesaler with loans. A developer is its largest customer.

  1. Headline

    The 14% rate stays: cheaper loans and leasing are postponed

  2. Why it matters to you

    AI inference Debt service on loans and leasing will not get cheaper. cites products.loans

  3. House view

    Demo Bank view The rate stays at 14% until the end of 2026. p. 2 of the macro outlook

  4. What to do

    Discuss fixing the rate. Product: a fixed-rate loan. rule fix_rate fired

  5. Trace

    A rule check caught an invented “1.2 bn”, the agent revised, and the policy removed a product no rule allows.

From the project’s README. The bank, the company and every number are synthetic demo data.

How it works

  1. Profile

    Reads the subject: products, counterparties, tax regime, group.

  2. Tag the news

    Type, factors, NACE codes, countries and importance, if the event is not tagged yet.

  3. Plan

    Chooses 3–6 tool calls for this subject and this event.

  4. Run tools

    House view, research search, counterparties, the group, related news.

  5. Draft

    Writes the insight against a JSON schema.

  6. Attribute

    Fills in the features and sources the model left out.

  7. Self-check

    Rule checks, then a review by a second model. On errors it searches for more data, revises and checks again.

  8. Finalize

    Cuts unsupported statements, caps the impact, enforces the action policy, rewrites a rejected headline.

Every step is written to a trace you can read afterwards.

Every statement says where it came from

  • Fact

    Must cite a source.

  • House view

    Must cite the institution’s own research.

  • AI inference

    Must cite the features of the subject it is about.

  • Hypothesis

    Carries a caveat.

Code decides, not the model

  • Numbers that are not in the context are caught.
  • Feature keys the subject does not have are rejected.
  • The impact level is capped by a ceiling computed from how the subject is linked to the event.
  • A product is offered only when a policy rule fired on the subject’s features.
  • A prompt injection in the news cannot raise the impact or add a product.

Ways to use it

  • Console

    Pick a subject, read its feed, watch the agent work, ask follow-up questions, read the trace. Windows, macOS, Linux.

  • CLI

    analyze, feed, brief, chat and the evaluation commands.

  • Python API

    Refract.from_dir(...).analyze(...) returns the insight and its trace.

  • REST API

    OpenAPI docs and live progress over Server-Sent Events.

  • MCP server

    Exposes analysis, the feed and the trace to Claude Desktop, Cursor and other MCP clients.

  • News collector

    RSS and Atom feeds into deduplicated events, ranked per subject by code.

Try it without an API key

git clone https://github.com/Rinneway/refract.git
cd refract
uv sync --all-extras
uv run refract demo
uv run refract shell --demo

Demo mode replays recorded answers of real local models (qwen3.5:9b drafting, gemma4:12b reviewing); the checks, the ceiling and the policy run as live code.

Measured, with the caveats

A pilot on 8 synthetic pairs with local models and three LLM judges. Refract ships its own evaluation: nine ablations, two baselines, several judges, bootstrap confidence intervals.

Answers where a rule error reached the reader
Refract agent 0%
Single LLM call, same context 62%
  • No invented numbers reached the reader either.
  • On judge scores the agent beats a plain retelling, but not a single call with the same context.
  • The judges agree poorly with each other (κ 0.12–0.27) and there are no human labels yet. This is a pilot, not proof of quality.

Built alone

Design, agent, checks, retrieval, evaluation, CLI, API, MCP server, Docker, CI and documentation in two languages.

Refract grew out of my agent component in an earlier team project on news analytics. This repository is a standalone re-implementation: it contains none of that project’s data, only synthetic examples.

Tests
194
CI
Linux, Windows, macOS
Python
3.10+
License
MIT

See the code

Repository on GitHub README in Russian