Skip to main content

ServerBuilder

helios_engine::serve

Struct ServerBuilder 

Source 
pub struct ServerBuilder { /* private fields */ }
Expand description

Builder for creating a server with agent and endpoints. This provides a more ergonomic API for server configuration.

Implementations§

Source§

impl ServerBuilder

Source

pub fn with_agent(agent: Agent, model_name: impl Into<String>) -> Self

Creates a new server builder with an agent.

Examples found in repository?
examples/serve_simple_endpoints.rs (line 129)
8async fn main() -> helios_engine::Result<()> {
9    // Initialize tracing
10    tracing_subscriber::fmt()
11        .with_max_level(tracing::Level::INFO)
12        .init();
13
14    // Load configuration
15    let config = Config::from_file("config.toml")?;
16
17    // Create an agent with tools
18    let agent = Agent::builder("API Agent")
19        .config(config)
20        .system_prompt("You are a helpful AI assistant with access to a calculator tool.")
21        .tool(Box::new(CalculatorTool))
22        .max_iterations(5)
23        .build()
24        .await?;
25
26    // Create custom endpoints using the new simplified API
27    println!("🎉 Creating custom endpoints with the new simplified API!\n");
28
29    // Method 1: Super simple static endpoints
30    let version_endpoint = helios_engine::get(
31        "/api/version",
32        serde_json::json!({
33            "version": "0.4.4",
34            "service": "Helios Engine",
35            "features": ["agents", "tools", "streaming", "custom_endpoints"]
36        }),
37    );
38
39    let status_endpoint = helios_engine::get(
40        "/api/status",
41        serde_json::json!({
42            "status": "operational",
43            "model": "agent-based"
44        }),
45    );
46
47    // Method 2: Using the builder pattern for more control
48    let info_endpoint = EndpointBuilder::get("/api/info")
49        .json(serde_json::json!({
50            "name": "Helios Engine API",
51            "description": "AI Agent Server with Custom Endpoints",
52            "documentation": "https://helios-engine.vercel.app/"
53        }))
54        .description("API information endpoint")
55        .build();
56
57    // Method 3: Dynamic responses with a handler function
58    let echo_endpoint = EndpointBuilder::post("/api/echo")
59        .handle(|req| {
60            let message = req
61                .and_then(|r| r.body)
62                .and_then(|b| b.get("message").cloned())
63                .unwrap_or_else(|| serde_json::json!("No message provided"));
64
65            helios_engine::EndpointResponse::ok(serde_json::json!({
66                "echo": message,
67                "timestamp": chrono::Utc::now().to_rfc3339()
68            }))
69        })
70        .description("Echo endpoint that returns your message")
71        .build();
72
73    // Method 4: Different HTTP methods
74    let create_endpoint = EndpointBuilder::post("/api/create")
75        .json(serde_json::json!({
76            "message": "Resource created",
77            "id": "12345"
78        }))
79        .description("Simulates creating a resource")
80        .build();
81
82    let update_endpoint = EndpointBuilder::put("/api/update")
83        .json(serde_json::json!({
84            "message": "Resource updated"
85        }))
86        .description("Simulates updating a resource")
87        .build();
88
89    let delete_endpoint = helios_engine::delete(
90        "/api/delete",
91        serde_json::json!({
92            "message": "Resource deleted"
93        }),
94    );
95
96    // Collect all endpoints into a vector
97    let custom_endpoints = vec![
98        version_endpoint,
99        status_endpoint,
100        info_endpoint,
101        echo_endpoint,
102        create_endpoint,
103        update_endpoint,
104        delete_endpoint,
105    ];
106
107    // Start the server with the new ServerBuilder API
108    println!("🚀 Starting server with custom endpoints...\n");
109    println!("📡 OpenAI-compatible API endpoints:");
110    println!("   POST /v1/chat/completions");
111    println!("   GET  /v1/models");
112    println!("\n📡 Custom endpoints:");
113    println!("   GET    /api/version");
114    println!("   GET    /api/status");
115    println!("   GET    /api/info");
116    println!("   POST   /api/echo");
117    println!("   POST   /api/create");
118    println!("   PUT    /api/update");
119    println!("   DELETE /api/delete");
120    println!("\n💡 Try these commands:");
121    println!("   curl http://127.0.0.1:8000/api/version");
122    println!("   curl http://127.0.0.1:8000/api/status");
123    println!("   curl -X POST http://127.0.0.1:8000/api/echo \\");
124    println!("     -H 'Content-Type: application/json' \\");
125    println!("     -d '{{\"message\": \"Hello, Helios!\"}}'");
126    println!();
127
128    // Method 1: Pass a vector of endpoints (recommended)
129    ServerBuilder::with_agent(agent, "local-model")
130        .address("127.0.0.1:8000")
131        .endpoints(custom_endpoints)
132        .serve()
133        .await?;
134
135    // Method 2: Alternative - you can also use individual .endpoint() calls
136    // ServerBuilder::with_agent(agent, "local-model")
137    //     .address("127.0.0.1:8000")
138    //     .endpoint(version_endpoint)
139    //     .endpoint(status_endpoint)
140    //     // ... etc
141    //     .serve()
142    //     .await?;
143
144    Ok(())
145}
Source

