armos 0.1.0__tar.gz

armos-0.1.0/.claude/settings.local.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(pip3 --version)",
+      "Bash(pip3 install *)"
+    ]
+  }
+}

armos-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.env
+.venv
+venv/
+env/
+.pytest_cache/
+.coverage
+htmlcov/
+*.pyc
+.DS_Store

armos-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Armos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

armos-0.1.0/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: armos
+Version: 0.1.0
+Summary: Automatic PII masking for OpenAI and Anthropic SDKs
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.9
+Requires-Dist: presidio-analyzer>=2.2.0
+Requires-Dist: presidio-anonymizer>=2.2.0
+Requires-Dist: spacy>=3.7.0
+Provides-Extra: all
+Requires-Dist: anthropic>=0.20.0; extra == 'all'
+Requires-Dist: openai>=1.0.0; extra == 'all'
+Requires-Dist: redis>=5.0.0; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.20.0; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: python-dotenv>=1.0.0; extra == 'dev'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == 'openai'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0.0; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# Armos
+
+**PII never reaches your LLM. One line of code.**
+
+Armos wraps the OpenAI and Anthropic SDKs to automatically detect and mask personally identifiable information (PII) before it leaves your server — and restore the real values in the response. Your application code changes by exactly one word.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+
+---
+
+## The problem
+
+Every time your application calls an LLM, it sends raw text to a third-party server. If a user's message contains their name, Aadhaar number, email, PAN card, or credit card — that data leaves your infrastructure.
+
+This matters for:
+- **Healthcare apps** — patient names, dates of birth, medical IDs
+- **Fintech apps** — PAN, Aadhaar, bank details
+- **Customer support tools** — names, emails, phone numbers, addresses
+- **Any app** where users type free text that gets sent to OpenAI or Anthropic
+
+Most teams know this is a risk. Few have time to build a proper masking layer before shipping. Armos is that layer, pre-built.
+
+---
+
+## How it works
+
+![How Armos works](assets/how-it-works.png)
+
+**Detection runs entirely on your machine.** Presidio + spaCy analyse the text locally. No data is sent to any Armos server — there is no Armos server. The vault (token ↔ real value map) lives in your process memory, or optionally in your own Redis instance.
+
+---
+
+## Quickstart
+
+### Install
+
+```bash
+pip install armos
+```
+
+For Redis-backed persistence across requests:
+```bash
+pip install armos[redis]
+```
+
+> **Note:** On first use, download the spaCy language model:
+> ```bash
+> python -m spacy download en_core_web_lg
+> ```
+
+### OpenAI
+
+```python
+# Before
+from openai import OpenAI
+client = OpenAI()
+
+# After — one import added, one word changed
+from openai import OpenAI
+from armos import ArmosOpenAI
+
+client = ArmosOpenAI(OpenAI())
+
+# Everything else is identical
+response = client.chat.completions.create(
+    model="gpt-4o",
+    messages=[{
+        "role": "user",
+        "content": "Summarise the case for patient John Smith, Aadhaar 2345 6789 0123"
+    }]
+)
+
+# Real values are restored in the response automatically
+print(response.choices[0].message.content)
+```
+
+### Anthropic
+
+```python
+from anthropic import Anthropic
+from armos import ArmosAnthropic
+
+client = ArmosAnthropic(Anthropic())
+
+message = client.messages.create(
+    model="claude-sonnet-4-6",
+    max_tokens=1024,
+    messages=[{
+        "role": "user",
+        "content": "Patient John Smith, DOB 12/04/1982, PAN ABCDE1234F"
+    }]
+)
+
+print(message.content[0].text)  # real values restored
+```
+
+### With Redis (persistent vault across requests)
+
+```python
+# Token mappings survive across processes and requests
+client = ArmosOpenAI(OpenAI(), store="redis://localhost:6379")
+client = ArmosAnthropic(Anthropic(), store="redis://localhost:6379")
+
+# Custom TTL (default: 24 hours)
+client = ArmosOpenAI(OpenAI(), store="redis://localhost:6379", vault_ttl=3600)
+```
+
+### Standalone (any LLM or framework)
+
+```python
+from armos import Armos
+
+guard = Armos()
+
+result = guard.mask("Patient John Smith, Aadhaar 2345 6789 0123, email john@hospital.com")
+print(result.text)
+# → "Patient [PII:NAME:a1b2c3d4], Aadhaar [PII:AADHAAR:b2c3d4e5], email [PII:EMAIL:e5f6g7h8]"
+
+print(result.has_pii)  # True
+
+restored = guard.demask(result.text)
+print(restored)
+# → "Patient John Smith, Aadhaar 2345 6789 0123, email john@hospital.com"
+```
+
+---
+
+## What gets detected
+
+| Entity | Token | Example |
+|--------|-------|---------|
+| Person name | `[PII:NAME:…]` | John Smith |
+| Email address | `[PII:EMAIL:…]` | john@hospital.com |
+| Phone number | `[PII:PHONE:…]` | +91 98765 43210 |
+| Aadhaar number | `[PII:AADHAAR:…]` | 2345 6789 0123 |
+| PAN card | `[PII:PAN:…]` | ABCDE1234F |
+| Credit / debit card | `[PII:CARD:…]` | 4111 1111 1111 1111 |
+| IP address | `[PII:IP:…]` | 192.168.1.100 |
+| API keys & secrets | `[PII:APIKEY:…]` | sk-abc123… / AKIA… / ghp_… |
+
+---
+
+## Token design
+
+Tokens are **deterministic** and **normalisation-aware**:
+
+```
+"john smith"  →  [PII:NAME:a1b2c3d4]  ← stored: "john smith"
+"John Smith"  →  [PII:NAME:a1b2c3d4]  ← same token, vault unchanged
+"JOHN SMITH"  →  [PII:NAME:a1b2c3d4]  ← same token, vault unchanged
+```
+
+All casing variants of the same name map to one token. The LLM sees one consistent entity across a conversation — not three different people. De-masking restores the first-seen value.
+
+---
+
+## Vault options
+
+| Option | Default | Use when |
+|--------|---------|----------|
+| In-memory | `Armos()` | Single request or single process |
+| Redis | `Armos(store="redis://…")` | Multi-turn conversations, multiple workers, or across requests |
+
+In-memory vault is zero configuration and the default. Redis vault persists token mappings so a token created in request 1 can be de-masked in request 5.
+
+---
+
+## v1 limitations
+
+1. **Streaming not supported** — `stream=True` passes through without masking. (v1.1)
+2. **Async clients not supported** — `AsyncOpenAI`, `AsyncAnthropic` pass through without masking. (v1.1)
+3. **OpenAI Responses API not intercepted** — `client.responses.create()` passes through. (v1.1)
+4. **Embeddings not masked** — `client.embeddings.create()` sends text as-is. (v1.1)
+5. **Indian name accuracy** — `en_core_web_lg` is trained on English text; Indian names have lower recall than Western names. Fine-tuning planned for v2.
+6. **Casing: first-seen wins** — De-masking always restores the first-seen casing of an entity. Use consistent casing in your prompts for exact restoration.
+7. **Token length** — `[PII:NAME:a1b2c3d4]` is 18 chars vs `John` (4 chars). Near context-window limits this may push content over. Rare in practice.
+
+---
+
+## Contributing
+
+Armos is open source and MIT licensed. Issues and pull requests welcome.
+
+```bash
+git clone https://github.com/armos-ai/armos
+cd armos
+pip install -e ".[dev,all]"
+python -m spacy download en_core_web_lg
+pytest tests/ -v
+```
+
+## License
+
+MIT

