Metadata-Version: 2.4
Name: pyrestkit
Version: 1.2.2
Summary: Modern Python REST API Automation Toolkit With AI
Author: Raushan Raj
License-Expression: MIT
Project-URL: Homepage, https://github.com/Raushanraj77/pyrestkit
Project-URL: Repository, https://github.com/Raushanraj77/pyrestkit
Project-URL: Issues, https://github.com/Raushanraj77/pyrestkit/issues
Keywords: api,rest,automation,testing,pytest,framework,qa,sdet,ai,llm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.32.0
Requires-Dist: pydantic>=2.10.0
Requires-Dist: jsonschema>=4.23.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: PyYAML>=6.0
Provides-Extra: ai
Requires-Dist: openai>=1.0.0; extra == "ai"
Requires-Dist: anthropic>=0.30.0; extra == "ai"
Requires-Dist: boto3>=1.34.0; extra == "ai"
Requires-Dist: google-generativeai>=0.7.0; extra == "ai"
Requires-Dist: mistralai>=1.0.0; extra == "ai"
Requires-Dist: cohere>=5.0.0; extra == "ai"
Provides-Extra: all
Requires-Dist: pyrestkit[ai]; extra == "all"

# 🚀 PyRestKit

> A modern Python framework for REST API automation with built-in validation,
> authentication, configuration management, and optional AI-assisted failure analysis.

