dapplepot-sdk 0.1.0__tar.gz

dapplepot_sdk-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may accept and charge a
+      fee for acceptance of support, warranty, indemnity, or other liability
+      obligations and/or rights consistent with this License. However, in
+      accepting such obligations, You may act only on Your own behalf and on
+      Your sole responsibility, not on behalf of any other Contributor, and
+      only if You agree to indemnify, defend, and hold each Contributor
+      harmless for any liability incurred by, or claims asserted against,
+      such Contributor by reason of your accepting any such warranty or
+      additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2024 DapplePot
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied. See the License for the specific language governing permissions and
+   limitations under the License.

dapplepot_sdk-0.1.0/NOTICE

@@ -0,0 +1,4 @@
+dapplepot-sdk
+Copyright 2024 DapplePot
+
+This product includes software developed by DapplePot.

dapplepot_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,308 @@
+Metadata-Version: 2.4
+Name: dapplepot-sdk
+Version: 0.1.0
+Summary: DapplePot Python SDK for AI agent security observability — instruments LangChain/LangGraph, OpenAI, and Anthropic
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://dapplepot.com
+Keywords: llm,security,observability,ai-agents,langchain,openai,anthropic,langgraph
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Security
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: requests>=2.31.0
+Provides-Extra: langchain
+Requires-Dist: langchain>=0.2.0; extra == "langchain"
+Requires-Dist: langchain-core>=0.2.0; extra == "langchain"
+Requires-Dist: langchain-openai>=0.1.0; extra == "langchain"
+Requires-Dist: langgraph>=0.1.0; extra == "langchain"
+Provides-Extra: openai
+Requires-Dist: openai>=1.30.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.28.0; extra == "anthropic"
+Provides-Extra: all
+Requires-Dist: langchain>=0.2.0; extra == "all"
+Requires-Dist: langchain-core>=0.2.0; extra == "all"
+Requires-Dist: langchain-openai>=0.1.0; extra == "all"
+Requires-Dist: langgraph>=0.1.0; extra == "all"
+Requires-Dist: openai>=1.30.0; extra == "all"
+Requires-Dist: anthropic>=0.28.0; extra == "all"
+Dynamic: license-file
+
+# DapplePot Python SDK
+
+Python SDK for instrumenting LLM agents with DapplePot security observability. Drop-in integrations for **LangChain/LangGraph**, **OpenAI**, and **Anthropic** — sends structured events to the DapplePot ingest API and runs real-time threat detection in the hot path.
+
+## Installation
+Ensure you have Python 3.10+ installed, then:
+```bash
+pip install dapplepot-sdk
+
+# Framework-specific extras:
+pip install "dapplepot-sdk[langchain]"    # LangChain / LangGraph
+pip install "dapplepot-sdk[openai]"       # OpenAI
+pip install "dapplepot-sdk[anthropic]"    # Anthropic
+pip install "dapplepot-sdk[all]"          # Everything
+```
+
+## Quick Start
+
+Get your `sdk_key`, `tenant_id`, `agent_id`, and `ingest_url` from the DapplePot dashboard.
+
+### Anthropic
+
+The standard `anthropic` package is patched in-place — upgrade it freely without coordinating with DapplePot releases.
+
+```python
+import anthropic
+from dapplepot_sdk import DapplePot
+
+dp = DapplePot(
+    sdk_key    = "dp_sk_...",
+    tenant_id  = "your-tenant-id",
+    agent_id   = "your-agent-id",
+    ingest_url = "https://ingest.dapplepot.com",
+)
+dp.instrument_anthropic()
+
+client = anthropic.Anthropic(api_key="...")
+
+with dp.session(user_context_id="user_123", user_tenant_id="acme_corp"):
+    response = client.messages.create(
+        model="claude-opus-4-7",
+        max_tokens=1024,
+        messages=[{"role": "user", "content": "Hello!"}],
+    )
+```
+
+All LLM, tool, and session events are captured automatically. See [Tool Tracking](#tool-tracking) for how multi-turn tool-use loops are traced with zero extra code.
+
+### OpenAI
+
+```python
+import openai
+from dapplepot_sdk import DapplePot
+
+dp = DapplePot(
+    sdk_key    = "dp_sk_...",
+    tenant_id  = "...",
+    agent_id   = "...",
+    ingest_url = "https://ingest.dapplepot.com",
+)
+dp.instrument_openai()
+
+with dp.session(user_context_id="user_123"):
+    response = openai.chat.completions.create(
+        model="gpt-4o",
+        messages=[{"role": "user", "content": "Hello!"}],
+    )
+```
+
+### LangChain / LangGraph
+
+LangChain fires its own callbacks during chain or graph execution — pass `dp.callback_handler()` and DapplePot listens.
+
+```python
+from dapplepot_sdk import DapplePot
+
+dp = DapplePot(
+    sdk_key    = "dp_sk_...",
+    tenant_id  = "...",
+    agent_id   = "...",
+    ingest_url = "https://ingest.dapplepot.com",
+)
+
+handler = dp.callback_handler(
+    user_context_id="user_123",
+    user_tenant_id="acme_corp",
+)
+result = graph.invoke(
+    {"messages": [...]},
+    config={"callbacks": [handler]},
+)
+```
+
+For LangGraph: each named graph node automatically becomes a `node_start` / `node_end` event. Tool calls handled via `ToolNode` emit `tool_start` / `tool_end` automatically.
+
+## Core API
+
+### `dp.session(*, user_context_id=None, user_tenant_id=None)`
+
+Context manager that opens a DapplePot session for a multi-call conversation. The session ID is generated automatically.
+
+```python
+with dp.session(user_context_id="u_42", user_tenant_id="acme") as sess:
+    # All LLM calls inside this block belong to the same session
+    response = client.messages.create(...)
+```
+
+| Parameter | Description |
+|---|---|
+| `user_context_id` | Identifies the end-user within the session (optional) |
+| `user_tenant_id`  | For multi-tenant agents, identifies the customer tenant (optional) |
+
+Outside `dp.session()`, every patched LLM call becomes its own one-event session.
+
+### `dp.node(name, *, input=None)`
+
+Optional context manager that adds named structure to your agent code. Emits `node_start` on entry, `node_end` on success, or `node_error` if an exception escapes.
+
+```python
+with dp.session():
+    with dp.node("retrieve_context", input=query):
+        docs = vector_store.search(query)
+
+    with dp.node("generate_response"):
+        response = client.messages.create(...)
+```
+
+Use this when you want named steps in the trace UI — it is entirely optional. LangChain and LangGraph emit node events automatically from their own callbacks.
+
+### `dp.callback_handler(*, user_context_id=None, user_tenant_id=None)`
+
+Returns a fresh `DapplePotCallbackHandler` for one invocation of a LangChain chain or LangGraph run.
+
+## Tool Tracking
+
+For the Anthropic and OpenAI integrations, tool calls are detected automatically — no client-side instrumentation is required.
+
+**Anthropic**: when the model returns `tool_use` content blocks, `tool_start` is emitted. When the next `messages.create()` call carries matching `tool_result` blocks, `tool_end` is emitted with the real tool output and latency. Set `is_error=True` on the `tool_result` block to emit `tool_error` instead.
+
+**OpenAI**: when the model returns `tool_calls`, `tool_start` is emitted. When the next `chat.completions.create()` carries the corresponding `role="tool"` message, `tool_end` is emitted. Add `is_error=True` to the tool message to emit `tool_error` instead (a DapplePot convention — OpenAI ignores extra fields).
+
+**LangChain / LangGraph**: tool callbacks are wired automatically by the framework's own `BaseTool` and `ToolNode`.
+
+## Constructor
+
+```python
+DapplePot(
+    sdk_key,     # required — your SDK key from the DapplePot dashboard
+    tenant_id,   # required — your tenant ID
+    agent_id,    # required — the agent being instrumented
+    ingest_url,  # required — your DapplePot ingest endpoint
+    *,
+    sample_rate        = 1.0,   # 0.0–1.0; fraction of sessions traced
+    pii_scrubber       = None,  # custom scrubber object (must implement .scrub_value())
+    redact_keys        = None,  # list[str] of payload keys to replace with [REDACTED]
+    flush_interval_ms  = 500,   # background flush cadence
+    flush_batch_size   = 100,   # max events per flush batch
+)
+```
+
+All events are posted to `{ingest_url}/v1/ingest/events` with `Authorization: Bearer {sdk_key}`.
+
+Call `dp.shutdown()` on exit to flush buffered events.
+
+## Online Security Checks
+
+The SDK runs **12 sub-checks** synchronously on every event. When a check fires it emits a finding immediately (without waiting for session end). Which checks are active and what action they take is configured per-agent in the DapplePot dashboard and fetched automatically at SDK startup.
+
+| Sub-check | Category | Phase | Severity |
+|-----------|----------|-------|----------|
+| `PI-01a` | prompt_injection | input | high |
+| `PI-01b` | prompt_injection | input | critical |
+| `PI-01c` | prompt_injection | input | high |
+| `PI-02a` | prompt_injection | tool_end | high |
+| `PI-05a` | prompt_injection | input | high |
+| `PI-08a` | prompt_injection | llm_start | high |
+| `SID-01a` | data_disclosure | output | critical |
+| `SID-01c` | data_disclosure | output | critical |
+| `SID-02a` | data_disclosure | output | high |
+| `IOH-01a` | output_handling | output | critical |
+| `EA-01a` | excessive_agency | tool_start | high |
+| `EA-02b` | excessive_agency | tool_start | high |
+
+Check configuration and the tool manifest are fetched from the DapplePot API at startup. Update checks in the dashboard and restart your agent — no code changes needed.
+
+### Actions
+
+When a check fires, it takes one of four actions (configured per sub-check in the dashboard):
+
+| Action | Effect |
+|--------|--------|
+| `alert` | Logs a warning; execution continues |
+| `sanitize` | Redacts matched content from the event payload; execution continues |
+| `block_call` | Raises `DapplePotBlockedError` |
+| `terminate_session` | Raises `DapplePotSessionTerminatedError` |
+
+```python
+from dapplepot_sdk import DapplePot, DapplePotBlockedError, DapplePotSessionTerminatedError
+
+try:
+    result = graph.invoke(...)
+except DapplePotBlockedError as e:
+    print(e.signal, e.reason, e.session_id)
+except DapplePotSessionTerminatedError:
+    print("Session terminated by security policy")
+```
+
+## PII Scrubbing
+
+Use the built-in `RegexScrubber` or implement your own:
+
+```python
+from dapplepot_sdk import DapplePot
+from dapplepot_sdk.scrubbers import RegexScrubber
+
+scrubber = RegexScrubber(patterns=["email", "ssn", "aws_key", "jwt", "phone"])
+
+dp = DapplePot(
+    sdk_key      = "dp_sk_...",
+    tenant_id    = "...",
+    agent_id     = "...",
+    ingest_url   = "https://ingest.dapplepot.com",
+    pii_scrubber = scrubber,
+)
+```
+
+Built-in pattern names: `email`, `phone`, `ssn`, `credit_card`, `uk_nino`, `iban`, `ip_address`, `aws_key`, `jwt`.
+
+To implement a custom scrubber, subclass `BaseScrubber` and implement `scrub(text: str) -> str`:
+
+```python
+from dapplepot_sdk.scrubbers import BaseScrubber
+
+class MyScrubber(BaseScrubber):
+    def scrub(self, text: str) -> str:
+        return text.replace("sensitive", "[REDACTED]")
+```
+
+You can also redact known keys without touching values:
+
+```python
+dp = DapplePot(..., redact_keys=["api_key", "password", "ssn"])
+```
+
+**Impact on detection:** Scrubbing runs after real-time online checks, so live session checks marked for online detection (e.g. `SID-02a`) still operate on the original content and fire correctly. However, events stored for post-session analysis contain the scrubbed values — PII is replaced with tokens like `[EMAIL]` or `[SANITIZED]` before storage, so any offline detection pass on those events will find nothing to flag.
+
+## Event Reference
+
+All events flow through `POST {ingest_url}/v1/ingest/events`.
+
+| Event | When |
+|---|---|
+| `session_start` | `dp.session()` enter, or first patched call in standalone mode |
+| `session_end` | `dp.session()` exit (normal close), or last patched call in standalone mode |
+| `session_error` | Exception escapes `dp.session()` uncaught |
+| `node_start` | `dp.node()` enter, or LangGraph/LangChain child chain start |
+| `node_end` | `dp.node()` clean exit, or LangGraph/LangChain child chain end |
+| `node_error` | `dp.node()` raises, or LangGraph/LangChain child chain fails |
+| `llm_start` | Patched LLM call begins |
+| `llm_end` | Patched LLM call returns (tokens, latency, model, finish reason) |
+| `llm_error` | Patched LLM call raises |
+| `tool_start` | Tool invoked by the model (auto-detected from response) |
+| `tool_end` | Tool result fed back into the model (auto-detected from next call) |
+| `tool_error` | Tool result marked `is_error=True`, or framework tool callback fails |
+| `security_finding` | Online security check fired (out-of-band) |
+
+Errors propagate upward only as far as the exception actually travels. Catch an exception inside `dp.node()` and the session keeps going. Catch it inside `dp.session()` and you only see `node_error` and `llm_error`, never `session_error`.
+
+## License
+
+Licensed under the **Apache License, Version 2.0**. See [LICENSE](LICENSE) and [NOTICE](NOTICE) for details.