Metadata-Version: 2.4
Name: linden-ai
Version: 0.2.1
Summary: Python SDK for Linden AI reliability validation
Author: Linden
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Dynamic: license-file

# Linden SDK

## Reliability Layer for Production AI Systems

Linden is an AI reliability engine that validates LLM outputs before they reach production applications.

Modern AI systems can generate responses that look correct but are unreliable:

* Invalid JSON structures
* Missing required fields
* Incorrect data types
* Hallucinated information
* Broken business logic
* Inconsistent outputs
* Unsafe or unexpected responses

Linden acts as a reliability layer between your AI system and your application.

```
LLM Output
    |
    ↓
Linden SDK
    |
    ↓
Reliability Validation
    |
    ↓
ALLOW / WARN / REGENERATE / BLOCK
    |
    ↓
Your Application
```

---

# Why Linden?

Traditional validation checks whether an AI response is formatted correctly.

Linden checks whether an AI response is reliable enough to use.

Example:

```json
{
  "customer_id": "C10293",
  "refund_amount": 500,
  "approved_amount": 50
}
```

The JSON is valid.

The fields exist.

The data types are correct.

But the business logic is wrong.

Linden detects these reliability issues before the output reaches production.

---

# Reliability Profiles

Linden allows teams to configure reusable reliability rules instead of sending validation logic with every request.

A Reliability Profile stores how an AI output should be evaluated.

Examples:

* Customer Support Agent Profile
* Financial AI Profile
* Healthcare AI Profile
* Internal Assistant Profile
* API Response Validation Profile

Instead of sending:

* schemas
* business rules
* validation logic

with every request:

```
Application
      |
      ↓
Reliability Profile
      |
      ↓
Linden Validation Engine
      |
      ↓
Decision
```

Users configure the reliability requirements once and reuse them across AI workflows.

---

# Core Features

## AI Output Validation

Linden supports:

* JSON extraction
* JSON parsing
* Schema validation
* Required field validation
* Optional field validation
* Nullable validation
* Data type validation
* Extra field detection

---

## Business Logic Validation

Linden supports:

* Conditional rules
* Cross-field validation
* Context validation
* Semantic validation
* Business rule validation

---

## Reliability Decisions

Every validation produces a reliability decision.

| Decision   | Meaning                                       |
| ---------- | --------------------------------------------- |
| ALLOW      | Output passed reliability checks              |
| WARN       | Issues detected but output may continue       |
| REGENERATE | Output should be repaired and generated again |
| BLOCK      | Output should not be used                     |

---

# Installation

Install the Linden SDK:

```bash
pip install linden-ai
```

---

# Requirements

* Python 3.10+
* Linden API Key

---

# Quick Start

```python
from linden import LindenClient


client = LindenClient(
    api_key="your_linden_api_key"
)
```
# API Key Setup

Linden uses API keys to authenticate SDK requests.

## Creating an API Key

1. Login to your Linden dashboard
2. Navigate to **API Keys**
3. Click **Create API Key**
4. Copy your generated key

Example:

```text
linden_sk_xxxxxxxxxxxxxxxxx
```

Keep your API key secure.

Never expose API keys in:

* Frontend applications
* Browser code
* Public GitHub repositories
* Client-side applications

Recommended:

```python
import os

from linden import LindenClient


client = LindenClient(
    api_key=os.getenv(
        "LINDEN_API_KEY"
    )
)
```

---

# Reliability Profile Workflow

## Configure Once. Validate Everywhere.

Production AI systems should not send validation rules with every request.

Instead, create a Reliability Profile.

A profile contains:

* Expected output structure
* Schema requirements
* Business rules
* Conditional validation rules
* Cross-field validation rules
* Context validation settings
* Semantic validation settings

Once a profile is created, your application only needs to send:

* AI output
* Profile ID

Linden applies the configured reliability checks automatically.

---

# Example Architecture

```text
AI Application

      |
      |
      ↓

LLM Generates Output

      |
      |
      ↓

Linden SDK

      |
      |
      ↓

Reliability Profile

      |
      |
      ↓

ALLOW / WARN / REGENERATE / BLOCK

      |
      |
      ↓

Application Decision
```

---

# Validate Using a Reliability Profile

Example:

```python
from linden import LindenClient


client = LindenClient(
    api_key="linden_sk_xxxxxxxxx"
)


result = client.validate(

    text="""
    {
        "customer_id": "C10293",
        "refund_amount": 50,
        "approved_amount": 50
    }
    """,

    profile_id=2

)


print(result.decision)

print(result.score)

print(result.issues)
```

Example response:

```text
ALLOW

0

[]
```

---

# Validation Result