pub fn address(self, address: impl Into<String>) -> Self

Sets the server address (default: “127.0.0.1:8000”).

Examples found in repository?
examples/serve_simple_endpoints.rs (line 130)
8async fn main() -> helios_engine::Result<()> {
9    // Initialize tracing
10    tracing_subscriber::fmt()
11        .with_max_level(tracing::Level::INFO)
12        .init();
13
14    // Load configuration
15    let config = Config::from_file("config.toml")?;
16
17    // Create an agent with tools
18    let agent = Agent::builder("API Agent")
19        .config(config)
20        .system_prompt("You are a helpful AI assistant with access to a calculator tool.")
21        .tool(Box::new(CalculatorTool))
22        .max_iterations(5)
23        .build()
24        .await?;
25
26    // Create custom endpoints using the new simplified API
27    println!("🎉 Creating custom endpoints with the new simplified API!\n");
28
29    // Method 1: Super simple static endpoints
30    let version_endpoint = helios_engine::get(
31        "/api/version",
32        serde_json::json!({
33            "version": "0.4.4",
34            "service": "Helios Engine",
35            "features": ["agents", "tools", "streaming", "custom_endpoints"]
36        }),
37    );
38
39    let status_endpoint = helios_engine::get(
40        "/api/status",
41        serde_json::json!({
42            "status": "operational",
43            "model": "agent-based"
44        }),
45    );
46
47    // Method 2: Using the builder pattern for more control
48    let info_endpoint = EndpointBuilder::get("/api/info")
49        .json(serde_json::json!({
50            "name": "Helios Engine API",
51            "description": "AI Agent Server with Custom Endpoints",
52            "documentation": "https://helios-engine.vercel.app/"
53        }))
54        .description("API information endpoint")
55        .build();
56
57    // Method 3: Dynamic responses with a handler function
58    let echo_endpoint = EndpointBuilder::post("/api/echo")
59        .handle(|req| {
60            let message = req
61                .and_then(|r| r.body)
62                .and_then(|b| b.get("message").cloned())
63                .unwrap_or_else(|| serde_json::json!("No message provided"));
64
65            helios_engine::EndpointResponse::ok(serde_json::json!({
66                "echo": message,
67                "timestamp": chrono::Utc::now().to_rfc3339()
68            }))
69        })
70        .description("Echo endpoint that returns your message")
71        .build();
72
73    // Method 4: Different HTTP methods
74    let create_endpoint = EndpointBuilder::post("/api/create")
75        .json(serde_json::json!({
76            "message": "Resource created",
77            "id": "12345"
78        }))
79        .description("Simulates creating a resource")
80        .build();
81
82    let update_endpoint = EndpointBuilder::put("/api/update")
83        .json(serde_json::json!({
84            "message": "Resource updated"
85        }))
86        .description("Simulates updating a resource")
87        .build();
88
89    let delete_endpoint = helios_engine::delete(
90        "/api/delete",
91        serde_json::json!({
92            "message": "Resource deleted"
93        }),
94    );
95
96    // Collect all endpoints into a vector
97    let custom_endpoints = vec![
98        version_endpoint,
99        status_endpoint,
100        info_endpoint,
101        echo_endpoint,
102        create_endpoint,
103        update_endpoint,
104        delete_endpoint,
105    ];
106
107    // Start the server with the new ServerBuilder API
108    println!("🚀 Starting server with custom endpoints...\n");
109    println!("📡 OpenAI-compatible API endpoints:");
110    println!("   POST /v1/chat/completions");
111    println!("   GET  /v1/models");
112    println!("\n📡 Custom endpoints:");
113    println!("   GET    /api/version");
114    println!("   GET    /api/status");
115    println!("   GET    /api/info");
116    println!("   POST   /api/echo");
117    println!("   POST   /api/create");
118    println!("   PUT    /api/update");
119    println!("   DELETE /api/delete");
120    println!("\n💡 Try these commands:");
121    println!("   curl http://127.0.0.1:8000/api/version");
122    println!("   curl http://127.0.0.1:8000/api/status");
123    println!("   curl -X POST http://127.0.0.1:8000/api/echo \\");
124    println!("     -H 'Content-Type: application/json' \\");
125    println!("     -d '{{\"message\": \"Hello, Helios!\"}}'");
126    println!();
127
128    // Method 1: Pass a vector of endpoints (recommended)
129    ServerBuilder::with_agent(agent, "local-model")
130        .address("127.0.0.1:8000")
131        .endpoints(custom_endpoints)
132        .serve()
133        .await?;
134
135    // Method 2: Alternative - you can also use individual .endpoint() calls
136    // ServerBuilder::with_agent(agent, "local-model")
137    //     .address("127.0.0.1:8000")
138    //     .endpoint(version_endpoint)
139    //     .endpoint(status_endpoint)
140    //     // ... etc
141    //     .serve()
142    //     .await?;
143
144    Ok(())
145}
Source

