Credify

A robust Rust library for validating LinkedIn profile URLs with AI-first design. Built for the era of AI agents and LLMs, Credify provides both traditional validation APIs and specialized functions optimized for AI tool calling, especially with frameworks like Rig.

🎯 New in v0.3.0: Ergonomic Rig framework integration with ultra-simple async helpers that prevent runtime panics and provide clean, structured responses perfect for AI agents.

🌟 Key Features

• 🤖 AI-First Design - Multiple API levels from simple booleans to rich structured data
• 🎯 Rig Framework Optimized - Ergonomic helpers designed specifically for Rig tools
• ⚡ Async & Sync APIs - Full async support to prevent blocking runtime panics
• 📊 Structured Responses - AIValidationResult with confidence scores and decisions
• 🔍 Smart Validation - Format checking, existence verification, and intelligent fallbacks
• 📝 Rich Error Context - Detailed explanations with actionable suggestions
• 🛡️ Never Panics - Comprehensive error handling throughout
• 🚀 High Performance - Optimized for concurrent operations

📦 Installation

[dependencies]
credify = "0.3.0"

Or use cargo add:

cargo add credify

🚀 Quick Start

For AI Agents & Rig Framework (Recommended)

use credify::{rig_is_valid, rig_validate_text};

// Ultra-simple validation
if rig_is_valid("https://linkedin.com/in/johndoe").await {
    println!("Valid LinkedIn profile!");
}

// Get a human-readable response
let message = rig_validate_text("https://linkedin.com/in/johndoe").await;
// Returns: "✅ Valid profile @johndoe (95% confidence)"

For Rig Tool Implementation

impl Tool for LinkedInValidator {
    async fn call(&self, args: Args) -> Result<String, Error> {
        // Just one line! No runtime panics, perfect for Rig
        Ok(credify::rig_validate_json(&args.url).await)
    }
}

📚 API Overview

🎯 Ergonomic Rig Helpers (New!)

🤖 AI-Optimized Functions

🔧 Traditional API

💡 Usage Examples

1. Rig Framework Integration (Recommended)

use credify::{rig_validate, RigValidationResult};
use rig::tool::Tool;

#[derive(Deserialize, Serialize)]
struct LinkedInChecker;

impl Tool for LinkedInChecker {
    const NAME: &'static str = "linkedin_checker";
    type Args = CheckArgs;
    type Output = String;
    type Error = MyError;

    async fn call(&self, args: Self::Args) -> Result<Self::Output, Self::Error> {
        // One line - that's it!
        Ok(credify::rig_validate_json(&args.url).await)
    }
}

// Or use structured data
async fn check_with_details(url: &str) {
    let result: RigValidationResult = credify::rig_validate(url).await;
    
    println!("Valid: {}", result.valid);
    println!("Status: {}", result.status);
    println!("Action: {}", result.action);
    println!("Confidence: {}%", result.confidence);
    
    if let Some(username) = result.username {
        println!("Username: @{}", username);
    }
}

2. AI Agent Integration

use credify::{ai_validate, AIDecision};

async fn validate_for_ai(url: &str) {
    let result = ai_validate(url).await;
    
    // Simple boolean check
    if result.is_valid {
        println!("Profile is valid!");
    }
    
    // Use confidence for nuanced decisions
    if result.confidence >= 0.9 {
        println!("High confidence validation");
    }
    
    // AI-friendly decision enum
    match result.decision {
        AIDecision::Accept => {
            // Use the profile
            println!("Accepted: {}", result.username.unwrap_or_default());
        }
        AIDecision::Retry => {
            // Network issue, try again
            println!("Temporary issue, retry in a moment");
        }
        AIDecision::Reject => {
            // Invalid URL
            println!("Invalid: {}", result.reason);
        }
    }
}

3. Quick Validation

use credify::is_valid_linkedin_profile_format;

// Format check only (no network calls)
if is_valid_linkedin_profile_format("https://linkedin.com/in/johndoe") {
    println!("Format is valid!");
}

// Full validation with network check
use credify::LinkedInValidator;

let validator = LinkedInValidator::new()?;
match validator.is_valid_linkedin_profile_url(url) {
    Ok(true) => println!("Profile exists!"),
    Ok(false) => println!("Profile not found"),
    Err(e) => println!("Error: {}", e),
}

4. Async Operations

use credify::validate_linkedin_url_async;

// Async validation
let is_valid = validate_linkedin_url_async(url).await?;

// Async with AI response
let json = credify::ai_validate_json_async(url).await;

⚠️ Important: Async Usage

When using Credify in async contexts (like web servers or AI frameworks), always use the async versions to avoid runtime panics:

// ❌ WRONG - Can cause panic in async context
async fn my_tool() {
    let result = credify::ai_validate_json(url); // Panic!
}

// ✅ CORRECT - Use async version
async fn my_tool() {
    let result = credify::ai_validate_json_async(url).await; // Works!
}

// ✅ BEST - Use Rig helpers (always async)
async fn my_tool() {
    let result = credify::rig_validate_json(url).await; // Perfect!
}

📊 Response Types

RigValidationResult

pub struct RigValidationResult {
    pub valid: bool,              // Simple pass/fail
    pub username: Option<String>, // LinkedIn username if found
    pub confidence: u8,           // 0-100 percentage
    pub status: String,           // Human-readable status
    pub action: String,           // Suggested action for AI
}

AIValidationResult

pub struct AIValidationResult {
    pub is_valid: bool,
    pub confidence: f32,          // 0.0 to 1.0
    pub decision: AIDecision,     // Accept/Retry/Reject
    pub username: Option<String>,
    pub reason: String,
    pub metadata: ValidationMetadata,
}

🤖 Why AI-Friendly Validation Matters

Traditional validation returns simple true/false or error codes. AI agents need rich context to make intelligent decisions:

• Context-Rich Responses: Understand why validation failed
• Confidence Scores: Make nuanced decisions based on certainty
• Actionable Suggestions: Know what to do next
• Structured Data: Easy to parse and reason about

🛠️ Advanced Features

Custom User Agent

let validator = LinkedInValidator::new_with_user_agent(
    "MyBot/1.0 (https://mybot.com)"
)?;

Handling LinkedIn Authentication

LinkedIn often returns AUTH_REQUIRED (999 status) for valid profiles. Credify intelligently handles this:

// AUTH_REQUIRED is treated as a valid profile
let result = rig_validate(url).await;
if result.valid && result.status.contains("auth required") {
    println!("Profile likely exists but LinkedIn is blocking checks");
}

📖 More Examples

Check out the examples/ directory for:

• basic.rs - Simple validation examples
• rig_ergonomic.rs - Ergonomic Rig API showcase
• rig_integration.rs - Full Rig framework integration
• batch_validator.rs - Validate multiple URLs concurrently
• llm_simple.rs - LLM-friendly validation

Run examples with:

cargo run --example rig_ergonomic

🧪 Testing

# Run all tests
cargo test

# Run with verbose output
cargo test -- --nocapture

📄 License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

🙏 Acknowledgments

Built with ❤️ for the AI agent community. Special thanks to the Rig framework team for inspiring the ergonomic API design.