forge-search

use forge_search;

pub mod config;

pub mod error;

pub mod tools;

pub mod types;

pub mod prelude;

pub use crate::config::SearchConfig;

pub use crate::error::{SearchError, SearchResult};

pub use crate::tools::{register_search_tools, SEARCH_TOOL_NAMES};

pub use crate::types::{
        CrawlRequest, CrawlResponse, ExtractRequest, ExtractResponse, MapRequest, MapResponse,
        SearchRequest, SearchResponse, SearchResultEntry,
    };

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SearchConfig {

}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum SearchDepth {
    /// Fast search using SERP snippets.
    Basic,
    /// Deeper search that fetches and processes page content.
    Advanced,
}

pub fn as_str(&self) -> &'static str;

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum ContentFormat {
    /// Markdown format (preserves structure).
    Markdown,
    /// Plain text (no formatting).
    Text,
}

pub fn as_str(&self) -> &'static str;

pub fn builder() -> SearchConfigBuilder;

pub fn endpoint(&self) -> &str;

pub fn api_key(&self) -> Option<&str>;

pub fn engines(&self) -> &[String];

pub fn default_max_results(&self) -> u32;

pub fn default_search_depth(&self) -> SearchDepth;

pub fn default_content_format(&self) -> ContentFormat;

pub fn request_timeout_ms(&self) -> u64;

pub fn max_extract_urls(&self) -> usize;

pub fn max_crawl_depth(&self) -> u32;

pub fn max_crawl_breadth(&self) -> u32;

pub fn max_crawl_pages(&self) -> u32;

pub struct SearchConfigBuilder {

}

pub fn endpoint(mut self, endpoint: impl Into<String>) -> Self;

pub fn api_key(mut self, key: impl Into<String>) -> Self;

pub fn engines(mut self, engines: Vec<String>) -> Self;

pub fn default_max_results(mut self, max: u32) -> Self;

pub fn default_search_depth(mut self, depth: SearchDepth) -> Self;

pub fn default_content_format(mut self, format: ContentFormat) -> Self;

pub fn request_timeout_ms(mut self, ms: u64) -> Self;

pub fn max_crawl_depth(mut self, depth: u32) -> Self;

pub fn build(self) -> SearchConfig;

#[derive(Debug, Error)]
pub enum SearchError {
    /// The search query was empty or blank.
    #[error("search query must not be empty; provide a non-blank query string")]
    EmptyQuery,

    /// The OneSearch API endpoint is not configured or unreachable.
    #[error(
        "OneSearch API endpoint '{endpoint}' is not reachable: {reason}; \
         verify the endpoint URL and that the OneSearch service is running"
    )]
    EndpointUnreachable {
        /// The endpoint URL that was attempted.
        endpoint: String,
        /// The reason the endpoint could not be reached.
        reason: String,
    },

    /// The OneSearch API returned an error response.
    #[error(
        "OneSearch API error (HTTP {status}): {message}; \
         request_id={request_id}"
    )]
    ApiError {
        /// The HTTP status code returned.
        status: u16,
        /// The error message from the API.
        message: String,
        /// The request ID for correlation.
        request_id: String,
    },

    /// A URL provided for extraction or crawling was invalid.
    #[error("invalid URL '{url}': {reason}")]
    InvalidUrl {
        /// The invalid URL.
        url: String,
        /// Why the URL is invalid.
        reason: String,
    },

    /// Too many URLs provided for extraction.
    #[error(
        "too many URLs for extraction: {count} provided but maximum is {max}; \
         reduce the number of URLs per request"
    )]
    TooManyUrls {
        /// The number of URLs provided.
        count: usize,
        /// The maximum allowed.
        max: usize,
    },

    /// The crawl depth or breadth exceeded configured limits.
    #[error("crawl parameter out of range: {param}={value} but allowed range is [{min}, {max}]")]
    CrawlParameterOutOfRange {
        /// The parameter name (e.g., "max_depth", "max_breadth").
        param: String,
        /// The value that was provided.
        value: i64,
        /// The minimum allowed value.
        min: i64,
        /// The maximum allowed value.
        max: i64,
    },

    /// Request timed out.
    #[error("search request timed out after {timeout_ms}ms")]
    Timeout {
        /// The timeout in milliseconds.
        timeout_ms: u64,
    },

    /// Serialization or deserialization of request/response failed.
    #[error("serialization error: {reason}")]
    SerializationError {
        /// What went wrong.
        reason: String,
    },

    /// Search is disabled or not configured in this toolbelt instance.
    #[error(
        "search tool '{tool_name}' is not configured; set the OneSearch endpoint in \
         SearchConfig or provide an API key to enable search capabilities"
    )]
    NotConfigured {
        /// The tool name that was invoked.
        tool_name: String,
    },
}

pub type SearchResult<T> = Result<T, SearchError>;