armos-0.1.0/README.md

@@ -0,0 +1,195 @@
+# Armos
+
+**PII never reaches your LLM. One line of code.**
+
+Armos wraps the OpenAI and Anthropic SDKs to automatically detect and mask personally identifiable information (PII) before it leaves your server — and restore the real values in the response. Your application code changes by exactly one word.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+
+---
+
+## The problem
+
+Every time your application calls an LLM, it sends raw text to a third-party server. If a user's message contains their name, Aadhaar number, email, PAN card, or credit card — that data leaves your infrastructure.
+
+This matters for:
+- **Healthcare apps** — patient names, dates of birth, medical IDs
+- **Fintech apps** — PAN, Aadhaar, bank details
+- **Customer support tools** — names, emails, phone numbers, addresses
+- **Any app** where users type free text that gets sent to OpenAI or Anthropic
+
+Most teams know this is a risk. Few have time to build a proper masking layer before shipping. Armos is that layer, pre-built.
+
+---
+
+## How it works
+
+![How Armos works](assets/how-it-works.png)
+
+**Detection runs entirely on your machine.** Presidio + spaCy analyse the text locally. No data is sent to any Armos server — there is no Armos server. The vault (token ↔ real value map) lives in your process memory, or optionally in your own Redis instance.
+
+---
+
+## Quickstart
+
+### Install
+
+```bash
+pip install armos
+```
+
+For Redis-backed persistence across requests:
+```bash
+pip install armos[redis]
+```
+
+> **Note:** On first use, download the spaCy language model:
+> ```bash
+> python -m spacy download en_core_web_lg
+> ```
+
+### OpenAI
+
+```python
+# Before
+from openai import OpenAI
+client = OpenAI()
+
+# After — one import added, one word changed
+from openai import OpenAI
+from armos import ArmosOpenAI
+
+client = ArmosOpenAI(OpenAI())
+
+# Everything else is identical
+response = client.chat.completions.create(
+    model="gpt-4o",
+    messages=[{
+        "role": "user",
+        "content": "Summarise the case for patient John Smith, Aadhaar 2345 6789 0123"
+    }]
+)
+
+# Real values are restored in the response automatically
+print(response.choices[0].message.content)
+```
+
+### Anthropic
+
+```python
+from anthropic import Anthropic
+from armos import ArmosAnthropic
+
+client = ArmosAnthropic(Anthropic())
+
+message = client.messages.create(
+    model="claude-sonnet-4-6",
+    max_tokens=1024,
+    messages=[{
+        "role": "user",
+        "content": "Patient John Smith, DOB 12/04/1982, PAN ABCDE1234F"
+    }]
+)
+
+print(message.content[0].text)  # real values restored
+```
+
+### With Redis (persistent vault across requests)
+
+```python
+# Token mappings survive across processes and requests
+client = ArmosOpenAI(OpenAI(), store="redis://localhost:6379")
+client = ArmosAnthropic(Anthropic(), store="redis://localhost:6379")
+
+# Custom TTL (default: 24 hours)
+client = ArmosOpenAI(OpenAI(), store="redis://localhost:6379", vault_ttl=3600)
+```
+
+### Standalone (any LLM or framework)
+
+```python
+from armos import Armos
+
+guard = Armos()
+
+result = guard.mask("Patient John Smith, Aadhaar 2345 6789 0123, email john@hospital.com")
+print(result.text)
+# → "Patient [PII:NAME:a1b2c3d4], Aadhaar [PII:AADHAAR:b2c3d4e5], email [PII:EMAIL:e5f6g7h8]"
+
+print(result.has_pii)  # True
+
+restored = guard.demask(result.text)
+print(restored)
+# → "Patient John Smith, Aadhaar 2345 6789 0123, email john@hospital.com"
+```
+
+---
+
+## What gets detected
+
+| Entity | Token | Example |
+|--------|-------|---------|
+| Person name | `[PII:NAME:…]` | John Smith |
+| Email address | `[PII:EMAIL:…]` | john@hospital.com |
+| Phone number | `[PII:PHONE:…]` | +91 98765 43210 |
+| Aadhaar number | `[PII:AADHAAR:…]` | 2345 6789 0123 |
+| PAN card | `[PII:PAN:…]` | ABCDE1234F |
+| Credit / debit card | `[PII:CARD:…]` | 4111 1111 1111 1111 |
+| IP address | `[PII:IP:…]` | 192.168.1.100 |
+| API keys & secrets | `[PII:APIKEY:…]` | sk-abc123… / AKIA… / ghp_… |
+
+---
+
+## Token design
+
+Tokens are **deterministic** and **normalisation-aware**:
+
+```
+"john smith"  →  [PII:NAME:a1b2c3d4]  ← stored: "john smith"
+"John Smith"  →  [PII:NAME:a1b2c3d4]  ← same token, vault unchanged
+"JOHN SMITH"  →  [PII:NAME:a1b2c3d4]  ← same token, vault unchanged
+```
+
+All casing variants of the same name map to one token. The LLM sees one consistent entity across a conversation — not three different people. De-masking restores the first-seen value.
+
+---
+
+## Vault options
+
+| Option | Default | Use when |
+|--------|---------|----------|
+| In-memory | `Armos()` | Single request or single process |
+| Redis | `Armos(store="redis://…")` | Multi-turn conversations, multiple workers, or across requests |
+
+In-memory vault is zero configuration and the default. Redis vault persists token mappings so a token created in request 1 can be de-masked in request 5.
+
+---
+
+## v1 limitations
+
+1. **Streaming not supported** — `stream=True` passes through without masking. (v1.1)
+2. **Async clients not supported** — `AsyncOpenAI`, `AsyncAnthropic` pass through without masking. (v1.1)
+3. **OpenAI Responses API not intercepted** — `client.responses.create()` passes through. (v1.1)
+4. **Embeddings not masked** — `client.embeddings.create()` sends text as-is. (v1.1)
+5. **Indian name accuracy** — `en_core_web_lg` is trained on English text; Indian names have lower recall than Western names. Fine-tuning planned for v2.
+6. **Casing: first-seen wins** — De-masking always restores the first-seen casing of an entity. Use consistent casing in your prompts for exact restoration.
+7. **Token length** — `[PII:NAME:a1b2c3d4]` is 18 chars vs `John` (4 chars). Near context-window limits this may push content over. Rare in practice.
+
+---
+
+## Contributing
+
+Armos is open source and MIT licensed. Issues and pull requests welcome.
+
+```bash
+git clone https://github.com/armos-ai/armos
+cd armos
+pip install -e ".[dev,all]"
+python -m spacy download en_core_web_lg
+pytest tests/ -v
+```
+
+## License
+
+MIT

