Skip to main content

rungbot_research/
lib.rs

1//! `rungbot-research` — the weekly research pipeline behind `rungbot research`.
2//!
3//! Research only. Nothing here can place an order or reach a venue's private API:
4//! the crate holds no venue key and is not a dependency of the executor.
5//!
6//! The pipeline, stage by stage, all composing through one ledger file
7//! (`opportunity-ledger.json`) in a data directory:
8//!
9//! * [`oppscan`] — the technical half: CoinPaprika's whole market in one call, kept to a
10//!   tradable band and ranked by distance from the all-time high.
11//! * [`survivor`] — the bear/chop screen: a DefiLlama value index (fees, TVL, category),
12//!   a value-first selection, then web evidence and an LLM verdict per coin.
13//! * [`catalyst`] — the bull screen: web evidence of a forward catalyst, then an LLM
14//!   verdict per coin.
15//! * [`unlocks`] — a token-unlock calendar from DefiLlama's open dataset CDN.
16//! * [`theses`] — which of those runs in which market regime, and how it is titled.
17//! * [`report`] — reads the regime, runs the matching thesis, and writes one dated note
18//!   plus a short HTML email.
19//!
20//! Every outside call goes through a trait ([`Fetch`], [`Search`], [`Llm`],
21//! [`report::NoteSink`], [`report::Mailer`]) so the golden tests replay recorded
22//! responses and never touch the network. The real clients live in [`clients`].
23//!
24//! ## The LLM command
25//!
26//! No model provider is built in. You name a command in the config; the prompt goes to
27//! its stdin and its stdout is the answer. The command always gets a spend cap appended
28//! (`--max-budget-usd <N>` by default; both the flag and the amount are configurable,
29//! neither can be switched off), and nothing grants it extra permissions: whatever
30//! flags your tool needs, you write them into the command yourself.
31
32#![forbid(unsafe_code)]
33#![deny(clippy::all)]
34
35use std::io::Write;
36use std::path::{Path, PathBuf};
37
38pub mod catalyst;
39pub mod cli;
40pub mod clients;
41pub mod date;
42#[cfg(test)]
43mod golden_tests;
44pub mod oppscan;
45pub mod py;
46pub mod report;
47pub mod survivor;
48#[cfg(test)]
49mod testenv;
50pub mod theses;
51pub mod unlocks;
52
53pub use py::Json;
54
55/// The ledger every stage reads and writes.
56pub const LEDGER: &str = "opportunity-ledger.json";
57/// `SYMBOL -> {name, tvl, category, gecko_id, fees30d, revenue30d}` from DefiLlama.
58pub const VALUE_INDEX: &str = "value-index.json";
59/// `SYMBOL -> {slug, gecko_id}` for the unlock calendar.
60pub const UNLOCK_INDEX: &str = "unlock-index.json";
61
62/// The User-Agent the public data sources were read with.
63pub const UA_SCAN: &str = "oppscan/0.1";
64pub const UA_BROWSER_SCAN: &str = "Mozilla/5.0 oppscan";
65
66#[derive(Debug, Clone, PartialEq)]
67pub enum ResearchError {
68    /// A stage refused to run, with the message to print (exit 1).
69    Exit(String),
70    /// The configuration cannot do what was asked (exit 2).
71    Config(String),
72    /// A read, a parse or a write failed (exit 1).
73    Failed(String),
74}
75
76impl std::fmt::Display for ResearchError {
77    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
78        match self {
79            ResearchError::Exit(m) | ResearchError::Config(m) | ResearchError::Failed(m) => {
80                write!(f, "{m}")
81            }
82        }
83    }
84}
85
86impl std::error::Error for ResearchError {}
87
88pub type Result<T> = std::result::Result<T, ResearchError>;
89
90/// A keyless JSON GET.
91pub trait Fetch {
92    fn get_json(
93        &self,
94        url: &str,
95        user_agent: &str,
96        timeout_s: u64,
97    ) -> std::result::Result<Json, String>;
98}
99
100#[derive(Debug, Clone, PartialEq)]
101pub enum SearchError {
102    /// No search key is configured. Each stage words this itself.
103    NoKey,
104    /// The call failed; the text is `Kind: message`.
105    Failed(String),
106}
107
108/// A web search: one JSON request body in, the parsed JSON response out.
109pub trait Search {
110    fn search(&self, body: &str) -> std::result::Result<Json, SearchError>;
111}
112
113/// An LLM behind a command: the prompt in, raw stdout out. An `Err` is `Kind: message`.
114pub trait Llm {
115    fn ask(&self, prompt: &str) -> std::result::Result<String, String>;
116}
117
118/// Where a stage prints. The real one is stdout/stderr; tests capture it.
119pub trait Console {
120    fn out(&mut self, line: &str);
121    fn err(&mut self, line: &str);
122}
123
124/// stdout and stderr, one `print` per call.
125pub struct StdConsole;
126
127impl Console for StdConsole {
128    fn out(&mut self, line: &str) {
129        let mut o = std::io::stdout().lock();
130        let _ = writeln!(o, "{line}");
131    }
132    fn err(&mut self, line: &str) {
133        let mut e = std::io::stderr().lock();
134        let _ = writeln!(e, "{line}");
135    }
136}
137
138/// Everything a stage printed, for tests.
139#[derive(Debug, Default, Clone)]
140pub struct BufConsole {
141    pub out: String,
142    pub err: String,
143}
144
145impl Console for BufConsole {
146    fn out(&mut self, line: &str) {
147        self.out.push_str(line);
148        self.out.push('\n');
149    }
150    fn err(&mut self, line: &str) {
151        self.err.push_str(line);
152        self.err.push('\n');
153    }
154}
155
156/// The data directory the ledger and indexes live in.
157#[derive(Debug, Clone, PartialEq)]
158pub struct Paths {
159    pub dir: PathBuf,
160}
161
162impl Paths {
163    pub fn new(dir: impl Into<PathBuf>) -> Self {
164        Paths { dir: dir.into() }
165    }
166    pub fn ledger(&self) -> PathBuf {
167        self.dir.join(LEDGER)
168    }
169    pub fn value_index(&self) -> PathBuf {
170        self.dir.join(VALUE_INDEX)
171    }
172    pub fn unlock_index(&self) -> PathBuf {
173        self.dir.join(UNLOCK_INDEX)
174    }
175}
176
177/// Read and parse a JSON file.
178pub fn read_json(path: &Path) -> Result<Json> {
179    let text = std::fs::read_to_string(path)
180        .map_err(|e| ResearchError::Failed(format!("cannot read {}: {e}", path.display())))?;
181    py::parse(&text)
182        .map_err(|e| ResearchError::Failed(format!("{} is not valid JSON: {e}", path.display())))
183}
184
185/// Write `value` as indented JSON, through a temp file and a rename so a reader never
186/// sees half a file.
187pub fn write_json(path: &Path, value: &Json) -> Result<()> {
188    if let Some(parent) = path.parent().filter(|p| !p.as_os_str().is_empty()) {
189        std::fs::create_dir_all(parent).map_err(|e| {
190            ResearchError::Failed(format!("cannot create {}: {e}", parent.display()))
191        })?;
192    }
193    let tmp = path.with_extension(format!("json.tmp.{}", std::process::id()));
194    std::fs::write(&tmp, py::dumps_indent(value, 2))
195        .map_err(|e| ResearchError::Failed(format!("cannot write {}: {e}", tmp.display())))?;
196    std::fs::rename(&tmp, path).map_err(|e| {
197        let _ = std::fs::remove_file(&tmp);
198        ResearchError::Failed(format!("cannot replace {}: {e}", path.display()))
199    })
200}
201
202/// The ledger as a list of records.
203pub fn read_ledger(paths: &Paths) -> Result<Vec<Json>> {
204    match read_json(&paths.ledger())? {
205        Json::Arr(a) => Ok(a),
206        _ => Err(ResearchError::Failed(format!(
207            "{} is not a list",
208            paths.ledger().display()
209        ))),
210    }
211}
212
213pub fn write_ledger(paths: &Paths, cands: &[Json]) -> Result<()> {
214    write_json(&paths.ledger(), &Json::Arr(cands.to_vec()))
215}
216
217/// Indices of `cands` ordered by `dislocation_score`, deepest first; equal scores keep
218/// their ledger order.
219pub fn by_dislocation(cands: &[Json]) -> Vec<usize> {
220    let mut idx: Vec<usize> = (0..cands.len()).collect();
221    let score = |i: usize| {
222        cands[i]
223            .get("dislocation_score")
224            .and_then(Json::as_f64)
225            .unwrap_or(0.0)
226    };
227    idx.sort_by(|&a, &b| {
228        score(b)
229            .partial_cmp(&score(a))
230            .unwrap_or(std::cmp::Ordering::Equal)
231    });
232    idx
233}
234
235/// The shared pieces of a stage that reaches outside.
236pub struct Ctx<'a> {
237    pub paths: Paths,
238    pub fetch: &'a dyn Fetch,
239    pub search: &'a dyn Search,
240    /// `None` when no LLM command is configured; the synthesis stages refuse to run.
241    pub llm: Option<&'a dyn Llm>,
242    /// The local calendar date the run is dated with.
243    pub today: date::Date,
244}
245
246/// The message a synthesis stage stops with when no LLM command is configured.
247pub fn no_llm() -> ResearchError {
248    ResearchError::Config(
249        "no LLM command configured: set research.llm.command in the config \
250         (the spend cap research.llm.max_budget_usd is always passed to it)"
251            .into(),
252    )
253}