Every Linden validation returns a `ValidationResult`.

## Decision

```python
result.decision
```

Possible values:

```text
ALLOW
WARN
REGENERATE
BLOCK
```

---

## Reliability Score

```python
result.score
```

The score represents the reliability risk detected by Linden.

Example:

```text
0
```

means no reliability issues were detected.

---

## Validation Issues

```python
result.issues
```

Example:

```python
[
    {
        "field": "approved_amount",
        "message": "Approved amount does not match refund rules"
    }
]
```

---

# Using Decisions In Your Application

Linden provides the decision.

Your application decides what happens next.

Example:

```python
result = client.validate(

    text=ai_output,

    profile_id=2

)


if result.decision == "ALLOW":

    process_output(ai_output)


elif result.decision == "WARN":

    log_warning(
        result.issues
    )

    process_output(ai_output)


elif result.decision == "REGENERATE":

    retry_generation()


elif result.decision == "BLOCK":

    stop_processing()
```
# Automatic Regeneration

## Repair AI Outputs Automatically

AI systems sometimes generate outputs that are almost correct but fail reliability checks.

Instead of manually handling failures, Linden can automatically:

1. Validate the AI output
2. Detect reliability issues
3. Generate a repair prompt
4. Send the repair request back to your LLM
5. Validate the repaired output again

The process continues until:

* The output passes validation
* The maximum retry limit is reached

---

# Using Automatic Regeneration

Linden provides `run_with_regeneration()` for automatic repair workflows.

Example:

```python
from linden import LindenClient


client = LindenClient(
    api_key="linden_sk_xxxxxxxxx"
)


def my_llm(prompt):

    response = your_llm_provider.generate(
        prompt
    )

    return response



result = client.run_with_regeneration(

    text=ai_output,

    expected_schema=schema,

    llm=my_llm

)


print(result.decision)
```

---

# How Regeneration Works

Example workflow:

```text
AI Output
    |
    ↓
Linden Validation
    |
    |
    ├── ALLOW
    |
    ↓
Return Output


    |
    |
    └── REGENERATE

            |
            ↓

      Generate Repair Prompt

            |
            ↓

      Send Prompt To LLM

            |
            ↓

      Validate New Output

            |
            ↓

      ALLOW / WARN / BLOCK
```

---

# Regeneration Limits

Linden prevents unlimited retry loops.

The SDK supports:

```python
max_regeneration_attempts
```

Example:

```python
result = client.run_with_regeneration(

    text=ai_output,

    expected_schema=schema,

    llm=my_llm,

    max_attempts=3

)
```

The workflow stops when:

* The output passes validation
* The retry limit is reached

---

# Manual Regeneration

For advanced workflows, you can manually control regeneration.

Example:

```python
result = client.validate(

    text=ai_output,

    profile_id=2

)


if result.decision == "REGENERATE":

    repaired = llm(
        result.repair_prompt
    )


    final_result = client.regenerate(

        validation_id=result.validation_id,

        output=repaired,

        profile_id=2

    )
```

---

# Why Use Linden Regeneration?

Without Linden:

```text
AI Output Failure

        ↓

Developer writes retry logic

        ↓

Custom validation handling

        ↓

More application complexity
```

With Linden:

```text
AI Output Failure

        ↓

Linden Detects Problem

        ↓

Linden Creates Repair Instructions

        ↓

AI Repairs Output

        ↓

Validated Production Output
```

---

# Supported AI Workflows

Automatic regeneration works well with:

* AI agents
* Chatbots
* API generation systems
* Structured extraction pipelines
* Automated workflows
* LLM-powered applications
# Advanced Validation Rules

Reliability Profiles are the recommended way to run Linden in production.

However, advanced users can also provide validation rules directly when they need dynamic or temporary validation behavior.

This is useful for:

* Testing new AI workflows
* Development environments
* One-time validation requests
* Dynamic schemas

---

# Schema Validation

Linden can validate AI outputs against an expected schema.

Example:

```python
schema = {

    "customer_id": {

        "type": "str",

        "required": True

    },


    "refund_amount": {

        "type": "int",

        "required": True

    },


    "approved_amount": {

        "type": "int",

        "required": True

    }

}
```

The schema defines:

* Required fields
* Data types
* Allowed structures
* Expected output format

---

# Conditional Rules

Conditional rules validate relationships between fields.

Example:

If a customer is located in the United States, currency must be USD.

```python
conditional_rules = [

    {

        "if": {

            "field": "country",

            "op": "eq",

            "value": "US"

        },


        "then": {

            "target_field": "currency",

            "op": "eq",

            "value": "USD"

        }

    }

]
```