[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
[![PyPI](https://img.shields.io/pypi/v/pyrestkit.svg)](https://pypi.org/project/pyrestkit/)
[![License](https://img.shields.io/github/license/Raushanraj77/pyrestkit)](LICENSE)
[![Tests](https://github.com/Raushanraj77/pyrestkit/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Raushanraj77/pyrestkit/actions/workflows/ci.yml)
[![Code Style](https://img.shields.io/badge/code%20style-ruff-black)](https://docs.astral.sh/ruff/)
[![Type Checked](https://img.shields.io/badge/type%20checked-mypy-blue)](https://mypy-lang.org/)

---

## Why PyRestKit?

Testing REST APIs often requires combining multiple libraries for:

- HTTP requests
- Authentication
- Configuration management
- Assertions
- JSON validation
- Logging
- Retry handling
- Environment management

As projects grow, these utilities become difficult to maintain consistently across teams.

PyRestKit provides a unified, extensible framework that brings these capabilities together while keeping your test code clean, maintainable, and type-safe.

In addition, PyRestKit offers **optional AI-assisted failure analysis**, enabling engineers to receive intelligent explanations and debugging suggestions from multiple Large Language Model (LLM) providers.

---

# Features

## REST API Client

- Simple request API
- GET / POST / PUT / PATCH / DELETE
- Custom headers
- Query parameters
- Cookies
- Multipart requests
- Request timeout support

---

## Authentication

Built-in authentication helpers:

- Basic Authentication
- Bearer Token
- API Key
- OAuth 2.0 (yet to implement)
- Custom authentication strategies

---

## Validation

Powerful response validation utilities.

Supported validations include:

- Status Code
- Headers
- JSON Schema
- Response Time
- JSON Path
- Custom Validators

---

## Configuration

Configuration can be loaded from

- YAML
- Environment Variables
- Python Objects

Supports multiple environments including

- Development
- QA
- Staging
- Production

---

## Assertions

Readable assertions for

- Status codes
- Headers
- JSON values
- Collections
- Response time
- Custom assertions

---

## AI-Assisted Failure Analysis

PyRestKit can analyze failed API responses using AI.

Features include

- Root cause explanation
- Human-readable summaries
- Suggested fixes
- Optional system prompts
- Prompt templates
- Provider abstraction

AI support is completely optional and does not affect users who prefer traditional API testing.

---

## Multiple AI Providers

PyRestKit currently supports:

| Provider | Supported |
|-----------|-----------|
| OpenAI | ✅ |
| Anthropic | ✅ |
| Google Gemini | ✅ |
| Azure OpenAI | ✅ |
| Groq | ✅ |
| Cohere | ✅ |
| Mistral | ✅ |
| Ollama | ✅ |
| AWS Bedrock | ✅ |

The provider abstraction allows additional providers to be implemented with minimal effort.

---

# Installation

## Standard Installation

```bash
pip install pyrestkit
```

---

## Development Installation

```bash
git clone https://github.com/Raushanraj77/pyrestkit.git

cd pyrestkit

python -m venv .venv

source .venv/bin/activate

pip install -e .
```

---

## Verify Installation

```python
import pyrestkit

print(pyrestkit.__version__)
```

---

# Quick Start

## Create a Client

```python
from pyrestkit import APIClient

client = APIClient(base_url="https://jsonplaceholder.typicode.com")
```

---

## Send a Request

```python
response = client.get("/posts/1")
```

---

## Validate Response

```python
response.validate_status_code(200)

response.validate_json()

response.validate_response_time(max_time_ms=1000)
```

---

## Read JSON

```python
data = response.json()

print(data["title"])
```

---

# Authentication Example

## Bearer Token

```python
client = APIClient(base_url="https://example.com")

client.authenticate_bearer(token="your-token")
```

---

## Basic Authentication

```python
client.authenticate_basic(username="admin", password="secret")
```

---

## API Key

```python
client.authenticate_api_key(key="xxxxxxxx", header_name="X-API-Key")
```

---

# Configuration Example

Load configuration from YAML.

```yaml
base_url: https://api.example.com

timeout: 30

headers:
  Accept: application/json
```

```python
from pyrestkit.config import Config

config = Config.from_yaml("config.yaml")
```

---

# Response Validation

```python
response.validate_status_code(200)

response.validate_header("Content-Type", "application/json")

response.validate_schema("schemas/user.json")
```

---

# AI Failure Analysis

AI analysis can be enabled whenever deeper insight into a failed response is useful.

```python
from pyrestkit.ai import AIAnalyzer
from pyrestkit.ai import AIConfig

config = AIConfig(provider="openai", model="gpt-4.1-mini", api_key="YOUR_API_KEY")

analyzer = AIAnalyzer(config)

analysis = analyzer.analyze(
    request=request,
    response=response,
)

print(analysis)
```
---

# Supported AI Providers

PyRestKit uses a provider abstraction layer that allows switching AI providers
without changing your test code.

```text
                    AI Analyzer
                         │
                         ▼
                 Provider Factory
                         │
        ┌────────────────┼────────────────┐
        ▼                ▼                ▼
     OpenAI         Anthropic        Gemini
        │                │                │
        ▼                ▼                ▼
      Groq           Cohere         Azure OpenAI
        │
        ▼
     Mistral
        │
        ▼
     Ollama
        │
        ▼
    AWS Bedrock
```

Every provider implements the same interface.

```python
class BaseAIProvider:
    def complete(
        self,
        prompt: str,
        *,
        config: AIConfig,
        system_prompt: str | None = None,
    ) -> str: ...
```

This makes it easy to:

- switch providers
- test providers
- implement custom providers
- support enterprise LLMs

---

# Project Structure

```text
pyrestkit/
│
├── pyrestkit/
│   │
│   ├── auth/
│   ├── client/
│   ├── config/
│   ├── exceptions/
│   ├── logging/
│   ├── retry/
│   ├── validators/
│   │
│   ├── ai/
│   │   ├── analyzer.py
│   │   ├── config.py
│   │   ├── exceptions.py
│   │   ├── factory.py
│   │   ├── prompt_loader.py
│   │   ├── prompts/
│   │   └── providers/
│   │
│   └── ...
│
├── docs/
├── examples/
├── tests/
├── pyproject.toml
└── README.md
```

---

# Framework Architecture

```text
                 Test

                  │

                  ▼

            API Client

                  │

                  ▼

        Authentication Layer

                  │

                  ▼

           HTTP Transport

                  │

                  ▼

            API Response

                  │

       ┌──────────┴──────────┐

       ▼                     ▼

 Validation             AI Analysis

       │                     │

       ▼                     ▼

 Assertions          Root Cause Analysis
```

---

# Why AI Is Optional

PyRestKit is designed as an API automation framework first.

AI is an optional capability.

This provides several advantages:

- no AI dependency for normal users
- predictable execution
- no external API calls unless enabled
- works in offline environments
- enterprise friendly
- easier testing

If AI is never configured, PyRestKit behaves exactly like a traditional API
automation framework.

---

# Extending PyRestKit

Creating a custom AI provider requires implementing a single interface.

```python
from pyrestkit.ai.providers.base import BaseAIProvider


class InternalProvider(BaseAIProvider):
    def complete(
        self,
        prompt: str,
        *,
        config,
        system_prompt=None,
    ) -> str:

        ...

        return result
```

Register the provider.

```python
factory.register(
    "internal",
    InternalProvider,
)
```

Now it can be used exactly like built-in providers.

---

# Example Workflow

```python
response = client.post(
    "/users",
    json=payload,
)

response.validate_status_code(201)

response.validate_schema("schemas/user.json")
```

If validation fails:

```python
analysis = analyzer.analyze(
    request=request,
    response=response,
)

print(analysis)
```

Example output:

```text
Status Code Mismatch

Expected:
201

Received:
400

Likely Cause

The "email" field is required but missing
from the request payload.

Suggested Fix

Include a valid email address before
submitting the request.
```

---

# Documentation

Detailed documentation is available in the `docs` directory.

| Document | Description |
|----------|-------------|
| getting-started.md | Installation and first project |
| architecture.md | Internal framework architecture |
| configuration.md | Configuration system |
| authentication.md | Authentication mechanisms |
| validation.md | Validators and assertions |
| ai.md | AI-assisted failure analysis |
| providers.md | AI provider implementations |
| examples.md | Complete usage examples |
| faq.md | Frequently asked questions |
| roadmap.md | Future development plans |

---

# Running Tests

Run all tests.

```bash
pytest
```

Run with coverage.

```bash
pytest --cov=pyrestkit
```

Run Ruff.

```bash
ruff check .
```

Run MyPy.

```bash
mypy .
```

Build package.

```bash
python -m build
```

---

# Contributing

Contributions are welcome.

Please read:

- CONTRIBUTING.md
- CODE_OF_CONDUCT.md

before submitting pull requests.

---

# Roadmap

## Version 1.x

- REST API Client
- Authentication
- Validation
- Assertions
- Retry
- Configuration
- Logging
- AI Failure Analysis
- Multiple AI Providers

## Version 2.x

Planned improvements include:

- Async HTTP Client
- HTML Reporting
- OpenAPI Integration
- AI Test Generation
- AI Assertion Suggestions
- Plugin System
- CLI
- VS Code Extension

---

# Why PyRestKit?

PyRestKit aims to provide a clean, extensible, and modern approach to REST API automation.

Core principles:

- Simplicity
- Type Safety
- Extensibility
- Clean Architecture
- Optional AI
- Developer Experience

---

# Requirements

- Python 3.10+
- requests
- pydantic
- jsonschema
- PyYAML

Optional:

- OpenAI
- Anthropic
- Gemini
- Azure OpenAI
- Groq
- Cohere
- Mistral
- Ollama
- AWS Bedrock

---

# License

PyRestKit is licensed under the MIT License.

See the LICENSE file for details.

---

# Support

If you encounter an issue:

- Open a GitHub Issue
- Start a GitHub Discussion
- Submit a Pull Request

---

# Acknowledgements

PyRestKit is inspired by the design philosophies of several outstanding open-source projects, including:

- Requests
- HTTPX
- FastAPI
- Pydantic
- Playwright

while focusing specifically on delivering a modern, extensible framework for REST API automation.

---

## Star the Project ⭐

If PyRestKit helps your team build reliable API automation, consider starring the repository to support the project and stay updated with future releases.
