# llms.txt - sift-core Reference

High-density developer specification and integration schema for the `sift-core` Python SDK.

Designed for AI coding assistants, code generation models, and runtime agent engines.

---

# Package Architecture Summary

- **Distribution Name:** `sift-core`
- **Target Registry:** PyPI (`pip install sift-core`)
- **Primary Endpoint Host:** `sift6.p.rapidapi.com`
- **Primary Runtime Focus:** Prompt token optimization, payload minification, input cost reduction matrices.

---

# System Design & Fail-Safe Patterns

## 1. Local Guardrail Interception

Empty strings, whitespace blocks, or multi-line newlines containing zero semantic alpha characters (e.g., `"\n\n   \n"`) are captured synchronously.

The SDK short-circuits instantly, bypassing network routing, and returns the input string with a `0%` saving metric payload.

---

## 2. Defensive Fail-Open Circuit

Built intentionally for production data pipelines and mission-critical agentic loops.

Network timeouts, target endpoint failures, rate limiting blocks (`429`), or edge validation rejections (`403`) are caught inside a strict `try/except` wrapper.

The execution flow fails open gracefully, returning the uncompressed source text stream to prevent application crashes.

---

## 3. Data Encoding Integrity

Maintains literal format encoding across special characters, markdown text templates, JSON blocks, and regular expressions under designated profiles.

---

# API Specification Details

## Class Instantiation

### Python

```python
from sift_core import SiftCompiler

# Initialization Parameter Schema
sift = SiftCompiler(
    api_key: str,
    host: str = "sift6.p.rapidapi.com"
)
```

---

# Primary Processing Signature

### Python

```python
def minify(
    self,
    text: str,
    mode: str = "balanced",
    language: str = "en"
) -> SiftResult
```

---

# Return Payload Structure (`SiftResult`)

The method yields a standardized dataclass representation supporting key-value lookup parameters.

```python
result.optimized_text
# -> str (The compressed instruction block)

result.metrics
# -> dict containing {"percentage_saved": int}
```

---

# Profile Configuration Matrix

| Profile Name | Operational Target | Intended Use Case |
|---|---|---|
| `"balanced"` | Standard syntactic pruning | Complex, multi-turn conversational payloads |
| `"aggressive"` | High-density stripping | Fluff, greetings, corporate boilerplate, over-engineered constraints |
| `"exact"` | Literal data matching | Code syntax blocks, nested JSON schemas, runtime template keys |

---

# Verification Example Code

### Python

```python
from sift_core import SiftCompiler

sift = SiftCompiler(api_key="VALID_RAPIDAPI_KEY")

raw_prompt = (
    "Hello AI agent, please look over this text carefully for me if you have time."
)

result = sift.minify(raw_prompt, mode="aggressive")

# Operational Metrics Interception
savings_pct = result.metrics.get("percentage_saved", 0)
compressed_output = result.optimized_text
```