Metadata-Version: 2.4
Name: devlacruz_hashlib
Version: 0.1.8
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Rust
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Security :: Cryptography
License-File: LICENSE
Summary: Extensión de hashing SHA-256 acelerado con Rust y PyO3
Author-email: Alejandro De La Cruz <devlacruz@axtosys.com>
License-Expression: MIT
Requires-Python: >=3.8, <4.0
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# devlacruz_hashlib 🛡️

> **devlacruz_hashlib** has evolved into a high-performance **AI Privacy Shield & TOON Compressor**, implemented in Rust with PyO3. It acts as a Zero-Trust middleware for Python AI Agents, encrypting sensitive data locally before it reaches commercial LLMs (OpenAI, Anthropic) while compressing JSON payloads into the TOON format to slash token costs.

---

## Table of Contents

1. [The Problem It Solves](#the-problem-it-solves)
2. [Features](#features)
3. [Installation](#installation)
4. [Quick Start](#quick-start)
5. [Real-World AI Agent Integration](#real-world-ai-agent-integration)
6. [API Reference](#api-reference)
7. [Performance](#performance)
8. [Contributing](#contributing)
9. [License & Author](#license--author)

---

## The Problem It Solves

When building AI Agents (using frameworks like AutoGen, LangChain, or OpenHands/OpenClaw), sending **PII (Personally Identifiable Information)** or **PHI (Protected Health Information)** to external APIs is a massive compliance and privacy risk. Furthermore, sending large datasets in JSON format wastes thousands of tokens on structural characters (`{}`, `""`).

**devlacruz_hashlib** solves both problems simultaneously at Rust speed:
1. **Locally encrypts** sensitive fields using ChaCha20-Poly1305.
2. **Compresses** the remaining data into the ultra-lightweight **TOON format**.
3. **Intercepts and decrypts** the LLM's response before it reaches your end-user.

---

## Features

* 🔒 **Military-Grade Privacy (Zero-Trust):** Uses ChaCha20-Poly1305 symmetric encryption. Keys are generated in your local RAM and never sent to the LLM.
* 📉 **Massive Token Savings:** Converts heavy JSON structures into the lightweight TOON format, saving up to 60% in prompt token costs.
* ⚡ **Rust Performance:** Parses, encrypts, and compresses thousands of records in milliseconds without blocking the Python GIL.
* 🌍 **Universal Compatibility:** Compiled with ABI3 support, meaning a single wheel works across Python 3.8 to 3.14+ on Linux, Windows, and macOS.

---

## Installation

Install via `pip`:

```bash
pip install devlacruz_hashlib

## Quick Start
# The basic lifecycle of a request using the Privacy Shield:

```python
import devlacruz_hashlib as shield
import json

# 1. Your private local data
data = [
    {"id": 1, "name": "Elon Musk", "diagnosis": "Anxiety", "score": 85},
    {"id": 2, "name": "Bill Gates", "diagnosis": "Flu", "score": 92}
]

# 2. Encrypt sensitive fields and compress to TOON
json_payload = json.dumps(data)
sensitive_keys = ["name", "diagnosis"]

# Rust drops the GIL and does the heavy lifting
secure_toon, master_key = shield.prepare_for_ai(json_payload, sensitive_keys)

print(secure_toon)
# Output (Sent to LLM):
# data[2]{diagnosis,id,name,score}
# <VAULT_A1B2...>,1,<VAULT_C3D4...>,85
# <VAULT_E5F6...>,2,<VAULT_G7H8...>,92

# 3. Simulate the LLM Response (The LLM uses the Vault tokens as names)
llm_response = "Patient <VAULT_A1B2...> needs rest."

# 4. Decrypt locally to get the final output
final_text = shield.restore_from_ai(llm_response, master_key)

print(final_text)
# Output: "Patient Elon Musk needs rest."
```

---

## Real-World AI Agent Integration

If you are building autonomous agents (e.g., using **OpenHands**, **AutoGen**, or custom `while` loops with tool calling), you can use this package as a secure wrapper for your tools.

### Example: Secure Database Tool for an Agent

```python
import devlacruz_hashlib as shield
import json

# Simulated secure internal database
INTERNAL_DB = {
    "Alejandro De La Cruz": {"balance": 5000, "status": "VIP"},
    "Sam Altman": {"balance": 1000, "status": "Standard"}
}

# ---------------------------------------------------------
# The Tool exposed to the AI Agent
# ---------------------------------------------------------
def secure_get_customer_data(encrypted_name: str, local_key: str) -> str:
    """
    Tool for the AI to fetch customer data without knowing their real identity.
    """
    # 1. Decrypt the identity locally
    real_name = shield.restore_from_ai(encrypted_name, local_key).strip()
    
    # 2. Fetch from real database
    if real_name in INTERNAL_DB:
        data = INTERNAL_DB[real_name]
        # 3. Return contextual data (balance/status) to the AI
        return f"User {encrypted_name} data: {json.dumps(data)}"
    return "User not found."

# ---------------------------------------------------------
# Agent Execution Flow
# ---------------------------------------------------------
# Step 1: User asks the agent a question
user_prompt = "What is the balance of Alejandro De La Cruz?"

# Step 2: You mask the prompt before giving it to the Agent
secure_prompt, session_key = shield.prepare_for_ai(
    json.dumps([{"query_target": "Alejandro De La Cruz"}]), 
    ["query_target"]
)

# Step 3: Agent reasons and calls the tool
# Agent thinks: "I need to look up <VAULT_XYZ123>"
tool_result = secure_get_customer_data("<VAULT_XYZ123>", session_key)

# Step 4: Agent generates final answer
agent_final_response = "The user <VAULT_XYZ123> has a balance of 5000 and is a VIP."

# Step 5: You decrypt before showing the user
user_facing_answer = shield.restore_from_ai(agent_final_response, session_key)
print(user_facing_answer) 
# Result: "The user Alejandro De La Cruz has a balance of 5000 and is a VIP."
```

---


## API Reference

| Function | Signature | Description |
| :--- | :--- | :--- |
| `prepare_for_ai` | `prepare_for_ai(json_str: str, sensitive_keys: list[str]) -> tuple[str, str]` | Takes a JSON string and a list of keys to protect. Returns a tuple containing the **TOON-formatted safe payload** and the **session master key**. Releases the GIL during execution. |
| `restore_from_ai` | `restore_from_ai(text: str, master_key: str) -> str` | Scans a text string (usually an LLM response) for `<VAULT_...>` tokens, decrypts them using the master key, and returns the human-readable text. Releases the GIL. |

---

## Performance

Because `devlacruz_hashlib` leverages Rust's memory safety and zero-cost abstractions, it processes large datasets exponentially faster than pure Python cryptography libraries.

**Processing 10,000 JSON records (Parsing + ChaCha20 Encryption + TOON Compression):**
* Pure Python (`cryptography` + `json`): ~2.5 - 4.0 seconds
* **devlacruz_hashlib (Rust)**: ~0.08 - 0.15 seconds
* **Speedup**: ~25x faster.

---

## Use Cases

* **Secure AI Agent Tools:** Create local proxies that encrypt PII before interacting with LLMs.
* **Cost-Optimized LLM Pipelines:** Compress vast JSON data structures into TOON to save on prompt tokens.
* **Compliance:** Maintain HIPAA/GDPR compliance while using commercial AI services.
* **Multi-threaded Data Masking:** Process gigabytes of data concurrently by releasing the Python GIL.

---

## Contributing

Contributions are welcome! To get started:

1. Fork this repository
2. Create a feature branch:

   ```bash
   git checkout -b feature/your-feature-name
   ```
3. Commit your changes:

   ```bash
   git commit -m "Add awesome feature"
   ```
4. Push to your branch:

   ```bash
   git push origin feature/your-feature-name
   ```
5. Open a Pull Request detailing your changes.

Please ensure code follows project style and includes tests.

---

## License

This project is licensed under the **MIT License**. See the [LICENSE](./LICENSE) file for details.

---

## Author

**Alejandro De La Cruz**
✉️ [devlacruz@axtosys.com](mailto:devlacruz@axtosys.com)

