feat: Add AI-optimized API for LLM agents and Rig framework

hghalebi · hghalebi · commit 92610633511d · 2025-07-31T16:51:19.000+02:00
- Add structured types: AIValidationResult, AIDecision, ValidationMetadata
- Add ai_validate() and ai_validate_async() functions for AI agents
- Add JSON output functions: ai_validate_json() and ai_validate_json_async()
- Add confidence levels (0.0-1.0) for nuanced AI decision-making
- Add Rig framework integration example
- Support LinkedIn usernames with dots (e.g., first.last)
- Update to Rust 2024 edition
- Bump version to 0.3.0
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2025-07-31
+
+### Added
+- AI-optimized API with structured types (`AIValidationResult`, `AIDecision`, `ValidationMetadata`)
+- `ai_validate()` and `ai_validate_async()` functions returning structured data for AI agents
+- `ai_validate_json()` and `ai_validate_json_async()` for direct JSON output
+- Confidence levels (0.0 to 1.0) for nuanced AI decision-making
+- Decision enum (Accept/Retry/Reject) for clear agent actions
+- Comprehensive tests for AI-optimized functions
+- Rig framework integration example demonstrating AI tool implementation
+- Support for LinkedIn usernames with dots (e.g., first.last)
+
+### Changed
+- Enhanced README with AI-optimized API documentation and Rig framework integration guide
+- Improved username extraction to properly handle all valid LinkedIn username formats
+- Updated to Rust 2024 edition
+
 ## [0.2.1] - 2025-07-31
 
 ### Fixed
@@ -16,6 +33,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 - Made CodeCov optional in CI to prevent build failures
+- Improved AUTH_REQUIRED suggested actions for AI agents - now recommends accepting URLs as valid
+- Updated detailed explanations to clarify that AUTH_REQUIRED likely means the profile exists
+
+### Added
+- New example `ai_agent.rs` demonstrating usage with AI agents for lead generation
 
 ## [0.2.0] - 2025-07-31
 
@@ -60,7 +82,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Safe handling of all network errors
 - Proper timeout configuration for HTTP requests
 
-[Unreleased]: https://github.com/RustSandbox/Credify/compare/v0.2.1...HEAD
+[Unreleased]: https://github.com/RustSandbox/Credify/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/RustSandbox/Credify/compare/v0.2.1...v0.3.0
 [0.2.1]: https://github.com/RustSandbox/Credify/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/RustSandbox/Credify/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/RustSandbox/Credify/releases/tag/v0.1.0
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,8 +1,8 @@
 [package]
 name = "credify"
-version = "0.2.1"
-edition = "2021"
-rust-version = "1.70"
+version = "0.3.0"
+edition = "2024"
+rust-version = "1.85"
 authors = ["Hamze Ghalebi <hamze.ghalebi@gmail.com>"]
 license = "MIT OR Apache-2.0"
 description = "A Rust library for validating LinkedIn profile URLs with LLM-friendly error messages"
@@ -36,6 +36,8 @@ thiserror = "2.0"
 tokio = { version = "1.45.1", features = ["rt-multi-thread", "macros"] }
 once_cell = "1.20"
 chrono = "0.4.41"
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
 
 [dev-dependencies]
 pretty_assertions = "1.4"
