Skip to main content

tpt_telos_codegen/
python.rs

1//! Python (with optional JAX) backend for tpt-telos.
2//!
3//! Generates Python `@dataclass`-based structs with runtime contract assertions
4//! and `satisfies_invariants()` methods, mirroring the Rust and Go backends.
5//! Functions carry runtime pre/post-condition `assert`s so contracts are
6//! enforced at every boundary crossing, even from uninstrumented callers.
7//!
8//! Activate with `@boundary(ml_training)`, `@boundary(python)`, or
9//! `@boundary(jax)`.  The JAX variant adds `import jax.numpy as jnp` and
10//! uses `jnp.int64` type hints.
11
12use std::collections::HashMap;
13
14use tpt_telos_parser::ast::*;
15
16use crate::{analyze_func, collect_types, InputParam, TypeFields};
17
18/// Python keywords that may not appear as unqualified identifiers.
19/// Telos identifiers that clash are suffixed with `_`.
20const PY_KEYWORDS: &[&str] = &[
21    "False", "None", "True", "and", "as", "assert", "async", "await", "break", "class", "continue",
22    "def", "del", "elif", "else", "except", "finally", "for", "from", "global", "if", "import",
23    "in", "is", "lambda", "nonlocal", "not", "or", "pass", "raise", "return", "try", "while",
24    "with", "yield",
25];
26
27fn py_safe(name: &str) -> String {
28    if PY_KEYWORDS.contains(&name) {
29        format!("{}_", name)
30    } else {
31        name.to_string()
32    }
33}
34
35/// Generate a full Python module source for the given telos modules.
36///
37/// `bodies` maps function names to their verified body statements.
38/// `use_jax` adds JAX/NumPy imports and type annotations.
39pub fn generate_python_package(
40    modules: &[&Module],
41    bodies: &HashMap<String, Vec<Stmt>>,
42    use_jax: bool,
43) -> String {
44    let mut out = String::new();
45    out.push_str("# Generated by tpt-telos. Do not edit by hand.\n");
46    out.push_str("# Mathematical contracts were verified by the tpt-telos SMT core.\n");
47    out.push_str("from __future__ import annotations\n");
48    out.push_str("from dataclasses import dataclass, field\n");
49    if use_jax {
50        out.push_str("import jax.numpy as jnp\n");
51    }
52    out.push('\n');
53
54    let mut all_types: TypeFields = HashMap::new();
55    for m in modules {
56        collect_types(m, &mut all_types);
57    }
58
59    for m in modules {
60        out.push_str(&generate_py_module(m, bodies, &all_types, use_jax));
61        out.push('\n');
62    }
63
64    out
65}
66
67fn generate_py_module(
68    module: &Module,
69    bodies: &HashMap<String, Vec<Stmt>>,
70    types: &TypeFields,
71    use_jax: bool,
72) -> String {
73    let mut out = String::new();
74    out.push_str(&format!(
75        "# ===== module {} (target: python) =====\n\n",
76        module.name
77    ));
78
79    let int_type = if use_jax { "jnp.int64" } else { "int" };
80
81    // Emit dataclasses for each struct type used in this module.
82    for (ty, fields) in types {
83        if fields.is_empty() {
84            continue;
85        }
86        out.push_str("@dataclass\n");
87        out.push_str(&format!("class {}:\n", ty));
88        for (f, fty) in fields {
89            let py_type = render_py_type(fty, int_type);
90            out.push_str(&format!("    {}: {} = 0\n", f, py_type));
91        }
92        out.push('\n');
93
94        // Emit invariant method if one exists.
95        for item in &module.items {
96            if let Item::Invariant(inv) = item {
97                if inv.name == *ty {
98                    let conds = inv
99                        .constraints
100                        .iter()
101                        .map(render_inv_py)
102                        .collect::<Vec<_>>()
103                        .join(" and ");
104                    out.push_str("    def satisfies_invariants(self) -> bool:\n");
105                    out.push_str(&format!("        return {}\n\n", conds));
106                }
107            }
108        }
109    }
110
111    // Emit standalone invariant methods for types not yet encountered above.
112    for item in &module.items {
113        if let Item::Invariant(inv) = item {
114            if !types.contains_key(&inv.name) {
115                // Invariant type has no fields referenced by functions — skip.
116                continue;
117            }
118        }
119    }
120
121    // Functions.
122    for item in &module.items {
123        if let Item::Func(f) = item {
124            let key = f.name.clone();
125            let stmts = bodies.get(&key).cloned().unwrap_or_else(|| f.body.clone());
126            out.push_str(&render_py_func(f, &stmts, types, int_type));
127            out.push('\n');
128        }
129    }
130
131    out
132}
133
134fn render_py_type(ty: &tpt_telos_parser::ast::Type, int_type: &str) -> String {
135    match ty {
136        tpt_telos_parser::ast::Type::Named(s) => match s.as_str() {
137            "Float32" => "float".to_string(),
138            "Float64" => "float".to_string(),
139            "Int" | "PositiveInt" => int_type.to_string(),
140            "Bool" => "bool".to_string(),
141            "String" => "str".to_string(),
142            other => other.to_string(),
143        },
144        tpt_telos_parser::ast::Type::Generic(name, args) => {
145            let args: Vec<_> = args.iter().map(|a| render_py_type(a, int_type)).collect();
146            format!("{}[{}]", name, args.join(", "))
147        }
148        tpt_telos_parser::ast::Type::Tuple(elems) => {
149            let elems: Vec<_> = elems.iter().map(|e| render_py_type(e, int_type)).collect();
150            format!("tuple[{}]", elems.join(", "))
151        }
152        tpt_telos_parser::ast::Type::Array(elem, len) => {
153            format!("list[{}]  # length {}", render_py_type(elem, int_type), len)
154        }
155        tpt_telos_parser::ast::Type::Slice(elem) => {
156            format!("list[{}]", render_py_type(elem, int_type))
157        }
158    }
159}
160
161fn render_py_func(f: &Func, stmts: &[Stmt], types: &TypeFields, int_type: &str) -> String {
162    let mut out = String::new();
163    let analysis = analyze_func(f, stmts, types);
164
165    // Build parameter list.
166    let mut params: Vec<String> = Vec::new();
167    for input in &analysis.inputs {
168        match input {
169            InputParam::Scalar { name } => {
170                params.push(format!("{}: {}", py_safe(name), int_type));
171            }
172            InputParam::Struct { name, ty, .. } => {
173                params.push(format!("{}: {}", py_safe(name), ty));
174            }
175        }
176    }
177
178    let ret = if analysis.scalar_out.is_some() {
179        format!(" -> {}", int_type)
180    } else {
181        " -> None".to_string()
182    };
183
184    // Docstring with contracts.
185    out.push_str(&format!("def {}({}){} :\n", f.name, params.join(", "), ret));
186    out.push_str("    \"\"\"\n");
187    for r in &f.requires {
188        out.push_str(&format!("    requires: {}\n", render_expr_py_doc(r)));
189    }
190    for e in &f.ensures {
191        out.push_str(&format!("    ensures:  {}\n", render_expr_py_doc(e)));
192    }
193    out.push_str("    \"\"\"\n");
194
195    // Precondition assertions.
196    for r in &f.requires {
197        let cond = render_expr_py(r);
198        let msg = render_expr_py_doc(r);
199        out.push_str(&format!(
200            "    assert {}, \"telos: precondition violated in `{}`: {}\"\n",
201            cond, f.name, msg
202        ));
203    }
204
205    // Capture old() values before the body runs.
206    let old_fields = collect_old_fields_py(f);
207    for (base, field) in &old_fields {
208        out.push_str(&format!(
209            "    __old_{}_{} = {}.{}\n",
210            py_safe(base),
211            field,
212            py_safe(base),
213            field
214        ));
215    }
216    if !old_fields.is_empty() {
217        out.push('\n');
218    }
219
220    // Body.
221    for stmt in stmts {
222        match stmt {
223            Stmt::MutateState(assigns) => {
224                for a in assigns {
225                    let lhs = render_assign_target_py(&a.target);
226                    let rhs = render_expr_py(&a.value);
227                    let op = match a.op {
228                        AssignOp::Set => "=",
229                        AssignOp::Add => "+=",
230                        AssignOp::Sub => "-=",
231                    };
232                    out.push_str(&format!("    {} {} {}\n", lhs, op, rhs));
233                }
234            }
235            Stmt::Assign(a) => {
236                let lhs = render_assign_target_py(&a.target);
237                let rhs = render_expr_py(&a.value);
238                let op = match a.op {
239                    AssignOp::Set => "=",
240                    AssignOp::Add => "+=",
241                    AssignOp::Sub => "-=",
242                };
243                out.push_str(&format!("    {} {} {}\n", lhs, op, rhs));
244            }
245            _ => {}
246        }
247    }
248
249    // Postcondition assertions.
250    if !f.ensures.is_empty() {
251        out.push('\n');
252    }
253    for e in &f.ensures {
254        let cond = render_ensures_py(e, &old_fields, f);
255        let msg = render_expr_py_doc(e);
256        out.push_str(&format!(
257            "    assert {}, \"telos: postcondition violated in `{}`: {}\"\n",
258            cond, f.name, msg
259        ));
260    }
261
262    // Return scalar output.
263    if let Some(ref outvar) = analysis.scalar_out {
264        out.push_str(&format!("    return {}\n", py_safe(outvar)));
265    }
266
267    out
268}
269
270/// Collect all `old(base.field)` references in a function's ensures clauses.
271fn collect_old_fields_py(f: &Func) -> Vec<(String, String)> {
272    let mut seen = std::collections::HashSet::new();
273    let mut out = Vec::new();
274    for e in &f.ensures {
275        collect_old_in_expr(e, &mut seen, &mut out);
276    }
277    out
278}
279
280fn collect_old_in_expr(
281    e: &Expr,
282    seen: &mut std::collections::HashSet<(String, String)>,
283    out: &mut Vec<(String, String)>,
284) {
285    match e {
286        Expr::Old(inner) => {
287            if let Expr::Field { base, field } = inner.as_ref() {
288                if seen.insert((base.clone(), field.clone())) {
289                    out.push((base.clone(), field.clone()));
290                }
291            }
292        }
293        Expr::Bin { lhs, rhs, .. } => {
294            collect_old_in_expr(lhs, seen, out);
295            collect_old_in_expr(rhs, seen, out);
296        }
297        Expr::Unary { expr, .. } => collect_old_in_expr(expr, seen, out),
298        _ => {}
299    }
300}
301
302fn render_assign_target_py(e: &Expr) -> String {
303    match e {
304        Expr::Var(v) => py_safe(v),
305        Expr::Field { base, field } => format!("{}.{}", py_safe(base), field),
306        _ => "?".to_string(),
307    }
308}
309
310fn render_ensures_py(e: &Expr, old_fields: &[(String, String)], _f: &Func) -> String {
311    render_expr_py_with_old(e, old_fields)
312}
313
314fn render_expr_py_with_old(e: &Expr, _old_fields: &[(String, String)]) -> String {
315    match e {
316        Expr::Old(inner) => {
317            if let Expr::Field { base, field } = inner.as_ref() {
318                format!("__old_{}_{}", py_safe(base), field)
319            } else {
320                render_expr_py_with_old(inner, _old_fields)
321            }
322        }
323        Expr::Int(n) => n.to_string(),
324        Expr::Var(v) => py_safe(v),
325        Expr::Field { base, field } => format!("{}.{}", py_safe(base), field),
326        Expr::Unary { op, expr } => match op {
327            UnOp::Neg => format!("-({})", render_expr_py_with_old(expr, _old_fields)),
328        },
329        Expr::Bin { op, lhs, rhs } => {
330            let l = render_expr_py_with_old(lhs, _old_fields);
331            let r = render_expr_py_with_old(rhs, _old_fields);
332            let s = py_bin_op(*op);
333            format!("{} {} {}", l, s, r)
334        }
335        other => render_expr_py(other),
336    }
337}
338
339fn render_expr_py(e: &Expr) -> String {
340    match e {
341        Expr::Int(n) => n.to_string(),
342        Expr::Var(v) => py_safe(v),
343        Expr::Field { base, field } => format!("{}.{}", py_safe(base), field),
344        Expr::Old(inner) => render_expr_py(inner),
345        Expr::Unary { op, expr } => match op {
346            UnOp::Neg => format!("-({})", render_expr_py(expr)),
347        },
348        Expr::Bin { op, lhs, rhs } => {
349            let l = render_expr_py(lhs);
350            let r = render_expr_py(rhs);
351            let s = py_bin_op(*op);
352            format!("{} {} {}", l, s, r)
353        }
354        other => crate::render_expr(other),
355    }
356}
357
358fn render_expr_py_doc(e: &Expr) -> String {
359    match e {
360        Expr::Int(n) => n.to_string(),
361        Expr::Var(v) => v.clone(),
362        Expr::Field { base, field } => format!("{}.{}", base, field),
363        Expr::Old(inner) => format!("old({})", render_expr_py_doc(inner)),
364        Expr::Unary { op, expr } => match op {
365            UnOp::Neg => format!("-{}", render_expr_py_doc(expr)),
366        },
367        Expr::Bin { op, lhs, rhs } => {
368            let l = render_expr_py_doc(lhs);
369            let r = render_expr_py_doc(rhs);
370            let s = match op {
371                BinOp::Add => "+",
372                BinOp::Sub => "-",
373                BinOp::Mul => "*",
374                BinOp::Div => "/",
375                BinOp::Eq => "==",
376                BinOp::Ne => "!=",
377                BinOp::Lt => "<",
378                BinOp::Le => "<=",
379                BinOp::Gt => ">",
380                BinOp::Ge => ">=",
381                BinOp::And => "&&",
382                BinOp::Or => "||",
383            };
384            format!("{} {} {}", l, s, r)
385        }
386        other => crate::render_expr_doc(other),
387    }
388}
389
390fn py_bin_op(op: BinOp) -> &'static str {
391    match op {
392        BinOp::Add => "+",
393        BinOp::Sub => "-",
394        BinOp::Mul => "*",
395        BinOp::Div => "//",
396        BinOp::Eq => "==",
397        BinOp::Ne => "!=",
398        BinOp::Lt => "<",
399        BinOp::Le => "<=",
400        BinOp::Gt => ">",
401        BinOp::Ge => ">=",
402        BinOp::And => "and",
403        BinOp::Or => "or",
404    }
405}
406
407/// Render an invariant expression for use inside `satisfies_invariants(self)`.
408/// Bare variable names become `self.<field>`.
409fn render_inv_py(e: &Expr) -> String {
410    match e {
411        Expr::Int(n) => n.to_string(),
412        Expr::Var(v) => format!("self.{}", v),
413        Expr::Field { field, .. } => format!("self.{}", field),
414        Expr::Old(inner) => render_inv_py(inner),
415        Expr::Unary { op, expr } => match op {
416            UnOp::Neg => format!("-({})", render_inv_py(expr)),
417        },
418        Expr::Bin { op, lhs, rhs } => {
419            let l = render_inv_py(lhs);
420            let r = render_inv_py(rhs);
421            let s = py_bin_op(*op);
422            format!("{} {} {}", l, s, r)
423        }
424        other => crate::render_expr(other),
425    }
426}
427
428#[cfg(test)]
429mod tests {
430    use super::*;
431
432    #[test]
433    fn py_safe_escapes_keywords() {
434        assert_eq!(py_safe("from"), "from_");
435        assert_eq!(py_safe("class"), "class_");
436        assert_eq!(py_safe("balance"), "balance");
437    }
438
439    #[test]
440    fn generate_python_emits_dataclass_and_function() {
441        let src = r#"
442            @boundary(ml_training)
443            module PhysicsLayer {
444                invariant State { energy >= 0 }
445                func update_energy(s: State, delta: Int)
446                    requires delta >= 0
447                    ensures s.energy == old(s.energy) + delta
448                { mutate state { s.energy += delta } }
449            }
450        "#;
451        let modules = tpt_telos_parser::parse(src).unwrap();
452        let bodies = std::collections::HashMap::new();
453        let refs: Vec<&tpt_telos_parser::ast::Module> = modules.iter().collect();
454        let py = generate_python_package(&refs, &bodies, false);
455        assert!(py.contains("@dataclass"), "missing @dataclass: {py}");
456        assert!(py.contains("class State"), "missing State class: {py}");
457        assert!(py.contains("def update_energy"), "missing function: {py}");
458        assert!(
459            py.contains("assert delta >= 0"),
460            "missing precondition: {py}"
461        );
462        assert!(
463            py.contains("def satisfies_invariants"),
464            "missing invariant method: {py}"
465        );
466    }
467
468    #[test]
469    fn generate_python_jax_adds_import() {
470        let src = "@boundary(jax) module M { func f(x: Int) requires x >= 0 { } }";
471        let modules = tpt_telos_parser::parse(src).unwrap();
472        let refs: Vec<&tpt_telos_parser::ast::Module> = modules.iter().collect();
473        let py = generate_python_package(&refs, &std::collections::HashMap::new(), true);
474        assert!(
475            py.contains("import jax.numpy as jnp"),
476            "missing JAX import: {py}"
477        );
478    }
479}