Linden checks whether the AI output follows the required business logic.

---

# Cross-Field Validation

Cross-field validation compares multiple fields.

Example:

Approved refund amount cannot exceed requested refund amount.

```python
cross_field_rules = [

    {

        "field1": "approved_amount",

        "field2": "refund_amount",

        "operator": "<="

    }

]
```

Example failure:

```json
{
    "refund_amount": 50,
    "approved_amount": 500
}
```

Linden detects that the relationship between fields is invalid.

---

# When To Use Profiles vs Manual Rules

## Use Reliability Profiles

Recommended for:

* Production applications
* AI agents
* Long-running systems
* Team workflows
* Repeated validation logic

Example:

```python
result = client.validate(

    text=ai_output,

    profile_id=2

)
```

---

## Use Manual Rules

Recommended for:

* Experiments
* Testing
* Temporary validation
* Dynamic requirements

Example:

```python
result = client.validate(

    text=ai_output,

    expected_schema=schema,

    conditional_rules=rules,

    cross_field_rules=cross_rules

)
```

---

# Production Recommendation

For production AI systems:

1. Create a Reliability Profile
2. Configure validation requirements
3. Connect your application using `profile_id`
4. Let Linden manage reliability decisions

Manual rules should be used only when validation requirements change dynamically.

---

# Validation Pipeline

Linden evaluates outputs through multiple reliability layers:

```text
AI Output

    ↓

JSON Parsing

    ↓

Schema Validation

    ↓

Business Rules

    ↓

Cross-field Checks

    ↓

Context Validation

    ↓

Semantic Validation

    ↓

Reliability Decision

    ↓

ALLOW / WARN / REGENERATE / BLOCK
```
# Integration Examples

Linden is designed to sit between your AI system and production applications.

Common use cases:

* AI agents
* Chatbots
* API generation
* Structured extraction
* Automated workflows
* Enterprise AI applications

---

# Example 1: AI Agent Validation

AI agents often generate tool calls, API requests, or structured actions.

Before executing an agent action, validate it with Linden.

Architecture:

```text
User Request

      ↓

AI Agent

      ↓

Generated Action

      ↓

Linden Validation

      ↓

ALLOW → Execute Action

WARN → Review Action

REGENERATE → Repair Action

BLOCK → Stop Execution
```

Example:

```python id="9n8c1p"
agent_output = agent.run(
    user_request
)


result = client.validate(

    text=agent_output,

    profile_id=2

)


if result.decision == "ALLOW":

    execute_agent_action(
        agent_output
    )


elif result.decision == "BLOCK":

    stop_agent()
```

---

# Example 2: Chatbot Reliability

Chatbots can produce incorrect or unsafe responses.

Linden validates responses before they reach users.

Architecture:

```text
User

 ↓

Chatbot

 ↓

LLM Response

 ↓

Linden

 ↓

User Response
```

Example:

```python id="4qg2mn"
response = chatbot.generate(
    user_message
)


validation = client.validate(

    text=response,

    profile_id=3

)


if validation.decision == "ALLOW":

    return response


if validation.decision == "REGENERATE":

    return client.run_with_regeneration(

        text=response,

        profile_id=3,

        llm=chatbot.generate

    )
```

---

# Example 3: API Response Validation

Many applications use AI models to generate API responses.

Linden verifies the response before returning it.

Example:

```python id="z3p4kg"
ai_response = model.generate()


result = client.validate(

    text=ai_response,

    profile_id=5

)


if result.decision == "BLOCK":

    return {

        "error":
        "Invalid AI response"

    }


return ai_response
```

---

# Example 4: Data Extraction Pipelines

AI systems are commonly used to extract structured data from:

* Documents
* Emails
* Forms
* Customer requests
* Support tickets

Example workflow:

```text
Document

   ↓

LLM Extraction

   ↓

Linden Validation

   ↓

Database

   ↓

Business Application
```

Example:

```python id="5s8qxm"
extracted_data = llm.extract(
    document
)


result = client.validate(

    text=extracted_data,

    profile_id=10

)


if result.decision == "ALLOW":

    save_to_database(
        extracted_data
    )
```

---

# Production Pattern

A typical production AI architecture:

```text
                    Application

                         |

                         ↓

                    AI Model

                         |

                         ↓

                 Linden Reliability Layer

                         |

        ---------------------------------

        |               |               |

      ALLOW           REGENERATE       BLOCK

        |               |               |

   Continue        Repair Output    Stop Request

```

---

# Why Developers Use Linden

Without Linden:

* Every application builds custom validation logic
* Retry systems are manually implemented
* Business rules are scattered
* AI failures reach production

With Linden:

