feat: Use AbortSignal in typescript, add a native timeout capability in python. (#2373)

## Summary
Modernizes the abort controller API documentation to use the AbortSignal
pattern, aligning with web standards while improving developer
experience.

**Key Changes:**
- **Renamed documentation**: "Abort Controllers" → "AbortSignals /
Timeouts" to better reflect modern usage patterns
- **Updated TypeScript API**: Changed from `abortController` parameter
to `abortSignal` to align with web standards
- **Added modern timeout pattern for TS**: Introduced
`AbortSignal.timeout(5000)` for simple timeout scenarios
- **Enhanced Python support**: Added `AbortController(timeout_ms=5000)`
constructor for built-in timeouts
- **Updated cross-references**: Fixed all internal links and redirects
throughout documentation

## Code Examples

### Before (old AbortController pattern):
```typescript
const controller = new AbortController()
const result = await b.ExtractResume(text, {
  abortController: controller  // Old parameter name
})
```

### After (modern AbortSignal pattern):
```typescript
// Simple timeout approach
const result = await b.ExtractResume(text, {
  abortSignal: AbortSignal.timeout(5000)  // Modern web standard
})

// Manual control when needed
const controller = new AbortController()
const result = await b.ExtractResume(text, {
  abortSignal: controller.signal  // Updated parameter name
})
```

### Python Simplification:

**Before (complex manual timeout):**
```python
async def with_timeout(operation, timeout_seconds):
    controller = AbortController()
    
    async def run_with_timeout():
        timeout_task = asyncio.create_task(asyncio.sleep(timeout_seconds))
        operation_task = asyncio.create_task(operation(controller))
        
        done, pending = await asyncio.wait(
            [timeout_task, operation_task],
            return_when=asyncio.FIRST_COMPLETED
        )
        
        if timeout_task in done:
            controller.abort()
            raise TimeoutError(f"Operation timed out after {timeout_seconds}s")
        
        return operation_task.result()
    
    return await run_with_timeout()

# Usage
result = await with_timeout(
    lambda ctrl: b.ExtractData(input, baml_options={"abort_controller": ctrl}),
    5  # 5 second timeout
)
```

**After (built-in timeout support):**
```python
# Much simpler with built-in timeout
controller = AbortController(timeout_ms=5000)  # Automatic timeout
result = await b.ExtractData(input, baml_options={"abort_controller": controller})
```

## Impact
This refactor eliminates the need for complex `asyncio.wait()` and
manual task management by moving timeout functionality directly into the
API, making it much cleaner and less error-prone while following modern
web standards.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: hellovai

engine/baml-runtime/src/async_vm_runtime.rs

@@ -30,7 +30,7 @@ use crate::{
     tracingv2::storage::storage::Collector,
     type_builder::TypeBuilder,
     BamlRuntime as LlmRuntime, BamlSrcReader, FunctionResult, FunctionResultStream,
-    InnerTraceStats, InternalRuntimeInterface, RuntimeContextManager,
+    InnerTraceStats, InternalRuntimeInterface, RuntimeContextManager, TripWire,
 };
 
 /// Async VM runtime.
@@ -144,7 +144,7 @@ impl BamlAsyncVmRuntime {
         cb: Option<&ClientRegistry>,
         collectors: Option<Vec<Arc<Collector>>>,
         env_vars: HashMap<String, String>,
-        cancel_tripwire: Option<stream_cancel::Tripwire>,
+        cancel_tripwire: Arc<TripWire>,
     ) -> (anyhow::Result<FunctionResult>, FunctionCallId) {
         // TODO: Proper error handling. Refactor the API to return a Result.
         let (function_index, function_kind) = self
@@ -308,7 +308,7 @@ impl BamlAsyncVmRuntime {
 
                         // Spanwed future basically awaits the LLM call and
                         // sends the result to the futures channel.
-                        let cancel_tripwire = cancel_tripwire.clone();
+                        let cancel_tripwire = cancel_tripwire.to_owned();
                         async move {
                             let result = llm_runtime
                                 .call_function(
@@ -397,7 +397,7 @@ impl BamlAsyncVmRuntime {
         cb: Option<&ClientRegistry>,
         collectors: Option<Vec<Arc<Collector>>>,
         env_vars: HashMap<String, String>,
-        cancel_tripwire: Option<stream_cancel::Tripwire>,
+        cancel_tripwire: Arc<TripWire>,
     ) -> (anyhow::Result<FunctionResult>, FunctionCallId) {
         self.async_runtime.block_on(self.call_function(
             function_name,
@@ -420,9 +420,19 @@ impl BamlAsyncVmRuntime {
         cb: Option<&ClientRegistry>,
         collectors: Option<Vec<Arc<Collector>>>,
         env_vars: HashMap<String, String>,
+        // FunctionResultStream is responsible for freeing the TripWire and the clean up.
+        cancel_tripwire: Arc<TripWire>,
     ) -> anyhow::Result<FunctionResultStream> {
-        self.llm_runtime
-            .stream_function(function_name, params, ctx, tb, cb, collectors, env_vars)
+        self.llm_runtime.stream_function(
+            function_name,
+            params,
+            ctx,
+            tb,
+            cb,
+            collectors,
+            env_vars,
+            cancel_tripwire,
+        )
     }
 
     pub async fn build_request(

engine/baml-runtime/src/cli/repl.rs

@@ -31,7 +31,7 @@ use reedline::{
     Signal,
 };
 
-use crate::BamlRuntime;
+use crate::{BamlRuntime, TripWire};
 
 #[derive(Args, Clone, Debug)]
 pub struct ReplArgs {
@@ -287,7 +287,7 @@ impl ReplState {
                                 None,
                                 None,
                                 env_vars,
-                                None,
+                                TripWire::new(None),
                             )
                             .await;
                         let function_result = res.0?;

engine/baml-runtime/src/cli/serve/mod.rs

@@ -39,7 +39,7 @@ use tokio_stream::StreamExt;
 
 use crate::{
     client_registry::ClientRegistry, errors::ExposedError, internal::llm_client::LLMResponse,
-    BamlRuntime, FunctionResult, RuntimeContextManager,
+    BamlRuntime, FunctionResult, RuntimeContextManager, TripWire,
 };
 
 #[derive(clap::Args, Clone, Debug)]
@@ -355,7 +355,7 @@ Tip: test that the server is up using `curl http://localhost:{}/_debug/ping`
                 client_registry.as_ref(),
                 None,
                 env_vars,
-                None,
+                TripWire::new(None),
             )
             .await;
 
@@ -456,6 +456,7 @@ Tip: test that the server is up using `curl http://localhost:{}/_debug/ping`
                 client_registry.as_ref(),
                 Some(vec![]),
                 env_vars,
+                TripWire::new(None),
             );
 
             match result_stream {

engine/baml-runtime/src/eval_expr.rs

@@ -22,7 +22,7 @@ use internal_baml_core::{
 use internal_baml_jinja::types::OutputFormatContent;
 use jsonish::{deserializer::deserialize_flags::Flag, helpers::render_output_format};
 
-use crate::{BamlRuntime, FunctionResult};
+use crate::{BamlRuntime, FunctionResult, TripWire};
 
 const MAX_STEPS: usize = 1000;
 
@@ -327,7 +327,7 @@ async fn beta_reduce<'a>(
                             None,
                             None,
                             env.env_vars.clone(),
-                            None,
+                            TripWire::new(None),
                         )
                         .await
                         .0;
@@ -1149,7 +1149,7 @@ test Poems {
                 Some(on_event),
                 None,
                 HashMap::new(),
-                None,
+                TripWire::new(None),
                 None::<Box<dyn Fn()>>,
             )
             // .run_test("MakePerson", "TestMakePerson", &ctx, Some(on_event), None)
@@ -1283,7 +1283,7 @@ test TestMakePerson() {
                 Some(on_event),
                 None,
                 HashMap::new(),
-                None,
+                TripWire::new(None),
                 None::<Box<dyn Fn()>>,
             )
             // .run_test("MakePerson", "TestMakePerson", &ctx, Some(on_event), None)
@@ -1361,7 +1361,7 @@ test UseFunction() {
                     "OPENAI_API_KEY".to_string(),
                     std::env::var("OPENAI_API_KEY").expect("OPENAI_API_KEY is not set."),
                 )]),
-                None,
+                TripWire::new(None),
                 None::<Box<dyn Fn()>>,
             )
             .await;

engine/baml-runtime/src/lib.rs

@@ -185,6 +185,43 @@ pub struct BamlRuntime {
     pub async_runtime: Arc<tokio::runtime::Runtime>,
 }
 
+pub struct TripWire {
+    trip_wire: Option<stream_cancel::Tripwire>,
+
+    on_drop: Option<Box<dyn Fn() + 'static + Send + Sync>>,
+}
+
+impl TripWire {
+    pub fn new(trip_wire: Option<stream_cancel::Tripwire>) -> Arc<Self> {
+        Arc::new(Self {
+            trip_wire,
+            on_drop: None,
+        })
+    }
+
+    pub fn new_with_on_drop(
+        trip_wire: Option<stream_cancel::Tripwire>,
+        on_drop: Box<dyn Fn() + 'static + Send + Sync>,
+    ) -> Arc<Self> {
+        Arc::new(Self {
+            trip_wire,
+            on_drop: Some(on_drop),
+        })
+    }
+
+    fn trip_wire(&self) -> Option<stream_cancel::Tripwire> {
+        self.trip_wire.clone()
+    }
+}
+
+impl Drop for TripWire {
+    fn drop(&mut self) {
+        if let Some(on_drop) = self.on_drop.take() {
+            on_drop();
+        }
+    }
+}
+
 impl BamlRuntime {
     #[cfg(not(target_arch = "wasm32"))]
     fn get_tokio_singleton() -> Result<Arc<tokio::runtime::Runtime>> {
@@ -410,7 +447,7 @@ impl BamlRuntime {
         expr_tx: Option<mpsc::UnboundedSender<Vec<internal_baml_diagnostics::SerializedSpan>>>,
         collector: Option<Arc<Collector>>,
         env_vars: HashMap<String, String>,
-        cancel_tripwire: Option<stream_cancel::Tripwire>,
+        cancel_tripwire: Arc<TripWire>,
         on_tick: Option<G>,
     ) -> (Result<TestResponse>, FunctionCallId)
     where
@@ -524,7 +561,7 @@ impl BamlRuntime {
                 ExprEvalResult::LLMCall { name, args } => (name, args),
             };
 
-            let mut stream = self.inner.stream_function_impl_with_tripwire(
+            let mut stream = self.inner.stream_function_impl(
                 function_name,
                 &params,
                 self.tracer_wrapper.get_or_create_tracer(&env_vars),
@@ -533,7 +570,7 @@ impl BamlRuntime {
                 self.async_runtime.clone(),
                 // TODO: collectors here?
                 vec![],
-                cancel_tripwire.clone(),
+                cancel_tripwire,
             )?;
             let (response_res, call_uuid) = stream
                 .run(
@@ -626,7 +663,7 @@ impl BamlRuntime {
         on_event: Option<F>,
         collector: Option<Arc<Collector>>,
         env_vars: HashMap<String, String>,
-        cancel_tripwire: Option<stream_cancel::Tripwire>,
+        cancel_tripwire: Arc<TripWire>,
         on_tick: Option<G>,
     ) -> (Result<TestResponse>, FunctionCallId)
     where
@@ -659,7 +696,7 @@ impl BamlRuntime {
         cb: Option<&ClientRegistry>,
         collectors: Option<Vec<Arc<Collector>>>,
         env_vars: HashMap<String, String>,
-        cancel_tripwire: Option<stream_cancel::Tripwire>,
+        cancel_tripwire: Arc<TripWire>,
     ) -> (Result<FunctionResult>, FunctionCallId) {
         let fut = self.call_function(
             function_name,
@@ -683,7 +720,7 @@ impl BamlRuntime {
         cb: Option<&ClientRegistry>,
         collectors: Option<Vec<Arc<Collector>>>,
         env_vars: HashMap<String, String>,
-        cancel_tripwire: Option<stream_cancel::Tripwire>,
+        cancel_tripwire: Arc<TripWire>,
     ) -> (Result<FunctionResult>, FunctionCallId) {
         let res = Box::pin(self.call_function_with_expr_events(
             function_name,
@@ -730,7 +767,7 @@ impl BamlRuntime {
         collectors: Option<Vec<Arc<Collector>>>,
         env_vars: HashMap<String, String>,
         expr_tx: Option<mpsc::UnboundedSender<Vec<internal_baml_diagnostics::SerializedSpan>>>,
-        cancel_tripwire: Option<stream_cancel::Tripwire>,
+        cancel_tripwire: Arc<TripWire>,
     ) -> (Result<FunctionResult>, FunctionCallId) {
         // baml_log::info!("env vars: {:#?}", env_vars.clone());
         baml_log::set_from_env(&env_vars).unwrap();
@@ -937,6 +974,7 @@ impl BamlRuntime {
         collectors: Option<Vec<Arc<Collector>>>,
         env_vars: HashMap<String, String>,
         expr_tx: Option<mpsc::UnboundedSender<Vec<SerializedSpan>>>,
+        cancel_tripwire: Arc<TripWire>,
     ) -> Result<FunctionResultStream> {
         baml_log::set_from_env(&env_vars).unwrap();
         self.inner.stream_function_impl(
@@ -947,6 +985,7 @@ impl BamlRuntime {
             #[cfg(not(target_arch = "wasm32"))]
             self.async_runtime.clone(),
             collectors.unwrap_or_default(),
+            cancel_tripwire,
         )
     }
 
@@ -959,6 +998,7 @@ impl BamlRuntime {
         cb: Option<&ClientRegistry>,
         collectors: Option<Vec<Arc<Collector>>>,
         env_vars: HashMap<String, String>,
+        cancel_tripwire: Arc<TripWire>,
     ) -> Result<FunctionResultStream> {
         self.stream_function_with_expr_events(
             function_name,
@@ -969,6 +1009,7 @@ impl BamlRuntime {
             collectors,
             env_vars,
             None,
+            cancel_tripwire,
         )
     }
 

engine/baml-runtime/src/runtime_methods/call_function.rs

@@ -15,7 +15,6 @@ use internal_baml_core::{
 };
 use internal_baml_jinja::RenderedPrompt;
 use internal_llm_client::{AllowedRoleMetadata, ClientSpec};
-use stream_cancel::Tripwire;
 
 use super::prepare_function::PreparedFunction;
 use crate::{
@@ -40,15 +39,15 @@ use crate::{
     tracingv2::storage::storage::{Collector, BAML_TRACER},
     type_builder::TypeBuilder,
     FunctionResult, FunctionResultStream, InternalRuntimeInterface, RenderCurlSettings,
-    RuntimeContext, RuntimeContextManager,
+    RuntimeContext, RuntimeContextManager, TripWire,
 };
 
 impl InternalBamlRuntime {
     pub(crate) async fn call_function_impl<'ir>(
         &'ir self,
         prepared_func_call: PreparedFunction<'ir>,
         ctx: RuntimeContext,
-        cancel_tripwire: Option<Tripwire>,
+        cancel_tripwire: Arc<TripWire>,
     ) -> Result<crate::FunctionResult> {
         let future = async {
             let renderer =
@@ -65,7 +64,7 @@ impl InternalBamlRuntime {
                 &renderer,
                 &baml_args,
                 |s| renderer.parse(self.ir(), &ctx, s, false),
-                cancel_tripwire,
+                cancel_tripwire.trip_wire(),
             )
             .await;