entelix_tools/
lib.rs

1//! # entelix-tools
2//!
3//! Built-in [`entelix_core::tools::Tool`] impls. First-party code
4//! touches zero `std::fs` / `std::process` (Invariant 9); shell- and
5//! filesystem-class tools delegate execution through the
6//! [`entelix_core::sandbox::Sandbox`] trait, whose concrete
7//! implementations ship as 1.x companion crates.
8//!
9//! ## Surface
10//!
11//! - [`HttpFetchTool`] — HTTP fetch with **mandatory host allowlist**
12//!   (SSRF defense), redirect cap, response-size cap, method
13//!   allowlist, cancellation-aware. The allowlist is *opt-in by
14//!   construction*: an `HttpFetchTool::builder()` without any allowed
15//!   hosts produces a tool that refuses every URL.
16//! - [`HostAllowlist`] — domain / wildcard / literal-IP rules with a
17//!   fail-closed default policy.
18//! - [`Calculator`] — arithmetic over `f64` (`+ - * / parens`).
19//!   Recursive-descent parser; no `eval` or shell-out. Generated
20//!   from a free async fn via the [`tool`] macro.
21//! - [`SearchProvider`] (trait) + [`SearchTool`] — adapter for
22//!   external search APIs (Brave / Tavily / Perplexity / …).
23//!   Concrete providers are deferred to 1.1 (same trait-only policy
24//!   as for `Embedder`).
25//!
26//! Coding-agent vertical tools (`SandboxedShellTool`,
27//! `SandboxedCodeTool`, `Sandboxed{Read,Write,ListDir}FileTool`,
28//! `ShellPolicy`, `CodePolicy`, `SandboxSkill`) live in the
29//! `entelix-tools-coding` companion crate so this horizontal surface
30//! stays free of coding-shape opinions.
31
32#![cfg_attr(docsrs, feature(doc_cfg))]
33#![doc(html_root_url = "https://docs.rs/entelix-tools/0.5.3")]
34#![deny(missing_docs)]
35// Doc-prose lints fire on legitimate proper nouns (HTTP, URL, SSRF,
36// API names) and on the `RFC1918` shorthand; the redundant_pub_crate
37// lint disagrees with the workspace `unreachable_pub` rule for items
38// inside private modules. `Tool` trait methods return `&str` whose
39// lifetime is bound by the trait — clippy keeps suggesting elision
40// that the trait signature forbids.
41#![allow(
42    clippy::doc_markdown,
43    clippy::elidable_lifetime_names,
44    clippy::equatable_if_let,
45    clippy::missing_errors_doc,
46    clippy::missing_panics_doc,
47    clippy::missing_const_for_fn,
48    clippy::needless_lifetimes,
49    clippy::needless_pass_by_value,
50    clippy::option_if_let_else,
51    clippy::redundant_pub_crate,
52    clippy::significant_drop_tightening,
53    clippy::unnecessary_literal_bound
54)]
55
56// Make the crate self-referential so the `#[tool]` proc-macro's
57// generated `::entelix_tools::SchemaTool` paths resolve when the
58// macro is invoked from inside this crate. Standard Rust hygiene
59// pattern for proc-macro consumers that re-export their own macro.
60extern crate self as entelix_tools;
61
62pub mod calculator;
63mod dns;
64mod error;
65mod http_fetch;
66pub mod memory;
67mod schema_tool;
68mod search;
69pub mod skills;
70
71pub use calculator::{Calculator, CalculatorInput, CalculatorOutput};
72pub use dns::{SsrfSafeDnsResolver, is_ssrf_blocked};
73/// `#[tool]` attribute macro — generates a [`SchemaTool`] impl
74/// from an `async fn` signature. Doc-comment first paragraph
75/// becomes the tool description; the function name (snake_case)
76/// becomes the tool struct name (PascalCase). See the
77/// `entelix-tool-derive` crate docs for the full contract.
78pub use entelix_tool_derive::tool;
79pub use error::{ToolError, ToolResult};
80pub use http_fetch::{
81    DEFAULT_FETCH_TIMEOUT, DEFAULT_MAX_REDIRECTS, DEFAULT_MAX_RESPONSE_BYTES, HostAllowlist,
82    HostRule, HttpFetchTool, HttpFetchToolBuilder,
83};
84pub use schema_tool::{SchemaTool, SchemaToolAdapter, SchemaToolExt};
85pub use search::{DEFAULT_MAX_RESULTS, SearchProvider, SearchResult, SearchTool};
86pub use skills::{
87    ActivateSkillTool, InMemorySkill, InMemorySkillBuilder, ListSkillsTool, ReadSkillResourceTool,
88    StaticResource,
89};
entelix_tools/lib.rs

entelix_tools/
lib.rs