* Reliability rules are centralized
* Profiles are reusable
* Decisions are consistent
* AI failures are handled automatically
# Error Handling

Linden provides clear exceptions for common SDK failures.

Available exceptions:

* Authentication errors
* Invalid validation requests
* Server errors

---

# Handling SDK Errors

Example:

```python id="n6t2aa"
from linden.exceptions import (
    AuthenticationError,
    ValidationError,
    ServerError
)


try:

    result = client.validate(

        text=ai_output,

        profile_id=2

    )


except AuthenticationError:

    print(
        "Invalid Linden API key"
    )


except ValidationError:

    print(
        "Invalid validation request"
    )


except ServerError:

    print(
        "Linden service unavailable"
    )
```

---

# Exception Types

## AuthenticationError

Raised when:

* API key is missing
* API key is invalid
* Authentication fails

Example:

```python id="9v8p3r"
Linden API key required
```

---

## ValidationError

Raised when the request sent to Linden is invalid.

Examples:

* Missing required parameters
* Invalid schema format
* Invalid validation configuration

Example:

```python id="4v0gmx"
Invalid validation request
```

---

## ServerError

Raised when Linden cannot process the request.

Examples:

* Service unavailable
* Internal server error
* Temporary platform issues

Example:

```python id="4u7s1f"
Linden service unavailable
```

---

# Environment Variables

API keys should never be hardcoded.

Recommended setup:

Create a `.env` file:

```text id="a7j8f2"
LINDEN_API_KEY=linden_sk_xxxxxxxxx
```

---

Load the key in your application:

```python id="d3s9kq"
import os

from linden import LindenClient


client = LindenClient(

    api_key=os.getenv(
        "LINDEN_API_KEY"
    )

)
```

---

# Security Best Practices

Protect your Linden API keys.

Do:

✅ Store keys in environment variables
✅ Rotate keys regularly
✅ Use separate keys for development and production
✅ Restrict access to production keys

Do not:

❌ Commit keys to GitHub
❌ Put keys in frontend applications
❌ Share keys publicly
❌ Store keys in client-side code

---

# Production Deployment

For production systems:

Recommended architecture:

```text id="4k8d7m"
Backend Application

        |

        ↓

Linden SDK

        |

        ↓

Linden API

        |

        ↓

Reliability Decision
```

The Linden SDK should run on your backend server.

Never expose your Linden API key directly to users.

---

# Supported Python Versions

Linden supports:

```
Python 3.10+
```

---

# License

MIT License
# Resources

## Website

Learn more about Linden:

https://ai-reliability-frontend.vercel.app/

---

## Documentation

Full documentation:

https://ai-reliability-frontend.vercel.app/docs

---

## SDK Repository

The Linden Python SDK provides:

* AI output validation
* Reliability profile support
* Automatic regeneration workflows
* Production-ready error handling
* Simple Python integration

---

# Current SDK Capabilities

The Linden SDK currently supports:

## Validation

✅ JSON validation
✅ Schema validation
✅ Required field validation
✅ Optional field validation
✅ Nullable validation
✅ Data type validation
✅ Extra field detection
✅ Conditional rules
✅ Cross-field validation
✅ Reliability scoring

---

## Reliability Profiles

✅ Create reusable validation configurations
✅ Validate using profile IDs
✅ Centralize AI reliability rules
✅ Reuse validation logic across applications

---

## Decisions

Every validation returns:

```text
ALLOW
WARN
REGENERATE
BLOCK
```

---

## Regeneration

The SDK supports:

✅ Repair prompts
✅ Automatic retry workflows
✅ LLM regeneration loops
✅ Maximum retry protection

---

# Roadmap

Linden is continuously improving the AI reliability layer.

## Platform Features

Planned:

* Analytics dashboard
* Usage monitoring
* Team API keys
* Organizations
* Billing
* Rate limiting
* Webhooks
* Audit logs

---

## Advanced AI Reliability

Planned:

* Improved semantic validation
* Smarter context matching
* Confidence scoring
* Explainability features
* AI-assisted repair

---

# Contributing

Contributions, feedback, and suggestions are welcome.

If you find issues or have ideas:

* Open an issue
* Submit feedback
* Share your use case

---

# Support

For questions or feedback:

Create an issue or contact the Linden team.

---

# Final Example

A complete Linden workflow:

```text
1. Create Reliability Profile

        ↓

2. Configure AI reliability requirements

        ↓

3. Connect your application using Linden SDK

        ↓

4. Validate AI outputs

        ↓

5. Receive reliability decision

        ↓

ALLOW / WARN / REGENERATE / BLOCK
```

Linden helps teams move AI systems from experimental prototypes to reliable production applications.