armos-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "armos"
+version = "0.1.0"
+description = "Automatic PII masking for OpenAI and Anthropic SDKs"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+license-files = ["LICENSE"]
+
+dependencies = [
+    "presidio-analyzer>=2.2.0",
+    "presidio-anonymizer>=2.2.0",
+    "spacy>=3.7.0",
+]
+
+[project.optional-dependencies]
+redis = ["redis>=5.0.0"]
+openai = ["openai>=1.0.0"]
+anthropic = ["anthropic>=0.20.0"]
+all = ["redis>=5.0.0", "openai>=1.0.0", "anthropic>=0.20.0"]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "python-dotenv>=1.0.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/armos"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

armos-0.1.0/src/armos/__init__.py

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: MIT
+"""
+Armos — Automatic PII masking for OpenAI and Anthropic SDKs.
+
+One line change. PII never reaches your LLM provider.
+
+Quick start:
+    from openai import OpenAI
+    from armos import ArmosOpenAI
+
+    client = ArmosOpenAI(OpenAI())
+    # Use exactly as you would the normal OpenAI client.
+    # PII is masked automatically before every request.
+    # Real values are restored automatically in every response.
+"""
+
+from .guard import Armos
+from .wrappers.openai import ArmosOpenAI
+from .wrappers.anthropic import ArmosAnthropic
+from .models import MaskResult, DetectedEntity
+
+__version__ = "0.1.0"
+__all__ = [
+    "Armos",
+    "ArmosOpenAI",
+    "ArmosAnthropic",
+    "MaskResult",
+    "DetectedEntity",
+]

