Spaces:
Sleeping
Sleeping
Paramveer singh commited on
Commit Β·
04fb48a
1
Parent(s): af1b492
Docs: Added comprehensive technical documentation suite
Browse files- docs/deployment.md +15 -0
- docs/environment.md +28 -0
- docs/scaling.md +17 -0
- docs/training.md +22 -0
docs/deployment.md
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# π Deployment Architecture
|
| 2 |
+
|
| 3 |
+
The environment is containerized and ready for cloud-scale deployment.
|
| 4 |
+
|
| 5 |
+
## ποΈ Stack
|
| 6 |
+
- **Runtime**: Python 3.10-slim.
|
| 7 |
+
- **Framework**: FastAPI + Uvicorn.
|
| 8 |
+
- **Containerization**: Docker.
|
| 9 |
+
- **Hosting**: Hugging Face Spaces (Docker SDK).
|
| 10 |
+
|
| 11 |
+
## π³ Docker Configuration
|
| 12 |
+
The environment is exposed on port `7860`. The build uses a multi-stage-like approach to keep the image size under 500MB, ensuring fast cold-starts on serverless platforms.
|
| 13 |
+
|
| 14 |
+
## π‘οΈ Security
|
| 15 |
+
The environment uses a **read-only** mock database that resets every episode. No actual PII is ever stored; all data is programmatically generated in-memory, making it safe for open-source AI research.
|
docs/environment.md
ADDED
|
@@ -0,0 +1,28 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# π§© Environment Specification
|
| 2 |
+
|
| 3 |
+
`DataPrivacyEnv` follows the Markov Decision Process (MDP) framework where an agent learns to minimize privacy risk through interaction.
|
| 4 |
+
|
| 5 |
+
## π’ State Space ($S$)
|
| 6 |
+
The state is represented as an in-memory relational database containing:
|
| 7 |
+
- **Users Table**: User metadata (ID, Name, Role, and potentially exposed PII like passwords).
|
| 8 |
+
- **Logs Table**: Unstructured text data containing system events and leaked identifiers.
|
| 9 |
+
|
| 10 |
+
## ποΈ Observation Space ($O$)
|
| 11 |
+
The agent does not see the full database state at once. It perceives:
|
| 12 |
+
- `status_code`: The result of its last API action.
|
| 13 |
+
- `response_data`: The specific JSON fragment returned by the endpoint.
|
| 14 |
+
- `current_task_goal`: A natural language embedding of the objective.
|
| 15 |
+
|
| 16 |
+
## β‘ Action Space ($A$)
|
| 17 |
+
The action space is **discrete-symbolic**. The agent must generate a valid `PrivacyAction` object:
|
| 18 |
+
- **Methods**: `GET`, `PATCH`, `DELETE`.
|
| 19 |
+
- **Endpoints**: Targeted resource paths.
|
| 20 |
+
- **Payload**: Key-value pairs for redaction logic.
|
| 21 |
+
|
| 22 |
+
## π° Reward Function ($R$)
|
| 23 |
+
The reward is calculated based on state-delta verification:
|
| 24 |
+
$$R_t = \text{Score}_{\text{task}} - \text{Penalty}_{\text{invalid\_action}}$$
|
| 25 |
+
|
| 26 |
+
- **Success**: $1.0$ (Task completed).
|
| 27 |
+
- **Partial**: Scaled based on percentage of PII fixed (e.g., $0.33$ per user record cleaned).
|
| 28 |
+
- **Penalty**: $0.0$ for invalid endpoints or malformed JSON.
|
docs/scaling.md
ADDED
|
@@ -0,0 +1,17 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# π Scaling & Complexity
|
| 2 |
+
|
| 3 |
+
`DataPrivacyEnv` is designed to scale across three dimensions:
|
| 4 |
+
|
| 5 |
+
## 1. Data Volume
|
| 6 |
+
While the current environment uses a small mock dataset, the `_get_initial_state` method can be extended to pull from **synthetic data generators**. This allows for "Needle in a Haystack" testing where an agent must scan millions of logs to find a single leak.
|
| 7 |
+
|
| 8 |
+
## 2. Task Complexity
|
| 9 |
+
Future iterations include **Multi-Step Dependency** tasks:
|
| 10 |
+
- **Contextual Redaction**: Redacting a name only if it appears near a sensitive keyword (e.g., "Salary").
|
| 11 |
+
- **Cross-Endpoint Verification**: Deleting a user in the CRM and then verifying their removal from the Auth-Server.
|
| 12 |
+
|
| 13 |
+
## 3. Compliance Diversity
|
| 14 |
+
The environment can be easily tuned for different regulatory frameworks:
|
| 15 |
+
- **GDPR**: Focus on "Right to be Forgotten" (Deletion).
|
| 16 |
+
- **PCI-DSS**: Focus on Credit Card Number (CCN) masking in transaction logs.
|
| 17 |
+
- **HIPAA**: Focus on Patient Health Information (PHI) anonymization.
|
docs/training.md
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# ποΈ Training Guide
|
| 2 |
+
|
| 3 |
+
To train an agent on `DataPrivacyEnv`, you can use the standard `openenv-core` interface.
|
| 4 |
+
|
| 5 |
+
## π οΈ Basic Training Loop (Pseudocode)
|
| 6 |
+
```python
|
| 7 |
+
from openenv_core import make
|
| 8 |
+
from stable_baselines3 import PPO
|
| 9 |
+
|
| 10 |
+
# Initialize the environment
|
| 11 |
+
env = make("data-privacy-env")
|
| 12 |
+
|
| 13 |
+
# Initialize a RL model (e.g., Proximal Policy Optimization)
|
| 14 |
+
model = PPO("MultiInputPolicy", env, verbose=1)
|
| 15 |
+
|
| 16 |
+
# Train for 10,000 steps
|
| 17 |
+
model.learn(total_timesteps=10000)
|
| 18 |
+
|
| 19 |
+
# Save the trained agent
|
| 20 |
+
model.save("pii_redactor_agent")
|
| 21 |
+
π Benchmarking
|
| 22 |
+
We recommend training across all three tasks (easy, medium, hard) to ensure the agent learns generalizable redaction strategies rather than just hardcoding specific log IDs.
|