Metadata-Version: 2.4
Name: argos-python
Version: 1.0.1
Summary: argos Security SDK for Python
Author-email: argos Team <team@tachynoix.net>
License: MIT
Keywords: fraud-detection,middleware,sdk,security,threat-detection
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Provides-Extra: all
Requires-Dist: django>=3.0.0; extra == 'all'
Requires-Dist: fastapi>=0.100.0; extra == 'all'
Requires-Dist: flask>=2.0.0; extra == 'all'
Requires-Dist: starlette>=0.27.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: django
Requires-Dist: django>=3.0.0; extra == 'django'
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.100.0; extra == 'fastapi'
Requires-Dist: starlette>=0.27.0; extra == 'fastapi'
Provides-Extra: flask
Requires-Dist: flask>=2.0.0; extra == 'flask'
Description-Content-Type: text/markdown

# argos Security SDK

A production-grade Python SDK for real-time threat detection and fraud prevention. argos monitors every request, scores risk using ML, and lets you block threats instantly or asynchronously.

## Features

- **AI-Powered Detection**: ML models analyze requests in real-time
- **Zero Latency**: Async mode queues events without blocking your app
- **Sync Enforcement**: Block malicious requests before they reach your logic
- **Circuit Breaker**: Built-in resilience with exponential backoff
- **Framework Middleware**: Drop-in support for FastAPI, Flask, Django, Starlette

## Installation

```bash
pip install argos

# With framework support
pip install argos[fastapi]    # FastAPI + Starlette
pip install argos[flask]     # Flask
pip install argos[django]     # Django
pip install argos[all]      # Everything
```

## Quick Start

```python
from argos import create_client

client = create_client(api_key="your-api-key")

event = client.ingest({
    "event_type": "login",
    "user_id": "user123",
    "ip_address": "192.168.1.1",
    "status": "success"
})

if event.signal == "BLOCK":
    print("Threat detected!")
```

## With Middleware

### FastAPI

```python
from fastapi import FastAPI
from argos import create_client
from argos.middleware.fastapi import FastAPIMiddleware

app = FastAPI()
client = create_client(api_key="your-api-key")

app.add_middleware(FastAPIMiddleware, client=client, mode="async")
```

### Flask

```python
from flask import Flask
from argos import create_client
from argos.middleware.flask import FlaskMiddleware

app = Flask(__name__)
client = create_client(api_key="your-api-key")
FlaskMiddleware(app, client)
```

### Django

Add to `settings.py`:

```python
ARGOS_API_KEY = "your-api-key"

MIDDLEWARE = [
    ...
    'argos.middleware.django.DjangoMiddleware',
    ...
]
```

## Configuration

```python
from argos import create_client

client = create_client(
    api_key="your-api-key",
    timeout=30.0,
    max_retries=3,
    queue_size=1000,
    circuit_breaker_threshold=5,
    circuit_breaker_timeout=60.0,
)
```

### Middleware Options

```python
from argos.middleware.base import MiddlewareConfig

config = MiddlewareConfig(
    mode="async",              # "sync" to block, "async" to queue
    include_headers=True,       # include request headers in events
    exclude_paths=["/health"], # skip these paths
    identity_header="X-User-ID",
)
```

## Error Handling

```python
from argos import (
    argosError,
    argosAuthenticationError,
    argosRateLimitError,
    argosTimeoutError,
    argosCircuitOpenError,
)

try:
    event = client.ingest({...})
except argosAuthenticationError:
    print("Invalid API key")
except argosRateLimitError as e:
    print(f"Rate limited, retry in {e.retry_after}s")
except argosCircuitOpenError:
    print("argos is unavailable")
```

## Async Usage

```python
import asyncio
from argos import create_client

async def main():
    client = create_client(api_key="your-api-key")
    event = await client.aingest({"event_type": "login", "user_id": "user123"})
    print(event.signal)

asyncio.run(main())
```

## High Throughput

Queue events during peak traffic, flush when convenient:

```python
# Queue without blocking
for req in requests:
    client.queue_event({"event_type": "request", "path": req.url})

# Process queued events
events = client.flush_queue()
```

## License

MIT