armos-0.1.0/src/armos/detection/__init__.py

@@ -0,0 +1 @@
+# SPDX-License-Identifier: MIT

armos-0.1.0/src/armos/detection/engine.py

@@ -0,0 +1,99 @@
+# SPDX-License-Identifier: MIT
+from typing import List
+from presidio_analyzer import AnalyzerEngine, RecognizerRegistry
+from presidio_analyzer.nlp_engine import NlpEngineProvider
+
+from ..models import DetectedEntity
+from .recognisers.aadhaar import AadhaarRecogniser
+from .recognisers.pan import PANRecogniser
+from .recognisers.standard import APIKeyRecogniser
+
+
+ENTITY_TYPES = [
+    "PERSON",
+    "EMAIL_ADDRESS",
+    "PHONE_NUMBER",
+    "AADHAAR_NUMBER",
+    "IN_PAN",
+    "CREDIT_CARD",
+    "IP_ADDRESS",
+    "API_KEY",
+]
+
+ENTITY_SHORT_CODES = {
+    "PERSON":         "NAME",
+    "EMAIL_ADDRESS":  "EMAIL",
+    "PHONE_NUMBER":   "PHONE",
+    "AADHAAR_NUMBER": "AADHAAR",
+    "IN_PAN":         "PAN",
+    "CREDIT_CARD":    "CARD",
+    "IP_ADDRESS":     "IP",
+    "API_KEY":        "APIKEY",
+}
+
+
+class DetectionEngine:
+    """
+    Orchestrates all PII recognisers.
+    Detection runs entirely locally — no text is sent anywhere.
+    """
+
+    def __init__(self):
+        self._analyzer = self._build_analyzer()
+
+    def _build_analyzer(self) -> AnalyzerEngine:
+        configuration = {
+            "nlp_engine_name": "spacy",
+            "models": [{"lang_code": "en", "model_name": "en_core_web_lg"}],
+        }
+        provider = NlpEngineProvider(nlp_configuration=configuration)
+        nlp_engine = provider.create_engine()
+
+        registry = RecognizerRegistry()
+        registry.load_predefined_recognizers(nlp_engine=nlp_engine)
+
+        registry.add_recognizer(AadhaarRecogniser())
+        registry.add_recognizer(PANRecogniser())
+        registry.add_recognizer(APIKeyRecogniser())
+
+        return AnalyzerEngine(nlp_engine=nlp_engine, registry=registry)
+
+    def detect(self, text: str, language: str = "en") -> List[DetectedEntity]:
+        """Detect all PII in text. Returns entities sorted by position."""
+        if not text or not text.strip():
+            return []
+
+        results = self._analyzer.analyze(
+            text=text,
+            entities=ENTITY_TYPES,
+            language=language,
+        )
+
+        entities = [
+            DetectedEntity(
+                entity_type=ENTITY_SHORT_CODES.get(r.entity_type, r.entity_type),
+                text=text[r.start:r.end],
+                start=r.start,
+                end=r.end,
+                score=r.score,
+            )
+            for r in results
+        ]
+
+        entities.sort(key=lambda e: e.start)
+        return self._resolve_overlaps(entities)
+
+    def _resolve_overlaps(self, entities: List[DetectedEntity]) -> List[DetectedEntity]:
+        """Remove overlapping detections. Higher confidence wins."""
+        if not entities:
+            return entities
+
+        resolved = [entities[0]]
+        for current in entities[1:]:
+            previous = resolved[-1]
+            if current.start < previous.end:
+                if current.score > previous.score:
+                    resolved[-1] = current
+            else:
+                resolved.append(current)
+        return resolved

