Paramveer singh commited on
Commit
04fb48a
Β·
1 Parent(s): af1b492

Docs: Added comprehensive technical documentation suite

Browse files
Files changed (4) hide show
  1. docs/deployment.md +15 -0
  2. docs/environment.md +28 -0
  3. docs/scaling.md +17 -0
  4. 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.