pub fn endpoint(self, endpoint: CustomEndpoint) -> Self

Adds a custom endpoint to the server.

Source

pub fn endpoints(self, endpoints: Vec<CustomEndpoint>) -> Self

Adds multiple custom endpoints to the server. This is the preferred way to add multiple endpoints at once.

§Example
let endpoints = vec![
    get("/api/v1", serde_json::json!({"version": "1.0"})),
    get("/api/status", serde_json::json!({"status": "ok"})),
];

ServerBuilder::with_agent(agent, "model")
    .endpoints(endpoints)
    .serve()
    .await?;
Examples found in repository?
examples/serve_simple_endpoints.rs (line 131)
8async fn main() -> helios_engine::Result<()> {
9    // Initialize tracing
10    tracing_subscriber::fmt()
11        .with_max_level(tracing::Level::INFO)
12        .init();
13
14    // Load configuration
15    let config = Config::from_file("config.toml")?;
16
17    // Create an agent with tools
18    let agent = Agent::builder("API Agent")
19        .config(config)
20        .system_prompt("You are a helpful AI assistant with access to a calculator tool.")
21        .tool(Box::new(CalculatorTool))
22        .max_iterations(5)
23        .build()
24        .await?;
25
26    // Create custom endpoints using the new simplified API
27    println!("🎉 Creating custom endpoints with the new simplified API!\n");
28
29    // Method 1: Super simple static endpoints
30    let version_endpoint = helios_engine::get(
31        "/api/version",
32        serde_json::json!({
33            "version": "0.4.4",
34            "service": "Helios Engine",
35            "features": ["agents", "tools", "streaming", "custom_endpoints"]
36        }),
37    );
38
39    let status_endpoint = helios_engine::get(
40        "/api/status",
41        serde_json::json!({
42            "status": "operational",
43            "model": "agent-based"
44        }),
45    );
46
47    // Method 2: Using the builder pattern for more control
48    let info_endpoint = EndpointBuilder::get("/api/info")
49        .json(serde_json::json!({
50            "name": "Helios Engine API",
51            "description": "AI Agent Server with Custom Endpoints",
52            "documentation": "https://helios-engine.vercel.app/"
53        }))
54        .description("API information endpoint")
55        .build();
56
57    // Method 3: Dynamic responses with a handler function
58    let echo_endpoint = EndpointBuilder::post("/api/echo")
59        .handle(|req| {
60            let message = req
61                .and_then(|r| r.body)
62                .and_then(|b| b.get("message").cloned())
63                .unwrap_or_else(|| serde_json::json!("No message provided"));
64
65            helios_engine::EndpointResponse::ok(serde_json::json!({
66                "echo": message,
67                "timestamp": chrono::Utc::now().to_rfc3339()
68            }))
69        })
70        .description("Echo endpoint that returns your message")
71        .build();
72
73    // Method 4: Different HTTP methods
74    let create_endpoint = EndpointBuilder::post("/api/create")
75        .json(serde_json::json!({
76            "message": "Resource created",
77            "id": "12345"
78        }))
79        .description("Simulates creating a resource")
80        .build();
81
82    let update_endpoint = EndpointBuilder::put("/api/update")
83        .json(serde_json::json!({
84            "message": "Resource updated"
85        }))
86        .description("Simulates updating a resource")
87        .build();
88
89    let delete_endpoint = helios_engine::delete(
90        "/api/delete",
91        serde_json::json!({
92            "message": "Resource deleted"
93        }),
94    );
95
96    // Collect all endpoints into a vector
97    let custom_endpoints = vec![
98        version_endpoint,
99        status_endpoint,
100        info_endpoint,
101        echo_endpoint,
102        create_endpoint,
103        update_endpoint,
104        delete_endpoint,
105    ];
106
107    // Start the server with the new ServerBuilder API
108    println!("🚀 Starting server with custom endpoints...\n");
109    println!("📡 OpenAI-compatible API endpoints:");
110    println!("   POST /v1/chat/completions");
111    println!("   GET  /v1/models");
112    println!("\n📡 Custom endpoints:");
113    println!("   GET    /api/version");
114    println!("   GET    /api/status");
115    println!("   GET    /api/info");
116    println!("   POST   /api/echo");
117    println!("   POST   /api/create");
118    println!("   PUT    /api/update");
119    println!("   DELETE /api/delete");
120    println!("\n💡 Try these commands:");
121    println!("   curl http://127.0.0.1:8000/api/version");
122    println!("   curl http://127.0.0.1:8000/api/status");
123    println!("   curl -X POST http://127.0.0.1:8000/api/echo \\");
124    println!("     -H 'Content-Type: application/json' \\");
125    println!("     -d '{{\"message\": \"Hello, Helios!\"}}'");
126    println!();
127
128    // Method 1: Pass a vector of endpoints (recommended)
129    ServerBuilder::with_agent(agent, "local-model")
130        .address("127.0.0.1:8000")
131        .endpoints(custom_endpoints)
132        .serve()
133        .await?;
134
135    // Method 2: Alternative - you can also use individual .endpoint() calls
136    // ServerBuilder::with_agent(agent, "local-model")
137    //     .address("127.0.0.1:8000")
138    //     .endpoint(version_endpoint)
139    //     .endpoint(status_endpoint)
140    //     // ... etc
141    //     .serve()
142    //     .await?;
143
144    Ok(())
145}
Source

