docs: add comprehensive DocC documentation to agent and web search features

- Added full DocC documentation to all public types in Agent/ and WebSearch/
- Documented OllamaAgent, AgentConfiguration, AgentEvent
- Documented OllamaWebSearchClient and all web search models
- Added overview sections, examples, parameters, and cross-references
- Documentation quality now matches existing SDK standards

Author: guitaripod

Sources/Swollama/Agent/AgentConfiguration.swift

@@ -1,15 +1,57 @@
 import Foundation
 
-
+/// Configuration settings for agent behavior and capabilities.
+///
+/// Controls how the agent operates during autonomous workflows, including iteration limits,
+/// result truncation, thinking mode, and model parameters.
+///
+/// ## Overview
+///
+/// The configuration allows you to balance between thoroughness and speed:
+/// - ``default``: Balanced settings suitable for most use cases
+/// - ``extended``: More iterations and larger context for complex tasks
+/// - ``fast``: Fewer iterations and disabled thinking for quick answers
+///
+/// ## Example
+///
+/// ```swift
+/// let config = AgentConfiguration(
+///     maxIterations: 15,
+///     truncateResults: 10000,
+///     enableThinking: true,
+///     modelOptions: ModelOptions(temperature: 0.3)
+/// )
+///
+/// let agent = OllamaAgent(webSearchAPIKey: apiKey, configuration: config)
+/// ```
 public struct AgentConfiguration: Sendable {
+    /// Maximum number of tool-calling iterations before the agent stops.
+    ///
+    /// Prevents infinite loops while allowing the agent to perform multiple tool calls.
     public let maxIterations: Int
 
+    /// Maximum character length for tool results before truncation.
+    ///
+    /// Set to `nil` to disable truncation. Truncation helps manage context window size.
     public let truncateResults: Int?
 
+    /// Whether to enable extended thinking mode for reasoning models.
+    ///
+    /// When enabled, the model shows its reasoning process through ``AgentEvent/thinking(_:)`` events.
     public let enableThinking: Bool
 
+    /// Model-specific parameters to use for all chat requests.
+    ///
+    /// See ``ModelOptions`` for available settings like temperature, context size, etc.
     public let modelOptions: ModelOptions?
 
+    /// Creates an agent configuration with custom settings.
+    ///
+    /// - Parameters:
+    ///   - maxIterations: Maximum tool-calling iterations (default: 10).
+    ///   - truncateResults: Maximum characters for tool results, or `nil` for no limit (default: 8000).
+    ///   - enableThinking: Enable extended thinking mode (default: true).
+    ///   - modelOptions: Optional model-specific parameters.
     public init(
         maxIterations: Int = 10,
         truncateResults: Int? = 8000,
@@ -22,15 +64,33 @@ public struct AgentConfiguration: Sendable {
         self.modelOptions = modelOptions
     }
 
+    /// Default configuration with balanced settings.
+    ///
+    /// - Max iterations: 10
+    /// - Truncate results: 8000 characters
+    /// - Thinking enabled: Yes
+    /// - Model options: None
     public static let `default` = AgentConfiguration()
 
+    /// Extended configuration for complex, multi-step tasks.
+    ///
+    /// - Max iterations: 20
+    /// - Truncate results: 16000 characters
+    /// - Thinking enabled: Yes
+    /// - Model options: Large context window (32000)
     public static let extended = AgentConfiguration(
         maxIterations: 20,
         truncateResults: 16000,
         enableThinking: true,
         modelOptions: ModelOptions(numCtx: 32000)
     )
 
+    /// Fast configuration for quick, simple queries.
+    ///
+    /// - Max iterations: 5
+    /// - Truncate results: 4000 characters
+    /// - Thinking enabled: No
+    /// - Model options: Low temperature (0.0) for deterministic responses
     public static let fast = AgentConfiguration(
         maxIterations: 5,
         truncateResults: 4000,

Sources/Swollama/Agent/AgentEvent.swift

@@ -1,15 +1,64 @@
 import Foundation
 
-
+/// Events emitted during agent execution.
+///
+/// `AgentEvent` represents observable stages in an agent's workflow, allowing you to monitor
+/// the agent's reasoning, tool usage, and responses in real-time.
+///
+/// ## Overview
+///
+/// The agent emits events in this typical sequence:
+/// 1. ``thinking(_:)`` - The model's reasoning process (if enabled)
+/// 2. ``toolCall(name:arguments:)`` - A tool being invoked
+/// 3. ``toolResult(name:content:)`` - The result from the tool
+/// 4. Steps 1-3 repeat as needed
+/// 5. ``message(_:)`` - The final answer
+/// 6. ``done`` - Workflow complete
+///
+/// ## Example
+///
+/// ```swift
+/// for try await event in agent.run(prompt: "What is Swift?", model: model) {
+///     switch event {
+///     case .thinking(let text):
+///         print("💭 \(text)")
+///     case .toolCall(let name, _):
+///         print("🔧 Calling \(name)")
+///     case .toolResult(let name, let content):
+///         print("📊 Result from \(name)")
+///     case .message(let text):
+///         print("💬 \(text)")
+///     case .done:
+///         print("✅ Complete")
+///     }
+/// }
+/// ```
 public enum AgentEvent: Sendable {
+    /// The model's reasoning process before taking action.
+    ///
+    /// Contains the extended thinking content from reasoning models when ``AgentConfiguration/enableThinking`` is true.
     case thinking(String)
 
+    /// A tool is being invoked by the model.
+    ///
+    /// - Parameters:
+    ///   - name: The name of the tool being called (e.g., "web_search").
+    ///   - arguments: JSON string containing the tool's parameters.
     case toolCall(name: String, arguments: String)
 
+    /// The result returned from a tool execution.
+    ///
+    /// - Parameters:
+    ///   - name: The name of the tool that was executed.
+    ///   - content: The result content from the tool (possibly truncated).
     case toolResult(name: String, content: String)
 
+    /// The final response message from the model.
+    ///
+    /// Contains the model's answer after completing all necessary tool calls.
     case message(String)
 
+    /// The agent workflow has completed successfully.
     case done
 }
 

Sources/Swollama/Agent/OllamaAgent.swift

@@ -1,11 +1,66 @@
 import Foundation
 
-
+/// A thread-safe autonomous agent that combines local chat models with cloud-based web search.
+///
+/// `OllamaAgent` orchestrates multi-step workflows where a language model can autonomously search
+/// the web, fetch pages, and synthesize information to answer complex queries. The agent operates
+/// in a loop, allowing the model to make multiple tool calls until it has enough information to
+/// provide a complete answer.
+///
+/// ## Overview
+///
+/// The agent workflow:
+/// 1. Sends the user's prompt to the local Ollama model
+/// 2. Model decides whether to call tools (web search/fetch) or answer directly
+/// 3. If tools are called, executes them via ``OllamaWebSearchClient``
+/// 4. Feeds results back to the model
+/// 5. Repeats until the model provides a final answer or hits iteration limit
+///
+/// All steps emit ``AgentEvent`` values through an `AsyncThrowingStream`, allowing you to observe
+/// the agent's reasoning, tool usage, and responses in real-time.
+///
+/// ## Example
+///
+/// ```swift
+/// let agent = OllamaAgent(webSearchAPIKey: "your_api_key")
+///
+/// guard let model = OllamaModelName.parse("qwen3:4b") else {
+///     throw OllamaError.invalidParameters("Invalid model")
+/// }
+///
+/// for try await event in agent.run(prompt: "What are the latest Swift features?", model: model) {
+///     switch event {
+///     case .thinking(let text):
+///         print("Thinking: \(text)")
+///     case .toolCall(let name, _):
+///         print("Using tool: \(name)")
+///     case .message(let answer):
+///         print("Answer: \(answer)")
+///     case .done:
+///         print("Complete")
+///     default:
+///         break
+///     }
+/// }
+/// ```
+///
+/// - Note: As an actor, all method calls must use `await`.
+/// - Important: Requires an Ollama API key for web search functionality. Get one at https://ollama.com/settings/keys
 public actor OllamaAgent {
+    /// The local Ollama client for chat operations.
     public let client: OllamaClient
+
+    /// The cloud web search client for tool execution.
     public let webSearch: OllamaWebSearchClient
+
     private let configuration: AgentConfiguration
 
+    /// Creates a new autonomous agent.
+    ///
+    /// - Parameters:
+    ///   - client: The local Ollama client to use. Defaults to a new ``OllamaClient`` instance.
+    ///   - webSearchAPIKey: Your Ollama API key for web search capabilities.
+    ///   - configuration: Agent behavior configuration. Defaults to ``AgentConfiguration/default``.
     public init(
         client: OllamaClient = OllamaClient(),
         webSearchAPIKey: String,
@@ -16,6 +71,37 @@ public actor OllamaAgent {
         self.configuration = configuration
     }
 
+    /// Runs the agent workflow for a given prompt.
+    ///
+    /// Executes an autonomous workflow where the model can search the web and fetch pages to gather
+    /// information before providing an answer. The method returns immediately with an `AsyncThrowingStream`
+    /// that emits events as the agent progresses.
+    ///
+    /// - Parameters:
+    ///   - prompt: The user's query or instruction.
+    ///   - model: The Ollama model to use for reasoning and responses.
+    /// - Returns: A stream of ``AgentEvent`` values representing the agent's progress.
+    /// - Throws: Errors are thrown through the stream, including ``OllamaError/invalidParameters(_:)``
+    ///           if the agent reaches the iteration limit without completing.
+    ///
+    /// ## Example
+    ///
+    /// ```swift
+    /// for try await event in agent.run(prompt: "Explain quantum computing", model: model) {
+    ///     switch event {
+    ///     case .thinking(let thought):
+    ///         print("💭 \(thought)")
+    ///     case .toolCall(let name, _):
+    ///         print("🔧 Calling \(name)")
+    ///     case .message(let answer):
+    ///         print("💬 \(answer)")
+    ///     case .done:
+    ///         print("✅ Done")
+    ///     default:
+    ///         break
+    ///     }
+    /// }
+    /// ```
     nonisolated public func run(
         prompt: String,
         model: OllamaModelName

Sources/Swollama/WebSearch/OllamaWebSearchClient.swift

@@ -5,12 +5,49 @@ import Foundation
 
 private struct InvalidResponseTypeError: Error {}
 
-
+/// A thread-safe client for the Ollama cloud web search API.
+///
+/// `OllamaWebSearchClient` provides access to Ollama's cloud-based web search and web fetch capabilities,
+/// enabling models to search the web for current information and retrieve full page content. This is separate
+/// from the local ``OllamaClient`` and requires an API key for authentication.
+///
+/// ## Overview
+///
+/// The client supports two main operations:
+/// - Web search: Query the web for relevant pages matching a search term
+/// - Web fetch: Extract full content and links from a specific URL
+///
+/// ## Authentication
+///
+/// Requires an Ollama API key. Get one at: https://ollama.com/settings/keys
+///
+/// ## Example
+///
+/// ```swift
+/// let client = OllamaWebSearchClient(apiKey: "your_api_key")
+///
+/// let results = try await client.webSearch(query: "Swift actors", maxResults: 5)
+/// for result in results.results {
+///     print("\(result.title): \(result.url)")
+/// }
+///
+/// let page = try await client.webFetch(url: "https://swift.org")
+/// print(page.content)
+/// ```
+///
+/// - Note: As an actor, all method calls must use `await`.
+/// - Important: This client connects to Ollama's cloud API, not your local Ollama instance.
 public actor OllamaWebSearchClient: Sendable {
     private let apiKey: String
     private let baseURL: URL
     private let session: URLSession
 
+    /// Creates a new Ollama web search client.
+    ///
+    /// - Parameters:
+    ///   - apiKey: Your Ollama API key for authentication.
+    ///   - baseURL: The base URL for the Ollama cloud API. Defaults to `https://ollama.com`.
+    ///   - session: The URLSession to use. Defaults to `.shared`.
     public init(
         apiKey: String,
         baseURL: URL = URL(string: "https://ollama.com")!,
@@ -21,6 +58,15 @@ public actor OllamaWebSearchClient: Sendable {
         self.session = session
     }
 
+    /// Searches the web for information matching a query.
+    ///
+    /// Returns relevant web pages with titles, URLs, and content snippets.
+    ///
+    /// - Parameters:
+    ///   - query: The search query string.
+    ///   - maxResults: Maximum number of results to return (default 5, maximum 10).
+    /// - Returns: A response containing an array of search results.
+    /// - Throws: ``OllamaError/httpError(statusCode:message:)`` if the request fails.
     public func webSearch(
         query: String,
         maxResults: Int? = nil
@@ -29,6 +75,13 @@ public actor OllamaWebSearchClient: Sendable {
         return try await performRequest(path: "/api/web_search", body: request)
     }
 
+    /// Fetches the full content from a specific web page.
+    ///
+    /// Extracts the page title, main text content, and all links found on the page.
+    ///
+    /// - Parameter url: The complete URL of the web page to fetch.
+    /// - Returns: A response containing the page title, content, and links.
+    /// - Throws: ``OllamaError/httpError(statusCode:message:)`` if the request fails.
     public func webFetch(url: String) async throws -> WebFetchResponse {
         let request = WebFetchRequest(url: url)
         return try await performRequest(path: "/api/web_fetch", body: request)
@@ -64,6 +117,17 @@ public actor OllamaWebSearchClient: Sendable {
 
 
 extension OllamaWebSearchClient {
+    /// Tool definition for web search function calling.
+    ///
+    /// Provide this to ``ChatOptions/init(tools:format:modelOptions:keepAlive:think:)`` to enable
+    /// the model to search the web for current information.
+    ///
+    /// ## Example
+    ///
+    /// ```swift
+    /// let options = ChatOptions(tools: [OllamaWebSearchClient.webSearchTool])
+    /// let response = try await client.chat(messages: messages, model: model, options: options)
+    /// ```
     public static let webSearchTool = ToolDefinition(
         type: "function",
         function: FunctionDefinition(
@@ -86,6 +150,17 @@ extension OllamaWebSearchClient {
         )
     )
 
+    /// Tool definition for web fetch function calling.
+    ///
+    /// Provide this to ``ChatOptions/init(tools:format:modelOptions:keepAlive:think:)`` to enable
+    /// the model to fetch and extract full content from specific URLs.
+    ///
+    /// ## Example
+    ///
+    /// ```swift
+    /// let options = ChatOptions(tools: [OllamaWebSearchClient.webFetchTool])
+    /// let response = try await client.chat(messages: messages, model: model, options: options)
+    /// ```
     public static let webFetchTool = ToolDefinition(
         type: "function",
         function: FunctionDefinition(