armos-0.1.0/src/armos/detection/recognisers/__init__.py

@@ -0,0 +1 @@
+# SPDX-License-Identifier: MIT

armos-0.1.0/src/armos/detection/recognisers/aadhaar.py

@@ -0,0 +1,45 @@
+# SPDX-License-Identifier: MIT
+from presidio_analyzer import Pattern, PatternRecognizer
+
+
+class AadhaarRecogniser(PatternRecognizer):
+    """
+    Detects Indian Aadhaar numbers.
+
+    Format: 12 digits. First digit cannot be 0 or 1.
+    Common representations:
+        2345 6789 0123   (spaces — most common)
+        2345-6789-0123   (hyphens)
+        234567890123     (no separator — lower confidence)
+    """
+
+    PATTERNS = [
+        Pattern(
+            name="aadhaar_spaces",
+            regex=r"\b[2-9]\d{3}\s\d{4}\s\d{4}\b",
+            score=0.95,
+        ),
+        Pattern(
+            name="aadhaar_hyphens",
+            regex=r"\b[2-9]\d{3}-\d{4}-\d{4}\b",
+            score=0.95,
+        ),
+        Pattern(
+            name="aadhaar_plain",
+            regex=r"\b[2-9]\d{11}\b",
+            score=0.6,
+        ),
+    ]
+
+    CONTEXT = [
+        "aadhaar", "aadhar", "uid", "uidai",
+        "unique identification", "biometric id", "aadhaaar"
+    ]
+
+    def __init__(self):
+        super().__init__(
+            supported_entity="AADHAAR_NUMBER",
+            patterns=self.PATTERNS,
+            context=self.CONTEXT,
+            supported_language="en",
+        )