pub fn with_endpoints(self, endpoints: &[CustomEndpoint]) -> Self

Alternative syntax: adds multiple endpoints using a slice. This allows you to pass endpoints inline with array syntax.

§Example
ServerBuilder::with_agent(agent, "model")
    .with_endpoints(&[
        get("/api/v1", serde_json::json!({"version": "1.0"})),
        get("/api/status", serde_json::json!({"status": "ok"})),
    ])
    .serve()
    .await?;
Source

pub async fn serve(self) -> Result<()>

Starts the server.

Examples found in repository?
examples/serve_simple_endpoints.rs (line 132)
8async fn main() -> helios_engine::Result<()> {
9    // Initialize tracing
10    tracing_subscriber::fmt()
11        .with_max_level(tracing::Level::INFO)
12        .init();
13
14    // Load configuration
15    let config = Config::from_file("config.toml")?;
16
17    // Create an agent with tools
18    let agent = Agent::builder("API Agent")
19        .config(config)
20        .system_prompt("You are a helpful AI assistant with access to a calculator tool.")
21        .tool(Box::new(CalculatorTool))
22        .max_iterations(5)
23        .build()
24        .await?;
25
26    // Create custom endpoints using the new simplified API
27    println!("🎉 Creating custom endpoints with the new simplified API!\n");
28
29    // Method 1: Super simple static endpoints
30    let version_endpoint = helios_engine::get(
31        "/api/version",
32        serde_json::json!({
33            "version": "0.4.4",
34            "service": "Helios Engine",
35            "features": ["agents", "tools", "streaming", "custom_endpoints"]
36        }),
37    );
38
39    let status_endpoint = helios_engine::get(
40        "/api/status",
41        serde_json::json!({
42            "status": "operational",
43            "model": "agent-based"
44        }),
45    );
46
47    // Method 2: Using the builder pattern for more control
48    let info_endpoint = EndpointBuilder::get("/api/info")
49        .json(serde_json::json!({
50            "name": "Helios Engine API",
51            "description": "AI Agent Server with Custom Endpoints",
52            "documentation": "https://helios-engine.vercel.app/"
53        }))
54        .description("API information endpoint")
55        .build();
56
57    // Method 3: Dynamic responses with a handler function
58    let echo_endpoint = EndpointBuilder::post("/api/echo")
59        .handle(|req| {
60            let message = req
61                .and_then(|r| r.body)
62                .and_then(|b| b.get("message").cloned())
63                .unwrap_or_else(|| serde_json::json!("No message provided"));
64
65            helios_engine::EndpointResponse::ok(serde_json::json!({
66                "echo": message,
67                "timestamp": chrono::Utc::now().to_rfc3339()
68            }))
69        })
70        .description("Echo endpoint that returns your message")
71        .build();
72
73    // Method 4: Different HTTP methods
74    let create_endpoint = EndpointBuilder::post("/api/create")
75        .json(serde_json::json!({
76            "message": "Resource created",
77            "id": "12345"
78        }))
79        .description("Simulates creating a resource")
80        .build();
81
82    let update_endpoint = EndpointBuilder::put("/api/update")
83        .json(serde_json::json!({
84            "message": "Resource updated"
85        }))
86        .description("Simulates updating a resource")
87        .build();
88
89    let delete_endpoint = helios_engine::delete(
90        "/api/delete",
91        serde_json::json!({
92            "message": "Resource deleted"
93        }),
94    );
95
96    // Collect all endpoints into a vector
97    let custom_endpoints = vec![
98        version_endpoint,
99        status_endpoint,
100        info_endpoint,
101        echo_endpoint,
102        create_endpoint,
103        update_endpoint,
104        delete_endpoint,
105    ];
106
107    // Start the server with the new ServerBuilder API
108    println!("🚀 Starting server with custom endpoints...\n");
109    println!("📡 OpenAI-compatible API endpoints:");
110    println!("   POST /v1/chat/completions");
111    println!("   GET  /v1/models");
112    println!("\n📡 Custom endpoints:");
113    println!("   GET    /api/version");
114    println!("   GET    /api/status");
115    println!("   GET    /api/info");
116    println!("   POST   /api/echo");
117    println!("   POST   /api/create");
118    println!("   PUT    /api/update");
119    println!("   DELETE /api/delete");
120    println!("\n💡 Try these commands:");
121    println!("   curl http://127.0.0.1:8000/api/version");
122    println!("   curl http://127.0.0.1:8000/api/status");
123    println!("   curl -X POST http://127.0.0.1:8000/api/echo \\");
124    println!("     -H 'Content-Type: application/json' \\");
125    println!("     -d '{{\"message\": \"Hello, Helios!\"}}'");
126    println!();
127
128    // Method 1: Pass a vector of endpoints (recommended)
129    ServerBuilder::with_agent(agent, "local-model")
130        .address("127.0.0.1:8000")
131        .endpoints(custom_endpoints)
132        .serve()
133        .await?;
134
135    // Method 2: Alternative - you can also use individual .endpoint() calls
136    // ServerBuilder::with_agent(agent, "local-model")
137    //     .address("127.0.0.1:8000")
138    //     .endpoint(version_endpoint)
139    //     .endpoint(status_endpoint)
140    //     // ... etc
141    //     .serve()
142    //     .await?;
143
144    Ok(())
145}

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> PolicyExt for T
where T: ?Sized,

Source§

fn and<P, B, E>(self, other: P) -> And<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns Action::Follow only if self and other return Action::Follow. Read more
Source§

fn or<P, B, E>(self, other: P) -> Or<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns Action::Follow if either self or other returns Action::Follow. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more