devlacruz-hashlib 0.1.8

Extensión de hashing SHA-256 acelerado con Rust y PyO3

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
2. Features
3. Installation
4. Quick Start
5. Real-World AI Agent Integration
6. API Reference
7. Performance
8. Contributing
9. 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:

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

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:

   git checkout -b feature/your-feature-name
   

3. Commit your changes:

   git commit -m "Add awesome feature"
   

4. Push to your branch:

   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 file for details.

---

Author

Alejandro De La Cruz ✉️ [e-mail]