docs(search): add comprehensive Search API documentation (#112)

* feat(search): add Perplexity Search API support

Implement direct access to Perplexity's real-time web index via Search API,
providing raw ranked search results without the generative LLM layer.

Core features:
- SearchRequest with functional options pattern (WithSearchMaxResults, etc.)
- Support for single and multi-query searches
- SearchResponse with result items, images, snippets, scores
- SearchRequestValidator with comprehensive validation
- Complete test coverage for request, response, and validation
- Working example demonstrating simple, advanced, and multi-query searches

API endpoint: https://api.perplexity.ai/search
Pricing: $5 per 1K requests (separate from chat completions)

* style: improve code formatting and alignment

- Align struct field indentation across multiple files
- Fix whitespace alignment in switch case comments
- Add missing newlines at end of files
- Improve code readability with consistent formatting

No functional changes.

* test(search): add comprehensive test suite for Search API

Add extensive test coverage including benchmarks, compliance tests,
integration tests, and edge case validation.

Test additions:
- Benchmark tests for request marshaling performance
- API compliance tests verifying specification adherence
- Integration tests for real API interactions (require PPLX_API_KEY)
- Extended validator tests for edge cases (unicode, special chars, long strings)

Total: 1,434 lines of new test coverage

* docs(search): add comprehensive Search API documentation

Update README and add example documentation covering Search API features,
usage patterns, and comparison with chat completions.

Changes:
- Add Search API section to main README with features and pricing
- Include basic, advanced, and multi-query search examples
- Add comparison table: Search API vs Chat Completions
- Create detailed search-example README with build/run instructions
- Document all search options and validation patterns
- Add context support examples

Author: sgaunet

README.md

@@ -7,14 +7,17 @@
 [![Release](https://github.com/sgaunet/perplexity-go/actions/workflows/release.yml/badge.svg)](https://github.com/sgaunet/perplexity-go/actions/workflows/release.yml)
 [![golangci-lint](https://github.com/sgaunet/perplexity-go/actions/workflows/linter.yml/badge.svg)](https://github.com/sgaunet/perplexity-go/actions/workflows/linter.yml)
 
-A lightweight Go library for interacting with the [Perplexity AI API](https://docs.perplexity.ai/reference/post_chat_completions), focusing on the chat completion endpoint.
+A lightweight Go library for interacting with the [Perplexity AI API](https://docs.perplexity.ai/reference/post_chat_completions), supporting both chat completions and the Search API.
 
-Features
+## Features
 
-    Simple and easy-to-use interface for making chat completion requests
-    Supports all Perplexity models, including online LLMs
-    Handles authentication and API key management
-    Provides convenient methods for common operations
+* Simple and easy-to-use interface for chat completion requests
+* **Search API support** for direct access to Perplexity's real-time web index
+* Supports all Perplexity models, including online LLMs
+* Handles authentication and API key management
+* Comprehensive request validation
+* Concurrent request support with thread-safe operations
+* Context-aware request handling with cancellation support
 
 If you need a **CLI tool** to interact with the API, check out the [pplx](https://github.com/sgaunet/pplx) project.
 
@@ -70,9 +73,124 @@ client := perplexity.NewClient(os.Getenv("PPLX_API_KEY"))
 }
 ```
 
+## Search API
+
+The Perplexity Search API provides direct access to Perplexity's real-time web index without the generative LLM layer, returning raw ranked search results with structured snippets.
+
+### Features
+
+* Direct web search without AI generation layer
+* Single query or multi-query search support
+* Structured results with titles, URLs, snippets, and scores
+* Optional image results
+* Domain filtering
+* Country-specific results
+
+### Pricing
+
+The Search API is priced at **$5 per 1,000 requests** (as of 2024), separate from chat completion pricing.
+
+### Basic Search Usage
+
+```go
+package main
+
+import (
+    "fmt"
+    "os"
+
+    "github.com/sgaunet/perplexity-go/v2"
+)
+
+func main() {
+    client := perplexity.NewClient(os.Getenv("PPLX_API_KEY"))
+
+    // Simple search
+    req := perplexity.NewSearchRequest("golang best practices")
+
+    resp, err := client.SendSearchRequest(req)
+    if err != nil {
+        fmt.Printf("Error: %v\n", err)
+        os.Exit(1)
+    }
+
+    // Print results
+    for i, result := range resp.Results {
+        fmt.Printf("%d. %s\n", i+1, result.Title)
+        fmt.Printf("   URL: %s\n", result.URL)
+        if result.Snippet != nil {
+            fmt.Printf("   Snippet: %s\n", *result.Snippet)
+        }
+    }
+}
+```
+
+### Advanced Search Options
+
+```go
+// Search with all options
+req := perplexity.NewSearchRequest(
+    "machine learning papers",
+    perplexity.WithSearchMaxResults(10),
+    perplexity.WithSearchReturnImages(true),
+    perplexity.WithSearchReturnSnippets(true),
+    perplexity.WithSearchCountry("US"),
+    perplexity.WithSearchDomains([]string{"arxiv.org", "github.com"}),
+)
+
+resp, err := client.SendSearchRequest(req)
+```
+
+### Multi-Query Search
+
+```go
+// Search multiple queries at once
+queries := []string{
+    "Go programming language",
+    "Rust programming language",
+    "Python programming language",
+}
+
+req := perplexity.NewSearchRequest(queries)
+resp, err := client.SendSearchRequest(req)
+```
+
+### Request Validation
+
+```go
+// Validate search request before sending
+validator := perplexity.NewSearchRequestValidator()
+if err := validator.ValidateSearchRequest(req); err != nil {
+    fmt.Printf("Validation error: %v\n", err)
+    return
+}
+```
+
+### Context Support
+
+```go
+import "context"
+
+// With timeout
+ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+defer cancel()
+
+resp, err := client.SendSearchRequestWithContext(ctx, req)
+```
+
+### Search vs Chat Completions
+
+| Feature | Search API | Chat Completions |
+|---------|------------|------------------|
+| **Purpose** | Raw web search results | AI-generated responses |
+| **Response** | Ranked list of URLs with snippets | Natural language text |
+| **Use Case** | Research, data gathering | Q&A, summarization, analysis |
+| **Pricing** | $5 per 1K requests | Variable by model |
+| **Latency** | Lower (no generation) | Higher (includes generation) |
+
 ## Documentation
 
-For detailed documentation and more examples, please refer to the GoDoc page.
+For detailed documentation and more examples, please refer to the [GoDoc page](https://godoc.org/github.com/sgaunet/perplexity-go/v2).
 
 ## Max Tokens
 

cmd/async-completion/main.go

@@ -87,10 +87,10 @@ func main() {
 	// Configure custom polling options
 	opts := &perplexity.AsyncPollingOptions{
 		InitialInterval:   3 * time.Second,  // Start with 3-second intervals
-		MaxInterval:      30 * time.Second, // Cap at 30 seconds
-		BackoffMultiplier: 1.5,             // Gradual backoff
-		MaxWaitTime:      10 * time.Minute, // Total timeout
-		JitterEnabled:    true,             // Add randomness to avoid thundering herd
+		MaxInterval:       30 * time.Second, // Cap at 30 seconds
+		BackoffMultiplier: 1.5,              // Gradual backoff
+		MaxWaitTime:       10 * time.Minute, // Total timeout
+		JitterEnabled:     true,             // Add randomness to avoid thundering herd
 	}
 
 	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Minute)
@@ -247,4 +247,4 @@ func exampleManualPolling(client *perplexity.Client, jobID string) {
 	}
 
 	fmt.Println("✅ Manual polling example completed!")
-}
+}

cmd/basic-completion/main.go

@@ -37,7 +37,7 @@ func main() {
 	req := perplexity.NewCompletionRequest(
 		perplexity.WithMessages(msg),
 		perplexity.WithWebSearchOptions(webSearchOpts),
-		perplexity.WithSearchMode("web"), // Use "web" or "academic" mode
+		perplexity.WithSearchMode("web"),            // Use "web" or "academic" mode
 		perplexity.WithReturnRelatedQuestions(true), // Enable related questions
 	)
 
@@ -98,4 +98,4 @@ func main() {
 			fmt.Printf("%d. %s\n", i+1, question)
 		}
 	}
-}
+}

cmd/image-search/main.go

@@ -25,7 +25,7 @@ func main() {
 	// Create a request with image return enabled
 	req := perplexity.NewCompletionRequest(
 		perplexity.WithMessages(msg),
-		perplexity.WithReturnImages(true),        // Enable image returns
+		perplexity.WithReturnImages(true),      // Enable image returns
 		perplexity.WithSearchRecencyFilter(""), // Clear default recency filter (incompatible with images)
 	)
 
@@ -75,4 +75,4 @@ func main() {
 			fmt.Printf("%d. %s\n", i+1, c)
 		}
 	}
-}
+}