diff --git a/README.md b/README.md
@@ -199,6 +199,79 @@ let result = validate_for_llm("https://linkedin.com/in/johndoe");
 // 5. Provide helpful feedback to end users
 ```
 
+### 🚀 AI-Optimized API (New in v0.2.1!)
+
+For even deeper AI agent integration, Credify now offers structured data types specifically designed for AI decision-making:
+
+```rust
+use credify::{ai_validate, ai_validate_json, AIDecision};
+
+// Get structured validation result
+let result = ai_validate("https://linkedin.com/in/johndoe");
+
+// Simple boolean for quick decisions
+if result.is_valid {
+    println!("Valid profile!");
+}
+
+// Confidence level (0.0 to 1.0) for nuanced decisions
+if result.confidence >= 0.8 {
+    println!("High confidence: {}", result.confidence);
+}
+
+// AI-friendly decision enum
+match result.decision {
+    AIDecision::Accept => {
+        // Use the profile URL
+        println!("Profile accepted: {:?}", result.username);
+    }
+    AIDecision::Retry => {
+        // Network issue - try again later
+        println!("Temporary issue, retry suggested");
+    }
+    AIDecision::Reject => {
+        // Invalid URL - search for another
+        println!("Invalid URL: {}", result.reason);
+    }
+}
+
+// Get JSON for direct AI consumption
+let json = ai_validate_json("https://linkedin.com/in/johndoe");
+// Returns pretty-printed JSON with all fields
+```
+
+#### Integration with Rig Framework
+
+Credify is optimized for use with the [Rig](https://github.com/0xPlaygrounds/rig) Rust framework for building AI agents:
+
+```rust
+// Define the tool for Rig
+#[derive(Deserialize, Serialize)]
+struct LinkedInValidator;
+
+impl Tool for LinkedInValidator {
+    const NAME: &'static str = "LinkedInValidator";
+    
+    async fn call(&self, args: ValidateLinkedInArgs) -> Result<String, Error> {
+        // Use the AI-optimized JSON function
+        Ok(credify::ai_validate_json(&args.url))
+    }
+}
+
+// System prompt for LinkedIn lead generation
+const SYSTEM_PROMPT: &str = r#"
+When validating LinkedIn profiles:
+1. Use web search to find LinkedIn URLs - don't make them up
+2. ALWAYS validate URLs with LinkedInValidator before using them
+3. Interpret results:
+   - is_valid: true + confidence >= 0.9 = Definitely real profile
+   - decision: Accept = Use this URL
+   - decision: Retry = Try again in a few seconds
+   - decision: Reject = Search for a different URL
+4. AUTH_REQUIRED usually means the profile EXISTS
+"#;
+```
+
 Common LLM agent scenarios:
 - **Lead Generation**: Validate profiles before adding to CRM
 - **Data Enrichment**: Verify profiles before fetching additional data
diff --git a/examples/ai_agent.rs b/examples/ai_agent.rs
@@ -0,0 +1,81 @@
+//! Example demonstrating how to use Credify with AI agents for lead generation
+//!
+//! This example shows how the validate_for_llm function is designed to work
+//! with AI agents that need to validate LinkedIn URLs found during searches.
+
+use credify::validate_for_llm;
+
+/// Simulated AI agent tool for LinkedIn profile validation
+struct LinkedInValidatorTool;
+
+impl LinkedInValidatorTool {
+    /// Validate a LinkedIn URL and return AI-friendly response
+    fn validate(&self, url: &str) -> String {
+        // The validate_for_llm function returns verbose structured data
+        // but does NOT print to terminal - perfect for AI agents
+        validate_for_llm(url)
+    }
+}
+
+fn main() {
+    println!("LinkedIn Profile Validator for AI Agents Example\n");
+
+    let tool = LinkedInValidatorTool;
+
+    // Simulate URLs that an AI agent might find during lead generation
+    let test_urls = vec![
+        (
+            "https://www.linkedin.com/in/johnsmith",
+            "Valid profile format",
+        ),
+        ("https://linkedin.com/in/jane-doe-123", "Valid with hyphens"),
+        ("https://www.google.com/in/someone", "Wrong domain"),
+        (
+            "https://linkedin.com/company/microsoft",
+            "Company page, not profile",
+        ),
+        ("not-a-url", "Invalid URL format"),
+    ];
+
+    for (url, description) in test_urls {
+        println!("=== Testing: {} ===", description);
+        println!("URL: {}\n", url);
+
+        // Call the tool - this returns structured data but doesn't print
+        let result = tool.validate(url);
+
+        // Parse the result to demonstrate what an AI agent would see
+        let is_success = result.contains("VALIDATION_RESULT: SUCCESS");
+        let is_auth_required = result.contains("ERROR_TYPE: AUTH_REQUIRED");
+
+        if is_success {
+            println!("✅ AI Agent Decision: VALID PROFILE - Proceed with this URL");
+        } else if is_auth_required {
+            println!("✅ AI Agent Decision: LIKELY VALID - LinkedIn is blocking checks but URL format is correct");
+            println!("   Recommendation: Treat as valid profile (LinkedIn auth walls usually mean real profiles)");
+        } else {
+            println!("❌ AI Agent Decision: INVALID - Search for a different URL");
+        }
+
+        // Show key information the AI would parse
+        for line in result.lines() {
+            if line.starts_with("VALIDATION_RESULT:")
+                || line.starts_with("ERROR_TYPE:")
+                || line.starts_with("RECOMMENDED_NEXT_STEP:")
+            {
+                println!("   {}", line);
+            }
+        }
+
+        println!("\n---\n");
+    }
+
+    // Demonstrate the authentication case specifically
+    println!("=== Special Case: LinkedIn Authentication Required ===\n");
+    println!("When LinkedIn returns AUTH_REQUIRED:");
+    println!("- The URL format is valid");
+    println!("- The profile LIKELY EXISTS");
+    println!("- LinkedIn is just blocking automated checks");
+    println!("- AI agents should ACCEPT these URLs as valid");
+    println!("\nThis is the most common response for real LinkedIn profiles!");
+}
diff --git a/examples/rig_integration.rs b/examples/rig_integration.rs
@@ -0,0 +1,146 @@
+//! Example of using Credify with Rig framework for AI-powered lead generation
+//!
+//! This example demonstrates the AI-optimized API designed specifically
+//! for function calling with LLM agents.
+
+use credify::{ai_validate_json, AIDecision, AIValidationResult};
+use serde::{Deserialize, Serialize};
+use serde_json::json;
+
+// Note: This is a mock implementation of Rig tool trait
+// In real usage, you would import from rig crate
+
+#[derive(Deserialize)]
+struct ValidateLinkedInArgs {
+    url: String,
+}
+
+#[derive(Debug, thiserror::Error)]
+#[error("LinkedIn validation error")]
+struct LinkedInValidatorError(String);
+
+#[derive(Deserialize, Serialize)]
+struct LinkedInValidator;
+
+// Mock implementation of Rig Tool trait
+impl LinkedInValidator {
+    const NAME: &'static str = "LinkedInValidator";
+
+    fn definition(&self) -> serde_json::Value {
+        json!({
+            "name": "LinkedInValidator",
+            "description": "Validates LinkedIn profile URLs and returns structured data for AI decision making",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "url": {
+                        "type": "string",
+                        "description": "The LinkedIn URL to validate"
+                    }
+                },
+                "required": ["url"]
+            }
+        })
+    }
+
+    async fn call(&self, args: ValidateLinkedInArgs) -> Result<String, LinkedInValidatorError> {
+        // Use the AI-optimized JSON function
+        let json_result = tokio::task::spawn_blocking(move || ai_validate_json(&args.url))
+            .await
+            .map_err(|e| LinkedInValidatorError(format!("Task error: {}", e)))?;
+
+        Ok(json_result)
+    }
+}
+
+// Example system prompt optimized for LinkedIn lead generation
+fn lead_gen_system_prompt() -> &'static str {
+    r#"
+You are an expert LinkedIn lead generator. When searching for LinkedIn profiles:
+
+1. Use web search to find actual LinkedIn URLs - don't make them up
+2. When you find a URL, ALWAYS validate it using the LinkedInValidator tool
+3. Interpret the validation results:
+   - is_valid: true with confidence >= 0.9 = DEFINITELY a real profile
+   - is_valid: true with confidence >= 0.7 = LIKELY a real profile
+   - decision: Accept = Use this URL
+   - decision: Retry = Try validating again after a few seconds
+   - decision: Reject = Search for a different URL
+4. AUTH_REQUIRED errors usually mean the profile EXISTS - treat these as valid
+5. Extract the username from the result for your records
+
+Always provide the validated LinkedIn URL to the user along with the confidence level.
+"#
+}
+
+#[tokio::main]
+async fn main() {
+    println!("=== Credify + Rig Framework Integration Example ===\n");
+
+    // Demonstrate the AI-optimized validation
+    let test_urls = vec![
+        "https://www.linkedin.com/in/satyanadella",
+        "https://linkedin.com/in/fake-user-12345",
+        "https://www.google.com/in/someone",
+        "not-a-url",
+    ];
+
+    let validator = LinkedInValidator;
+
+    for url in test_urls {
+        println!("Testing URL: {}", url);
+
+        let args = ValidateLinkedInArgs {
+            url: url.to_string(),
+        };
+
+        match validator.call(args).await {
+            Ok(json_result) => {
+                // Parse the JSON result
+                match serde_json::from_str::<AIValidationResult>(&json_result) {
+                    Ok(result) => {
+                        println!("  ✓ Validation complete:");
+                        println!("    - Valid: {}", result.is_valid);
+                        println!("    - Confidence: {:.1}%", result.confidence * 100.0);
+                        println!("    - Decision: {:?}", result.decision);
+                        println!("    - Reason: {}", result.reason);
+
+                        if let Some(username) = &result.username {
+                            println!("    - Username: {}", username);
+                        }
+
+                        // Show AI agent interpretation
+                        match result.decision {
+                            AIDecision::Accept => {
+                                println!("    🤖 AI: Use this LinkedIn URL");
+                            }
+                            AIDecision::Retry => {
+                                println!("    🤖 AI: Network issue - retry in a few seconds");
+                            }
+                            AIDecision::Reject => {
+                                println!("    🤖 AI: Invalid URL - search for another");
+                            }
+                        }
+                    }
+                    Err(e) => {
+                        println!("  ✗ Failed to parse result: {}", e);
+                    }
+                }
+            }
+            Err(e) => {
+                println!("  ✗ Validation error: {}", e);
+            }
+        }
+
+        println!();
+    }
+
+    // Show the system prompt
+    println!("\n=== Recommended System Prompt for Rig ===");
+    println!("{}", lead_gen_system_prompt());
+
+    // Demonstrate JSON output format
+    println!("\n=== JSON Output Format Example ===");
+    let example_json = ai_validate_json("https://linkedin.com/in/example");
+    println!("{}", example_json);
+}
diff --git a/src/lib.rs b/src/lib.rs
diff --git a/tests/ai_integration_tests.rs b/tests/ai_integration_tests.rs
