guard-agent 2.0.0__tar.gz

guard_agent-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Renzo Franceschini
+
+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.

guard_agent-2.0.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include guard_agent/py.typed
+include LICENSE
+include README.md

guard_agent-2.0.0/PKG-INFO

@@ -0,0 +1,335 @@
+Metadata-Version: 2.4
+Name: guard-agent
+Version: 2.0.0
+Summary: Framework-agnostic telemetry and monitoring agent for the Guard security ecosystem (fastapi-guard, flaskapi-guard, djangoapi-guard, tornadoapi-guard)
+Author-email: Renzo Franceschini <rennf93@users.noreply.github.com>
+License: MIT
+Project-URL: Homepage, https://guard-core.com
+Project-URL: Documentation, https://rennf93.github.io/guard-agent/latest/
+Project-URL: Repository, https://github.com/rennf93/guard-agent
+Project-URL: Changelog, https://github.com/rennf93/guard-agent/blob/master/CHANGELOG.md
+Project-URL: Bug Tracker, https://github.com/rennf93/guard-agent/issues
+Project-URL: Cloud Dashboard, https://app.guard-core.com
+Project-URL: Live Playground, https://playground.guard-core.com
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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 :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Monitoring
+Requires-Python: <3.15,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography
+Requires-Dist: httpx
+Requires-Dist: pydantic
+Requires-Dist: typing-extensions
+Provides-Extra: dev
+Requires-Dist: black; extra == "dev"
+Requires-Dist: fastapi; extra == "dev"
+Requires-Dist: fastapi-guard>=5.0.0; extra == "dev"
+Requires-Dist: httpx; extra == "dev"
+Requires-Dist: mkdocs; extra == "dev"
+Requires-Dist: mkdocstrings; extra == "dev"
+Requires-Dist: mkdocstrings-python; extra == "dev"
+Requires-Dist: mkdocs-material; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: psutil; extra == "dev"
+Requires-Dist: pymarkdownlnt; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-mock; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: types-psutil; extra == "dev"
+Requires-Dist: types-setuptools; extra == "dev"
+Provides-Extra: redis
+Requires-Dist: redis; extra == "redis"
+Dynamic: license-file
+
+<p align="center">
+    <a href="https://rennf93.github.io/guard-agent/latest/">
+        <img src="https://rennf93.github.io/guard-agent/latest/assets/big_logo.svg" alt="Guard Agent">
+    </a>
+</p>
+
+---
+
+<p align="center">
+    <strong>Guard Agent is an enterprise-grade, framework-agnostic telemetry and monitoring agent for the Guard security ecosystem. It integrates with <code>fastapi-guard</code>, <code>flaskapi-guard</code>, <code>djangoapi-guard</code>, and <code>tornadoapi-guard</code> to provide centralized security intelligence, real-time policy updates, and comprehensive event collection across any Python web framework.</strong>
+</p>
+
+<p align="center">
+    <a href="https://badge.fury.io/py/guard-agent">
+        <img src="https://badge.fury.io/py/guard-agent.svg?cache=none&icon=si%3Apython&icon_color=%23008cb4" alt="PyPiVersion">
+    </a>
+    <a href="https://github.com/rennf93/guard-agent/actions/workflows/release.yml">
+        <img src="https://github.com/rennf93/guard-agent/actions/workflows/release.yml/badge.svg" alt="Release">
+    </a>
+    <a href="https://opensource.org/licenses/MIT">
+        <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License">
+    </a>
+    <a href="https://github.com/rennf93/guard-agent/actions/workflows/ci.yml">
+        <img src="https://github.com/rennf93/guard-agent/actions/workflows/ci.yml/badge.svg" alt="CI">
+    </a>
+    <a href="https://github.com/rennf93/guard-agent/actions/workflows/code-ql.yml">
+        <img src="https://github.com/rennf93/guard-agent/actions/workflows/code-ql.yml/badge.svg" alt="CodeQL">
+    </a>
+</p>
+
+<p align="center">
+    <a href="https://github.com/rennf93/guard-agent/actions/workflows/pages/pages-build-deployment">
+        <img src="https://github.com/rennf93/guard-agent/actions/workflows/pages/pages-build-deployment/badge.svg?branch=gh-pages" alt="PagesBuildDeployment">
+    </a>
+    <a href="https://github.com/rennf93/guard-agent/actions/workflows/docs.yml">
+        <img src="https://github.com/rennf93/guard-agent/actions/workflows/docs.yml/badge.svg" alt="DocsUpdate">
+    </a>
+    <img src="https://img.shields.io/github/last-commit/rennf93/guard-agent?style=flat&amp;logo=git&amp;logoColor=white&amp;color=0080ff" alt="last-commit">
+</p>
+
+<p align="center">
+    <img src="https://img.shields.io/badge/Python-3776AB.svg?style=flat&amp;logo=Python&amp;logoColor=white" alt="Python">
+    <img src="https://img.shields.io/badge/Redis-FF4438.svg?style=flat&amp;logo=Redis&amp;logoColor=white" alt="Redis">
+    <a href="https://pepy.tech/project/guard-agent">
+        <img src="https://pepy.tech/badge/guard-agent" alt="Downloads">
+    </a>
+</p>
+
+<p align="center">
+  <a href="https://guard-core.com">Website</a> &middot;
+  <a href="https://rennf93.github.io/guard-agent/latest/">Docs</a> &middot;
+  <a href="https://playground.guard-core.com">Playground</a> &middot;
+  <a href="https://app.guard-core.com">Dashboard</a> &middot;
+  <a href="https://discord.gg/ZW7ZJbjMkK">Discord</a>
+</p>
+
+<p align="center">
+  Framework-agnostic security telemetry for Python web apps.<br>
+  Feeds the Guard dashboard with events, metrics, and dynamic rules from any supported adapter.
+</p>
+
+---
+
+> **Renamed from `fastapi-guard-agent`.** As of `guard-agent` 2.0.0, the package has been renamed to reflect its multi-framework scope. The Python import path (`from guard_agent import ...`) is unchanged. Existing `pip install fastapi-guard-agent` commands continue to work via a meta-package that transitively pulls the renamed distribution.
+
+---
+
+Documentation & Platform
+========================
+
+- 🌐 **[guard-core.com](https://guard-core.com)** — marketing site & product overview
+- 📚 **[Documentation](https://rennf93.github.io/guard-agent/latest/)** — full technical documentation
+- 🎮 **[Playground](https://playground.guard-core.com)** — try the Guard stack in-browser, no install required
+- 📊 **[Dashboard](https://app.guard-core.com)** — real-time security events, metrics, and dynamic rules for your projects
+- 💬 **[Discord](https://discord.gg/ZW7ZJbjMkK)** — community & maintainer support
+
+---
+
+Supported Adapters
+------------------
+
+Guard Agent is framework-agnostic. Pair it with the adapter for your stack:
+
+| Framework | Adapter package | Status |
+|-----------|-----------------|--------|
+| FastAPI   | [`fastapi-guard`](https://github.com/rennf93/fastapi-guard) | Stable |
+| Flask     | [`flaskapi-guard`](https://github.com/rennf93/flaskapi-guard) | Stable |
+| Django    | [`djangoapi-guard`](https://github.com/rennf93/djangoapi-guard) | Stable |
+| Tornado   | [`tornadoapi-guard`](https://github.com/rennf93/tornadoapi-guard) | Stable |
+
+All adapters share the same Guard Agent runtime and dashboard — a single telemetry contract across every framework.
+
+---
+
+Key Features
+------------
+
+-   **Framework-Agnostic Core**: One agent, one dashboard — works with every Guard adapter (FastAPI, Flask, Django, Tornado) through a shared wire protocol.
+-   **Automatic Integration**: Adapters wire the agent into their middleware automatically. Enable it through the adapter's `SecurityConfig` — no glue code required.
+-   **High-Performance Architecture**: Built on asynchronous I/O principles to ensure zero performance impact on your application while maintaining real-time data collection capabilities.
+-   **Enterprise-Grade Reliability**: Implements industry-standard resilience patterns including circuit breakers, exponential backoff with jitter, and intelligent retry mechanisms to guarantee data delivery.
+-   **Intelligent Data Management**: Features multi-tier buffering with in-memory and optional Redis persistence, ensuring zero data loss during network interruptions or application restarts.
+-   **Real-Time Security Updates**: Supports dynamic security policy updates from the centralized management platform, enabling immediate threat response without service interruption.
+-   **Extensible Architecture**: Designed with protocol-based abstractions, allowing seamless integration with custom transport layers, storage backends, and monitoring systems.
+-   **Comprehensive Security Intelligence**: Captures granular security events and performance metrics, providing actionable insights for security operations and compliance requirements.
+
+---
+
+Installation
+------------
+
+```bash
+pip install guard-agent
+```
+
+Or with `uv`:
+
+```bash
+uv add guard-agent
+```
+
+> The legacy name `fastapi-guard-agent` is still published as a meta-package that installs `guard-agent` transitively — existing installs keep working, but new projects should use `guard-agent` directly.
+
+Optional extras:
+
+```bash
+pip install "guard-agent[redis]"    # Enable Redis-backed event buffer
+```
+
+---
+
+Getting Started
+---------------
+
+Guard Agent is embedded directly by your framework's adapter — you enable it through the adapter's security config rather than importing it manually.
+
+### FastAPI example
+
+```python
+from fastapi import FastAPI
+from guard import SecurityConfig, SecurityMiddleware
+
+config = SecurityConfig(
+    auto_ban_threshold=5,
+    auto_ban_duration=300,
+
+    # Enable agent telemetry
+    enable_agent=True,
+    agent_api_key="YOUR_API_KEY",
+    agent_project_id="YOUR_PROJECT_ID",
+    agent_endpoint="https://api.guard-core.com",
+
+    agent_buffer_size=100,
+    agent_flush_interval=30,
+    agent_enable_events=True,
+    agent_enable_metrics=True,
+
+    enable_dynamic_rules=True,
+    dynamic_rule_interval=300,
+)
+
+app = FastAPI()
+SecurityMiddleware(app, config=config)
+
+@app.get("/")
+async def root():
+    return {"message": "Hello World"}
+```
+
+Flask, Django, and Tornado adapters expose analogous `SecurityConfig` interfaces — see each adapter's README for framework-native examples.
+
+With `enable_agent=True`, the agent automatically:
+
+- Captures security violations (IP bans, rate-limit breaches, suspicious request patterns)
+- Collects performance telemetry for security operations monitoring
+- Synchronizes security policies from the centralized management platform
+- Implements intelligent buffering for optimal network utilization
+- Recovers automatically from transient network failures
+
+---
+
+Advanced Configuration
+----------------------
+
+For standalone use or custom event handling, instantiate the agent directly:
+
+```python
+from guard_agent.client import guard_agent
+from guard_agent.models import AgentConfig
+
+config = AgentConfig(
+    api_key="YOUR_API_KEY",
+    project_id="YOUR_PROJECT_ID",
+)
+
+agent = guard_agent(config)
+```
+
+### Configuration Parameters
+
+#### Authentication & Identification
+-   **`api_key: str`** (Required): Authentication key for the Guard management platform
+-   **`project_id: str | None`**: Unique project identifier for data segregation and multi-tenancy support
+
+#### Network Configuration
+-   **`endpoint: str`**: Management platform API endpoint (Default: `https://api.guard-core.com`)
+-   **`timeout: int`**: HTTP request timeout in seconds (Default: `30`)
+-   **`retry_attempts: int`**: Maximum retry attempts for failed requests (Default: `3`)
+-   **`backoff_factor: float`**: Exponential backoff multiplier for retry delays (Default: `1.0`)
+
+#### Data Management
+-   **`buffer_size: int`**: Maximum events in memory buffer before automatic flush (Default: `100`)
+-   **`flush_interval: int`**: Automatic buffer flush interval in seconds (Default: `30`)
+-   **`max_payload_size: int`**: Maximum payload size in bytes before truncation (Default: `1024`)
+
+#### Feature Control
+-   **`enable_metrics: bool`**: Enable performance metrics collection (Default: `True`)
+-   **`enable_events: bool`**: Enable security event collection (Default: `True`)
+
+#### Security & Privacy
+-   **`sensitive_headers: list[str]`**: HTTP headers to redact from collected data (Default: `["authorization", "cookie", "x-api-key"]`)
+
+---
+
+Migration from `fastapi-guard-agent`
+------------------------------------
+
+No code changes required. The import path was always `guard_agent`:
+
+```python
+# This worked before and still works:
+from guard_agent import GuardAgentHandler, AgentConfig
+```
+
+To switch your install command:
+
+```bash
+# Old (still works via shim)
+pip install fastapi-guard-agent
+
+# New (preferred)
+pip install guard-agent
+```
+
+The legacy `fastapi-guard-agent` name is maintained as a meta-package pointing to `guard-agent>=2.0.0,<3.0.0`, so pinned environments keep resolving correctly.
+
+---
+
+Contributing
+------------
+
+Contributions are welcome! Please open an issue or submit a pull request on GitHub.
+
+---
+
+License
+-------
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+---
+
+Author
+------
+
+Renzo Franceschini - [rennf93@users.noreply.github.com](mailto:rennf93@users.noreply.github.com)
+
+---
+
+Acknowledgements
+----------------
+
+- [FastAPI](https://fastapi.tiangolo.com/)
+- [Flask](https://flask.palletsprojects.com/)
+- [Django](https://www.djangoproject.com/)
+- [Tornado](https://www.tornadoweb.org/)
+- [Redis](https://redis.io/)
+- [httpx](https://www.python-httpx.org/)
+- [Pydantic](https://pydantic-docs.helpmanual.io/)

guard_agent-2.0.0/README.md

@@ -0,0 +1,279 @@
+<p align="center">
+    <a href="https://rennf93.github.io/guard-agent/latest/">
+        <img src="https://rennf93.github.io/guard-agent/latest/assets/big_logo.svg" alt="Guard Agent">
+    </a>
+</p>
+
+---
+
+<p align="center">
+    <strong>Guard Agent is an enterprise-grade, framework-agnostic telemetry and monitoring agent for the Guard security ecosystem. It integrates with <code>fastapi-guard</code>, <code>flaskapi-guard</code>, <code>djangoapi-guard</code>, and <code>tornadoapi-guard</code> to provide centralized security intelligence, real-time policy updates, and comprehensive event collection across any Python web framework.</strong>
+</p>
+
+<p align="center">
+    <a href="https://badge.fury.io/py/guard-agent">
+        <img src="https://badge.fury.io/py/guard-agent.svg?cache=none&icon=si%3Apython&icon_color=%23008cb4" alt="PyPiVersion">
+    </a>
+    <a href="https://github.com/rennf93/guard-agent/actions/workflows/release.yml">
+        <img src="https://github.com/rennf93/guard-agent/actions/workflows/release.yml/badge.svg" alt="Release">
+    </a>
+    <a href="https://opensource.org/licenses/MIT">
+        <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License">
+    </a>
+    <a href="https://github.com/rennf93/guard-agent/actions/workflows/ci.yml">
+        <img src="https://github.com/rennf93/guard-agent/actions/workflows/ci.yml/badge.svg" alt="CI">
+    </a>
+    <a href="https://github.com/rennf93/guard-agent/actions/workflows/code-ql.yml">
+        <img src="https://github.com/rennf93/guard-agent/actions/workflows/code-ql.yml/badge.svg" alt="CodeQL">
+    </a>
+</p>
+
+<p align="center">
+    <a href="https://github.com/rennf93/guard-agent/actions/workflows/pages/pages-build-deployment">
+        <img src="https://github.com/rennf93/guard-agent/actions/workflows/pages/pages-build-deployment/badge.svg?branch=gh-pages" alt="PagesBuildDeployment">
+    </a>
+    <a href="https://github.com/rennf93/guard-agent/actions/workflows/docs.yml">
+        <img src="https://github.com/rennf93/guard-agent/actions/workflows/docs.yml/badge.svg" alt="DocsUpdate">
+    </a>
+    <img src="https://img.shields.io/github/last-commit/rennf93/guard-agent?style=flat&amp;logo=git&amp;logoColor=white&amp;color=0080ff" alt="last-commit">
+</p>
+
+<p align="center">
+    <img src="https://img.shields.io/badge/Python-3776AB.svg?style=flat&amp;logo=Python&amp;logoColor=white" alt="Python">
+    <img src="https://img.shields.io/badge/Redis-FF4438.svg?style=flat&amp;logo=Redis&amp;logoColor=white" alt="Redis">
+    <a href="https://pepy.tech/project/guard-agent">
+        <img src="https://pepy.tech/badge/guard-agent" alt="Downloads">
+    </a>
+</p>
+
+<p align="center">
+  <a href="https://guard-core.com">Website</a> &middot;
+  <a href="https://rennf93.github.io/guard-agent/latest/">Docs</a> &middot;
+  <a href="https://playground.guard-core.com">Playground</a> &middot;
+  <a href="https://app.guard-core.com">Dashboard</a> &middot;
+  <a href="https://discord.gg/ZW7ZJbjMkK">Discord</a>
+</p>
+
+<p align="center">
+  Framework-agnostic security telemetry for Python web apps.<br>
+  Feeds the Guard dashboard with events, metrics, and dynamic rules from any supported adapter.
+</p>
+
+---
+
+> **Renamed from `fastapi-guard-agent`.** As of `guard-agent` 2.0.0, the package has been renamed to reflect its multi-framework scope. The Python import path (`from guard_agent import ...`) is unchanged. Existing `pip install fastapi-guard-agent` commands continue to work via a meta-package that transitively pulls the renamed distribution.
+
+---
+
+Documentation & Platform
+========================
+
+- 🌐 **[guard-core.com](https://guard-core.com)** — marketing site & product overview
+- 📚 **[Documentation](https://rennf93.github.io/guard-agent/latest/)** — full technical documentation
+- 🎮 **[Playground](https://playground.guard-core.com)** — try the Guard stack in-browser, no install required
+- 📊 **[Dashboard](https://app.guard-core.com)** — real-time security events, metrics, and dynamic rules for your projects
+- 💬 **[Discord](https://discord.gg/ZW7ZJbjMkK)** — community & maintainer support
+
+---
+
+Supported Adapters
+------------------
+
+Guard Agent is framework-agnostic. Pair it with the adapter for your stack:
+
+| Framework | Adapter package | Status |
+|-----------|-----------------|--------|
+| FastAPI   | [`fastapi-guard`](https://github.com/rennf93/fastapi-guard) | Stable |
+| Flask     | [`flaskapi-guard`](https://github.com/rennf93/flaskapi-guard) | Stable |
+| Django    | [`djangoapi-guard`](https://github.com/rennf93/djangoapi-guard) | Stable |
+| Tornado   | [`tornadoapi-guard`](https://github.com/rennf93/tornadoapi-guard) | Stable |
+
+All adapters share the same Guard Agent runtime and dashboard — a single telemetry contract across every framework.
+
+---
+
+Key Features
+------------
+
+-   **Framework-Agnostic Core**: One agent, one dashboard — works with every Guard adapter (FastAPI, Flask, Django, Tornado) through a shared wire protocol.
+-   **Automatic Integration**: Adapters wire the agent into their middleware automatically. Enable it through the adapter's `SecurityConfig` — no glue code required.
+-   **High-Performance Architecture**: Built on asynchronous I/O principles to ensure zero performance impact on your application while maintaining real-time data collection capabilities.
+-   **Enterprise-Grade Reliability**: Implements industry-standard resilience patterns including circuit breakers, exponential backoff with jitter, and intelligent retry mechanisms to guarantee data delivery.
+-   **Intelligent Data Management**: Features multi-tier buffering with in-memory and optional Redis persistence, ensuring zero data loss during network interruptions or application restarts.
+-   **Real-Time Security Updates**: Supports dynamic security policy updates from the centralized management platform, enabling immediate threat response without service interruption.
+-   **Extensible Architecture**: Designed with protocol-based abstractions, allowing seamless integration with custom transport layers, storage backends, and monitoring systems.
+-   **Comprehensive Security Intelligence**: Captures granular security events and performance metrics, providing actionable insights for security operations and compliance requirements.
+
+---
+
+Installation
+------------
+
+```bash
+pip install guard-agent
+```
+
+Or with `uv`:
+
+```bash
+uv add guard-agent
+```
+
+> The legacy name `fastapi-guard-agent` is still published as a meta-package that installs `guard-agent` transitively — existing installs keep working, but new projects should use `guard-agent` directly.
+
+Optional extras:
+
+```bash
+pip install "guard-agent[redis]"    # Enable Redis-backed event buffer
+```
+
+---
+
+Getting Started
+---------------
+
+Guard Agent is embedded directly by your framework's adapter — you enable it through the adapter's security config rather than importing it manually.
+
+### FastAPI example
+
+```python
+from fastapi import FastAPI
+from guard import SecurityConfig, SecurityMiddleware
+
+config = SecurityConfig(
+    auto_ban_threshold=5,
+    auto_ban_duration=300,
+
+    # Enable agent telemetry
+    enable_agent=True,
+    agent_api_key="YOUR_API_KEY",
+    agent_project_id="YOUR_PROJECT_ID",
+    agent_endpoint="https://api.guard-core.com",
+
+    agent_buffer_size=100,
+    agent_flush_interval=30,
+    agent_enable_events=True,
+    agent_enable_metrics=True,
+
+    enable_dynamic_rules=True,
+    dynamic_rule_interval=300,
+)
+
+app = FastAPI()
+SecurityMiddleware(app, config=config)
+
+@app.get("/")
+async def root():
+    return {"message": "Hello World"}
+```
+
+Flask, Django, and Tornado adapters expose analogous `SecurityConfig` interfaces — see each adapter's README for framework-native examples.
+
+With `enable_agent=True`, the agent automatically:
+
+- Captures security violations (IP bans, rate-limit breaches, suspicious request patterns)
+- Collects performance telemetry for security operations monitoring
+- Synchronizes security policies from the centralized management platform
+- Implements intelligent buffering for optimal network utilization
+- Recovers automatically from transient network failures
+
+---
+
+Advanced Configuration
+----------------------
+
+For standalone use or custom event handling, instantiate the agent directly:
+
+```python
+from guard_agent.client import guard_agent
+from guard_agent.models import AgentConfig
+
+config = AgentConfig(
+    api_key="YOUR_API_KEY",
+    project_id="YOUR_PROJECT_ID",
+)
+
+agent = guard_agent(config)
+```
+
+### Configuration Parameters
+
+#### Authentication & Identification
+-   **`api_key: str`** (Required): Authentication key for the Guard management platform
+-   **`project_id: str | None`**: Unique project identifier for data segregation and multi-tenancy support
+
+#### Network Configuration
+-   **`endpoint: str`**: Management platform API endpoint (Default: `https://api.guard-core.com`)
+-   **`timeout: int`**: HTTP request timeout in seconds (Default: `30`)
+-   **`retry_attempts: int`**: Maximum retry attempts for failed requests (Default: `3`)
+-   **`backoff_factor: float`**: Exponential backoff multiplier for retry delays (Default: `1.0`)
+
+#### Data Management
+-   **`buffer_size: int`**: Maximum events in memory buffer before automatic flush (Default: `100`)
+-   **`flush_interval: int`**: Automatic buffer flush interval in seconds (Default: `30`)
+-   **`max_payload_size: int`**: Maximum payload size in bytes before truncation (Default: `1024`)
+
+#### Feature Control
+-   **`enable_metrics: bool`**: Enable performance metrics collection (Default: `True`)
+-   **`enable_events: bool`**: Enable security event collection (Default: `True`)
+
+#### Security & Privacy
+-   **`sensitive_headers: list[str]`**: HTTP headers to redact from collected data (Default: `["authorization", "cookie", "x-api-key"]`)
+
+---
+
+Migration from `fastapi-guard-agent`
+------------------------------------
+
+No code changes required. The import path was always `guard_agent`:
+
+```python
+# This worked before and still works:
+from guard_agent import GuardAgentHandler, AgentConfig
+```
+
+To switch your install command:
+
+```bash
+# Old (still works via shim)
+pip install fastapi-guard-agent
+
+# New (preferred)
+pip install guard-agent
+```
+
+The legacy `fastapi-guard-agent` name is maintained as a meta-package pointing to `guard-agent>=2.0.0,<3.0.0`, so pinned environments keep resolving correctly.
+
+---
+
+Contributing
+------------
+
+Contributions are welcome! Please open an issue or submit a pull request on GitHub.
+
+---
+
+License
+-------
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+---
+
+Author
+------
+
+Renzo Franceschini - [rennf93@users.noreply.github.com](mailto:rennf93@users.noreply.github.com)
+
+---
+
+Acknowledgements
+----------------
+
+- [FastAPI](https://fastapi.tiangolo.com/)
+- [Flask](https://flask.palletsprojects.com/)
+- [Django](https://www.djangoproject.com/)
+- [Tornado](https://www.tornadoweb.org/)
+- [Redis](https://redis.io/)
+- [httpx](https://www.python-httpx.org/)
+- [Pydantic](https://pydantic-docs.helpmanual.io/)