pub mod config;

pub mod error;

pub mod tools;

pub mod types;

pub mod prelude;

pub use crate::config::SearchConfig;

pub use crate::error::{SearchError, SearchResult};

pub use crate::tools::{register_search_tools, SEARCH_TOOL_NAMES};

pub use crate::types::{
        CrawlRequest, CrawlResponse, ExtractRequest, ExtractResponse, MapRequest, MapResponse,
        SearchRequest, SearchResponse, SearchResultEntry,
    };

pub const SEARCH_TOOL_NAMES: &[&str];

pub fn search_tool_definitions(config: &SearchConfig) -> Vec<ToolDefinition>;

pub fn register_search_tools(
    registry: &mut ToolRegistry,
    config: &SearchConfig,
) -> Result<(), ForgeToolError>;

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SearchRequest {

}

pub fn new(query: impl Into<String>) -> Self;

pub fn query(&self) -> &str;

pub fn max_results(&self) -> u32;

pub fn with_max_results(mut self, max: u32) -> Self;

pub fn with_search_depth(mut self, depth: &str) -> Self;

pub fn with_topic(mut self, topic: &str) -> Self;

pub fn with_answer(mut self) -> Self;

pub fn with_raw_content(mut self) -> Self;

pub fn with_engines(mut self, engines: Vec<String>) -> Self;

pub fn with_include_domains(mut self, domains: Vec<String>) -> Self;

pub fn with_exclude_domains(mut self, domains: Vec<String>) -> Self;

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SearchResultEntry {
/// The page title.

pub title: String,
/// The page URL.

pub url: String,
/// A content snippet or summary.

pub content: String,
/// Relevance score (0.0 to 1.0).

pub score: f64,
/// Full raw content of the page, if requested.

#[serde(skip_serializing_if = "Option::is_none")]
pub raw_content: Option<String>,
/// Publication date, if available.

#[serde(skip_serializing_if = "Option::is_none")]
pub published_date: Option<String>
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SearchResponse {
/// The original query.

pub query: String,
/// The search results.

pub results: Vec<SearchResultEntry>,
/// AI-generated answer, if requested.

#[serde(skip_serializing_if = "Option::is_none")]
pub answer: Option<String>,
/// Time taken to process the search, in seconds.

pub response_time: f64,
/// Unique request identifier.

pub request_id: String
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ExtractRequest {

}

pub fn new(urls: Vec<String>) -> Self;

pub fn urls(&self) -> &[String];

pub fn with_depth(mut self, depth: &str) -> Self;

pub fn with_format(mut self, format: &str) -> Self;

pub fn with_timeout(mut self, timeout: f64) -> Self;

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ExtractResultEntry {
/// The URL that was extracted.

pub url: String,
/// The extracted raw content.

pub raw_content: String,
/// Images found on the page.

#[serde(default)]
pub images: Vec<String>
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ExtractFailedEntry {
/// The URL that failed.

pub url: String,
/// The error message.

pub error: String
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ExtractResponse {
/// Successfully extracted results.

pub results: Vec<ExtractResultEntry>,
/// URLs that failed to extract.

#[serde(default)]
pub failed_results: Vec<ExtractFailedEntry>,
/// Time taken in seconds.

pub response_time: f64,
/// Unique request identifier.

pub request_id: String
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CrawlRequest {

}

pub fn new(url: impl Into<String>) -> Self;

pub fn url(&self) -> &str;

pub fn with_max_depth(mut self, depth: u32) -> Self;

pub fn with_max_breadth(mut self, breadth: u32) -> Self;

pub fn with_limit(mut self, limit: u32) -> Self;

pub fn with_select_paths(mut self, paths: Vec<String>) -> Self;

pub fn with_exclude_paths(mut self, paths: Vec<String>) -> Self;

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CrawlResultEntry {
/// The page URL.

pub url: String,
/// The page content (in the requested format).

pub raw_content: String,
/// Images found on the page.

#[serde(default)]
pub images: Vec<String>
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CrawlResponse {
/// The base URL that was crawled.

pub base_url: String,
/// The crawled page results.

pub results: Vec<CrawlResultEntry>,
/// Time taken in seconds.

pub response_time: f64,
/// Unique request identifier.

pub request_id: String
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct MapRequest {

}

pub fn new(url: impl Into<String>) -> Self;

pub fn url(&self) -> &str;

pub fn with_max_depth(mut self, depth: u32) -> Self;

pub fn with_max_breadth(mut self, breadth: u32) -> Self;

pub fn with_limit(mut self, limit: u32) -> Self;

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct MapResponse {
/// The base URL that was mapped.

pub base_url: String,
/// The discovered URLs.

pub results: Vec<String>,
/// Time taken in seconds.

pub response_time: f64,
/// Unique request identifier.

pub request_id: String
}