shieldcortex 0.2.0__tar.gz → 0.5.0__tar.gz

{shieldcortex-0.2.0 → shieldcortex-0.5.0}/.github/workflows/test.yml

@@ -18,7 +18,7 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies
-        run: pip install -e ".[dev]"
+        run: pip install -e ".[dev,langchain]"
       - name: Lint
         run: ruff check src/
       - name: Type check

shieldcortex-0.5.0/CHANGELOG.md

@@ -0,0 +1,159 @@
+# Changelog
+
+## [Unreleased]
+
+## 0.5.0 — 2026-10-17
+
+Minor release: opt-in fail-closed and QUARANTINE blocking for the LangChain
+handlers, structured tool outputs scanned, and path parameters URL-encoded.
+0.4.0 was never tagged or published, so this is the first published release
+after 0.3.0 and also carries every 0.4.0 change listed below.
+
+Defaults are unchanged for API errors and QUARANTINE: a `ShieldCortexError`
+from a scan is still logged and skipped, and QUARANTINE still does not act,
+unless you opt in with the new options below.
+
+### Added
+
+- LangChain handlers: `fail_closed` (default `False`). With
+  `raise_on_block=True`, a `ShieldCortexError` from a scan (401, 429, 5xx,
+  timeout, and every other API error) raises `ContentBlockedError` with
+  `result=None` and the original error as `__cause__`, so the run stops
+  (except for sync-only tools under `ainvoke` with the async handler; see
+  Known limitation). `fail_closed=True` without `raise_on_block=True` raises `ValueError` at
+  construction.
+- `ContentBlockedError.result` is now typed `ScanResult | None`. It is only
+  `None` with `fail_closed=True`, so default-option callers never see `None`
+  at runtime, but type checkers will ask them to narrow before reading
+  `error.result.firewall`:
+  `if error.result is not None: print(error.result.firewall.reason)`.
+- LangChain handlers: `block_on_quarantine` (default `False`). When `True`,
+  a QUARANTINE verdict is treated exactly like BLOCK.
+
+### Fixed
+
+- LangChain `on_tool_end` now scans structured tool outputs (ToolMessage
+  content, content blocks, dicts) instead of skipping them. Non-string
+  outputs are reduced to text (`.content` string, joined text parts of a
+  content-block list, or JSON with a `str()` fallback); non-text blocks in a
+  content list are dropped, not JSON-encoded; `None` and outputs
+  that reduce to empty text are not scanned. String outputs are scanned as
+  before.
+- Path parameters (ids, device UUIDs, export manifest ids) are now
+  percent-encoded as a single URL segment, so `/`, `?`, `#`, `%`, spaces and
+  non-ASCII characters can no longer change the route. Empty, `.` and `..`
+  values raise `ValueError` before any request is sent.
+
+### Known limitation
+
+- LangChain answers a bare (non-chat) LLM call that is fully served from its
+  LLM cache without firing `on_llm_start` or `on_llm_end`, so neither the
+  prompt nor the cached output is scanned and no block can stop that call.
+  The 0.4.0 bare-LLM prompt scanning applies only to calls that reach the
+  model. Set `cache=False` on LLMs whose calls must be scanned (the default,
+  `cache=None`, uses any cache set with `set_llm_cache`), or scan outside the
+  model call. Chat models fire their start callback before the cache lookup,
+  so cached chat calls still have their input scanned. Regression tests pin
+  this behaviour.
+- With the async handler, a sync-only tool (no coroutine) called through
+  `ainvoke` runs in a worker thread where LangChain logs and swallows every
+  exception the handler raises. Neither BLOCK verdicts nor `fail_closed`
+  scan-error raises stop that tool: it runs and `ainvoke` returns its output.
+  Give the tool an async implementation, or pass the sync handler (with a
+  sync client) for those calls; its exceptions propagate on that route.
+
+## 0.4.0 — 2026-10-16
+
+Minor release: the LangChain integration now stops the run on BLOCK, scans
+bare LLM and chat prompts, and adds two public names
+(`ShieldCortexSyncCallbackHandler`, `ContentBlockedError`). No breaking changes.
+
+### Fixed
+
+- LangChain async blocks now propagate when `raise_on_block=True`.
+- Bare LLM and chat model inputs are scanned by their start callbacks.
+  Chat message text covers string content, string blocks, and dict blocks
+  whose `text` is a string and whose `type` is `"text"` or absent. Empty
+  prompts and empty chat text are skipped; chain and tool scans are unchanged.
+
+### Added
+
+- `ShieldCortexSyncCallbackHandler` for synchronous LangChain calls and
+  `ContentBlockedError` for catching blocked content with its scan result.
+- Ship a PEP 561 `py.typed` marker so type checkers treat the installed
+  package as typed (the `Typing :: Typed` classifier was already declared).
+
+### Documentation
+
+- LangChain: output is scanned when the model finishes, so with `stream` /
+  `astream` a BLOCK on output stops the run only after the chunks were
+  delivered. Only `ShieldCortexError` from the scan call is logged and
+  skipped; other exceptions (for example connection errors) stop the run
+  when `raise_on_block=True`.
+- README: describe `ShieldCortexMemoryGuard` as a framework-agnostic
+  pre-write guard (it does not import or hook into CrewAI; the `[crewai]`
+  extra only installs CrewAI itself).
+- README: document the sync client's context manager
+  (`with ShieldCortex(...) as client:`) and `client.close()`.
+
+## 0.3.0 — 2026-08-15
+
+- Version-only release, coordinated with core v4.52.0. No API changes:
+  only the package version (`pyproject.toml`, `_version.py`) changed
+  from 0.2.0.
+
+## 0.2.0 — 2026-08-11
+
+SDK lockstep release: the Python SDK now covers the full customer surface
+documented in the SDK lockstep contract, in lockstep with the TypeScript SDK.
+
+### Added
+
+- **Verification** — `submit_verification()`, `list_verifications()`,
+  `get_verification()`, `get_verification_stats()`, `delete_verification()`
+- **Skills** — `ingest_skill_scans()`, `list_skill_scans()`
+- **Threats** — `report_threat()` (OpenClaw realtime compat shim)
+- **Incidents** — `replay_incidents()`
+- **Recall** — `explain_recall()`
+- **Sync** — `get_sync_health()`, `push_memories()`, `list_synced_memories()`,
+  `push_memory_graph()`. Note: `list_synced_memories()` omits the
+  `include_deleted` param unless truthy — the server Boolean-coerces any
+  present value (even `"false"`) as enabling it. Every other boolean query
+  param was audited for the same coercion trap; none affected.
+- **Licence** — `get_license()`, `regenerate_license()`
+- **Audit** — `ingest_audit_events()`, `get_iron_dome_stats()`,
+  `get_iron_dome_events()`, and the export-manifest surface
+  (`list_audit_exports()`, `get_audit_export_manifest()`,
+  `verify_audit_export()`, `list_audit_export_verifications()`)
+- Cross-SDK endpoint parity manifest and drift guard
+  (`tests/endpoint_manifest.py`, kept in lockstep with the TS SDK's
+  `tests/endpoint-manifest.ts`), including a sync/async surface parity test
+- Shared request builders (`_payloads.py`) so the sync and async clients
+  construct identical wire payloads and cannot drift
+
+### Changed
+
+- **BREAKING:** `export_audit_logs()` (both clients) now returns
+  `AuditExportResult` — the raw file body in `.content` plus the parsed
+  `X-ShieldCortex-Export-*` integrity headers in `.headers` — instead of a
+  bare `str`. Previously the integrity headers were discarded, so exports
+  structurally could not be verified. An absent `sha256`/`signature` header
+  is `None` (never `""`): the export is unverifiable. Migration:
+  `client.export_audit_logs(...)` → `client.export_audit_logs(...).content`.
+
+### Deprecated
+
+- `create_checkout_session()` / `create_portal_session()` now emit
+  `DeprecationWarning`: self-serve plans were retired 2026-07 (Free +
+  Enterprise model); the endpoints remain for grandfathered licence holders.
+
+## 0.1.1 — 2026-03-12
+
+- Added Iron Dome patterns/policies client support; fixed the default-policy
+  verb (PUT).
+
+## 0.1.0 — 2026-02-15
+
+- Initial release: scanning, audit, quarantine, keys, teams, invites,
+  billing, devices, alerts, webhooks, firewall rules; sync + async clients;
+  CrewAI and LangChain integrations; Python 3.9+ compatibility fixes.

{shieldcortex-0.2.0 → shieldcortex-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: shieldcortex
-Version: 0.2.0
+Version: 0.5.0
 Summary: Official Python SDK for the ShieldCortex API — AI memory security scanning
 Project-URL: Homepage, https://shieldcortex.ai
 Project-URL: Documentation, https://shieldcortex.ai/docs
@@ -74,7 +74,7 @@ pip install shieldcortex
 With framework integrations:
 
 ```bash
-pip install shieldcortex[crewai]     # CrewAI memory guard
+pip install shieldcortex[crewai]     # also installs CrewAI (the memory guard itself does not need it)
 pip install shieldcortex[langchain]  # LangChain callback handler
 ```
 
@@ -96,6 +96,19 @@ else:
     # don't store — content failed security checks
 ```
 
+The sync client holds an `httpx` connection pool. Use it as a context manager
+so the pool is closed when you are done:
+
+```python
+from shieldcortex import ShieldCortex
+
+with ShieldCortex(api_key="sc_live_...") as client:
+    result = client.scan("user input to remember")
+```
+
+In long-lived processes that keep a client around instead, call
+`client.close()` when you are finished with it.
+
 ## Async Support
 
 ```python
@@ -119,9 +132,9 @@ result = client.scan_batch([
 print(f"Scanned: {result.total_scanned}, Threats: {result.threats}")
 ```
 
-## CrewAI Integration
+## Memory Guard (CrewAI and others)
 
-Add a security gate between your CrewAI agent and its memory store. The guard scans all content before it's saved — blocking prompt injection and credential leaks:
+`ShieldCortexMemoryGuard` is a framework-agnostic pre-write check: call `guard.check()` before writing content to any memory store — from a CrewAI agent, another framework, or your own code. It scans the content and raises `MemoryBlockedError` if it is blocked (or, by default, quarantined). It does not hook into CrewAI automatically and does not import CrewAI; the `[crewai]` extra only installs CrewAI itself.
 
 ```python
 from shieldcortex import ShieldCortex
@@ -139,17 +152,101 @@ except MemoryBlockedError as e:
 
 ## LangChain Integration
 
-Automatically scan all LLM inputs and outputs as they flow through your chain — no changes to your existing code:
+The callbacks scan chain inputs, LLM prompts, text in chat messages, tool inputs,
+LLM outputs, and tool outputs, whenever LangChain fires the matching callback
+(see **LLM cache** below for a case where it does not). Use the async handler
+for `ainvoke` and `astream`, or the sync handler for `invoke`:
 
 ```python
-from shieldcortex import AsyncShieldCortex
-from shieldcortex.integrations.langchain import ShieldCortexCallbackHandler
+from langchain_openai import ChatOpenAI  # or any LangChain chat model / LLM
+from shieldcortex import AsyncShieldCortex, ShieldCortex
+from shieldcortex.integrations.langchain import (
+    ContentBlockedError,
+    ShieldCortexCallbackHandler,
+    ShieldCortexSyncCallbackHandler,
+)
 
-client = AsyncShieldCortex(api_key="sc_live_...")
-handler = ShieldCortexCallbackHandler(client, raise_on_block=True)
+model = ChatOpenAI()
 
-# Scans inputs on chain start, outputs on LLM end, and tool I/O
-llm = ChatOpenAI(callbacks=[handler])
+async with AsyncShieldCortex(api_key="sc_live_...") as client:
+    handler = ShieldCortexCallbackHandler(client, raise_on_block=True)
+    try:
+        reply = await model.ainvoke("Hello", config={"callbacks": [handler]})
+    except ContentBlockedError as error:  # also a ValueError
+        print(error.result.firewall.reason, error.source_identifier)
+
+with ShieldCortex(api_key="sc_live_...") as client:
+    handler = ShieldCortexSyncCallbackHandler(client, raise_on_block=True)
+    reply = model.invoke("Hello", config={"callbacks": [handler]})
+```
+
+By default only `BLOCK` verdicts act. With `raise_on_block=True`, a block stops
+the run with `ContentBlockedError`; otherwise it logs a warning. Use the matching
+handler for the call mode: LangChain cannot propagate an async handler's block
+from `invoke`.
+
+- **Chat message text** means string content, string blocks, and dict blocks
+  whose `text` is a string and whose `type` is `"text"` or absent. Images and
+  other block types are not scanned. Empty prompts are skipped.
+- **Streaming:** LLM output is scanned when the model finishes. With `stream`
+  or `astream`, every chunk has already reached your code by then, so an
+  output block stops the run after delivery and cannot prevent exposure.
+  Buffer the stream yourself if blocked output must never be shown. Input
+  scans still run before the model starts.
+- **Tool outputs** are reduced to text before scanning: strings as is; objects
+  with string `.content` (such as `ToolMessage`) by that content; a list
+  `.content` by its string items and the string `text` of its dict items,
+  joined by newlines; anything else as JSON (`default=str`), falling back to
+  `str()`. Other blocks in a list `.content`, such as images or dicts without
+  a string `text` (for example `{"payload": "..."}`), are dropped rather than
+  JSON-encoded, so their contents are not scanned. `None` and non-string outputs that reduce
+  to empty text are not scanned.
+- **LLM cache:** a bare (non-chat) LLM call answered entirely from a
+  LangChain LLM cache fires no callbacks: LangChain checks the cache before
+  `on_llm_start` and returns the cached text without `on_llm_end`. Neither
+  the prompt nor the cached output is scanned, and no block or `fail_closed`
+  error can stop that call. Set `cache=False` on LLMs whose calls must be
+  scanned (the default, `cache=None`, uses any cache set with
+  `set_llm_cache`), or scan outside the model call. Chat models fire
+  `on_chat_model_start` before their cache lookup, so a cached chat call
+  still has its input scanned.
+- **Sync-only tools under `ainvoke`:** LangChain runs a tool that has no
+  coroutine in a worker thread and logs and swallows every exception the
+  async handler raises there. Neither a `BLOCK` verdict nor a `fail_closed`
+  scan error stops that tool: it runs and `ainvoke` returns its output. Give
+  the tool an async implementation (`coroutine=` on `StructuredTool`, or
+  `_arun`), or pass the sync handler with a sync client for those calls,
+  e.g. `await tool.ainvoke(args, config={"callbacks": [sync_handler]})`; its
+  exceptions do propagate on that route.
+- **Scan errors:** by default a `ShieldCortexError` from the scan call (any
+  HTTP error such as 401, 429 or 5xx, or a timeout) is logged and that scan is
+  skipped, so the content passes. Other exceptions, such as connection errors,
+  are not caught: with `raise_on_block=True` they stop the run, otherwise
+  LangChain logs them.
+
+Two opt-in options, available on both handlers:
+
+| Option | Default | Effect |
+|---|---|---|
+| `fail_closed` | `False` | With `raise_on_block=True`, a `ShieldCortexError` from a scan raises `ContentBlockedError` instead of being logged and skipped (except for sync-only tools under `ainvoke` with the async handler, see above). `error.result` is `None` and `error.__cause__` is the original error. Requires `raise_on_block=True`; otherwise the constructor raises `ValueError`. |
+| `block_on_quarantine` | `False` | Treat `QUARANTINE` verdicts exactly like `BLOCK` (warn, or raise with `raise_on_block=True`). |
+
+```python
+handler = ShieldCortexSyncCallbackHandler(
+    client, raise_on_block=True, fail_closed=True, block_on_quarantine=True
+)
+```
+
+`ContentBlockedError.result` is typed `ScanResult | None`. Without
+`fail_closed` it is never `None` at runtime, but type checkers will still ask
+you to narrow it before reading `error.result.firewall`:
+
+```python
+except ContentBlockedError as error:
+    if error.result is None:  # fail_closed: the scan itself failed
+        print("scan failed:", error.__cause__)
+    else:
+        print(error.result.firewall.reason)
 ```
 
 ## Audit Logs

{shieldcortex-0.2.0 → shieldcortex-0.5.0}/README.md

@@ -35,7 +35,7 @@ pip install shieldcortex
 With framework integrations:
 
 ```bash
-pip install shieldcortex[crewai]     # CrewAI memory guard
+pip install shieldcortex[crewai]     # also installs CrewAI (the memory guard itself does not need it)
 pip install shieldcortex[langchain]  # LangChain callback handler
 ```
 
@@ -57,6 +57,19 @@ else:
     # don't store — content failed security checks
 ```
 
+The sync client holds an `httpx` connection pool. Use it as a context manager
+so the pool is closed when you are done:
+
+```python
+from shieldcortex import ShieldCortex
+
+with ShieldCortex(api_key="sc_live_...") as client:
+    result = client.scan("user input to remember")
+```
+
+In long-lived processes that keep a client around instead, call
+`client.close()` when you are finished with it.
+
 ## Async Support
 
 ```python
@@ -80,9 +93,9 @@ result = client.scan_batch([
 print(f"Scanned: {result.total_scanned}, Threats: {result.threats}")
 ```
 
-## CrewAI Integration
+## Memory Guard (CrewAI and others)
 
-Add a security gate between your CrewAI agent and its memory store. The guard scans all content before it's saved — blocking prompt injection and credential leaks:
+`ShieldCortexMemoryGuard` is a framework-agnostic pre-write check: call `guard.check()` before writing content to any memory store — from a CrewAI agent, another framework, or your own code. It scans the content and raises `MemoryBlockedError` if it is blocked (or, by default, quarantined). It does not hook into CrewAI automatically and does not import CrewAI; the `[crewai]` extra only installs CrewAI itself.
 
 ```python
 from shieldcortex import ShieldCortex
@@ -100,17 +113,101 @@ except MemoryBlockedError as e:
 
 ## LangChain Integration
 
-Automatically scan all LLM inputs and outputs as they flow through your chain — no changes to your existing code:
+The callbacks scan chain inputs, LLM prompts, text in chat messages, tool inputs,
+LLM outputs, and tool outputs, whenever LangChain fires the matching callback
+(see **LLM cache** below for a case where it does not). Use the async handler
+for `ainvoke` and `astream`, or the sync handler for `invoke`:
 
 ```python
-from shieldcortex import AsyncShieldCortex
-from shieldcortex.integrations.langchain import ShieldCortexCallbackHandler
+from langchain_openai import ChatOpenAI  # or any LangChain chat model / LLM
+from shieldcortex import AsyncShieldCortex, ShieldCortex
+from shieldcortex.integrations.langchain import (
+    ContentBlockedError,
+    ShieldCortexCallbackHandler,
+    ShieldCortexSyncCallbackHandler,
+)
 
-client = AsyncShieldCortex(api_key="sc_live_...")
-handler = ShieldCortexCallbackHandler(client, raise_on_block=True)
+model = ChatOpenAI()
 
-# Scans inputs on chain start, outputs on LLM end, and tool I/O
-llm = ChatOpenAI(callbacks=[handler])
+async with AsyncShieldCortex(api_key="sc_live_...") as client:
+    handler = ShieldCortexCallbackHandler(client, raise_on_block=True)
+    try:
+        reply = await model.ainvoke("Hello", config={"callbacks": [handler]})
+    except ContentBlockedError as error:  # also a ValueError
+        print(error.result.firewall.reason, error.source_identifier)
+
+with ShieldCortex(api_key="sc_live_...") as client:
+    handler = ShieldCortexSyncCallbackHandler(client, raise_on_block=True)
+    reply = model.invoke("Hello", config={"callbacks": [handler]})
+```
+
+By default only `BLOCK` verdicts act. With `raise_on_block=True`, a block stops
+the run with `ContentBlockedError`; otherwise it logs a warning. Use the matching
+handler for the call mode: LangChain cannot propagate an async handler's block
+from `invoke`.
+
+- **Chat message text** means string content, string blocks, and dict blocks
+  whose `text` is a string and whose `type` is `"text"` or absent. Images and
+  other block types are not scanned. Empty prompts are skipped.
+- **Streaming:** LLM output is scanned when the model finishes. With `stream`
+  or `astream`, every chunk has already reached your code by then, so an
+  output block stops the run after delivery and cannot prevent exposure.
+  Buffer the stream yourself if blocked output must never be shown. Input
+  scans still run before the model starts.
+- **Tool outputs** are reduced to text before scanning: strings as is; objects
+  with string `.content` (such as `ToolMessage`) by that content; a list
+  `.content` by its string items and the string `text` of its dict items,
+  joined by newlines; anything else as JSON (`default=str`), falling back to
+  `str()`. Other blocks in a list `.content`, such as images or dicts without
+  a string `text` (for example `{"payload": "..."}`), are dropped rather than
+  JSON-encoded, so their contents are not scanned. `None` and non-string outputs that reduce
+  to empty text are not scanned.
+- **LLM cache:** a bare (non-chat) LLM call answered entirely from a
+  LangChain LLM cache fires no callbacks: LangChain checks the cache before
+  `on_llm_start` and returns the cached text without `on_llm_end`. Neither
+  the prompt nor the cached output is scanned, and no block or `fail_closed`
+  error can stop that call. Set `cache=False` on LLMs whose calls must be
+  scanned (the default, `cache=None`, uses any cache set with
+  `set_llm_cache`), or scan outside the model call. Chat models fire
+  `on_chat_model_start` before their cache lookup, so a cached chat call
+  still has its input scanned.
+- **Sync-only tools under `ainvoke`:** LangChain runs a tool that has no
+  coroutine in a worker thread and logs and swallows every exception the
+  async handler raises there. Neither a `BLOCK` verdict nor a `fail_closed`
+  scan error stops that tool: it runs and `ainvoke` returns its output. Give
+  the tool an async implementation (`coroutine=` on `StructuredTool`, or
+  `_arun`), or pass the sync handler with a sync client for those calls,
+  e.g. `await tool.ainvoke(args, config={"callbacks": [sync_handler]})`; its
+  exceptions do propagate on that route.
+- **Scan errors:** by default a `ShieldCortexError` from the scan call (any
+  HTTP error such as 401, 429 or 5xx, or a timeout) is logged and that scan is
+  skipped, so the content passes. Other exceptions, such as connection errors,
+  are not caught: with `raise_on_block=True` they stop the run, otherwise
+  LangChain logs them.
+
+Two opt-in options, available on both handlers:
+
+| Option | Default | Effect |
+|---|---|---|
+| `fail_closed` | `False` | With `raise_on_block=True`, a `ShieldCortexError` from a scan raises `ContentBlockedError` instead of being logged and skipped (except for sync-only tools under `ainvoke` with the async handler, see above). `error.result` is `None` and `error.__cause__` is the original error. Requires `raise_on_block=True`; otherwise the constructor raises `ValueError`. |
+| `block_on_quarantine` | `False` | Treat `QUARANTINE` verdicts exactly like `BLOCK` (warn, or raise with `raise_on_block=True`). |
+
+```python
+handler = ShieldCortexSyncCallbackHandler(
+    client, raise_on_block=True, fail_closed=True, block_on_quarantine=True
+)
+```
+
+`ContentBlockedError.result` is typed `ScanResult | None`. Without
+`fail_closed` it is never `None` at runtime, but type checkers will still ask
+you to narrow it before reading `error.result.firewall`:
+
+```python
+except ContentBlockedError as error:
+    if error.result is None:  # fail_closed: the scan itself failed
+        print("scan failed:", error.__cause__)
+    else:
+        print(error.result.firewall.reason)
 ```
 
 ## Audit Logs

shieldcortex-0.5.0/examples/langchain_callback.py

@@ -0,0 +1,42 @@
+"""Scan LangChain inputs and outputs with the matching callback handler.
+
+Install with ``pip install shieldcortex[langchain]``. The handlers scan chain
+inputs, LLM prompts, text in chat messages, tool inputs, LLM outputs, and
+string tool outputs. Only BLOCK verdicts act. Streamed output is scanned
+after the chunks are delivered, so an output block cannot hide them.
+"""
+
+import asyncio
+
+from langchain_core.language_models.fake_chat_models import FakeListChatModel
+
+from shieldcortex import AsyncShieldCortex, ShieldCortex
+from shieldcortex.integrations.langchain import (
+    ContentBlockedError,
+    ShieldCortexCallbackHandler,
+    ShieldCortexSyncCallbackHandler,
+)
+
+
+async def main() -> None:
+    model = FakeListChatModel(responses=["Hello!"])
+
+    async with AsyncShieldCortex(api_key="sc_live_YOUR_KEY_HERE") as client:
+        handler = ShieldCortexCallbackHandler(client, raise_on_block=True)
+        try:
+            print(await model.ainvoke("Hello", config={"callbacks": [handler]}))
+        except ContentBlockedError as error:  # also a ValueError
+            print(f"Blocked {error.source_identifier}: {error.result.firewall.reason}")
+
+    # For invoke(), use the sync client and handler. The async handler's block
+    # cannot propagate from a sync call.
+    with ShieldCortex(api_key="sc_live_YOUR_KEY_HERE") as client:
+        handler = ShieldCortexSyncCallbackHandler(client, raise_on_block=True)
+        try:
+            print(model.invoke("Hello", config={"callbacks": [handler]}))
+        except ContentBlockedError as error:
+            print(f"Blocked {error.source_identifier}: {error.result.firewall.reason}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

{shieldcortex-0.2.0 → shieldcortex-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "shieldcortex"
-version = "0.2.0"
+version = "0.5.0"
 description = "Official Python SDK for the ShieldCortex API — AI memory security scanning"
 readme = "README.md"
 license = { text = "MIT" }

{shieldcortex-0.2.0 → shieldcortex-0.5.0}/src/shieldcortex/_http.py

@@ -10,6 +10,7 @@ import dataclasses
 import re
 from collections.abc import Callable
 from typing import Any, TypeVar, get_type_hints
+from urllib.parse import quote
 
 import httpx
 
@@ -121,6 +122,24 @@ def serialize_query(obj: Any) -> dict[str, str]:
     return params
 
 
+# ── Path parameters ───────────────────────────────────────────────────────────
+
+
+def _seg(value: object) -> str:
+    """Encode a caller-supplied value as exactly one URL path segment.
+
+    Reserved characters (``/``, ``?``, ``#``, ``%``, space, non-ASCII) are
+    percent-encoded. Empty, ``.`` and ``..`` are rejected before any request
+    is sent: URL parsing would otherwise collapse or climb the route.
+    """
+    segment = str(value)
+    if segment == "":
+        raise ValueError("path parameter must not be empty")
+    if segment in (".", ".."):
+        raise ValueError("path parameter must not be '.' or '..'")
+    return quote(segment, safe="")
+
+
 # ── Deserialisation ───────────────────────────────────────────────────────────
 
 # Cache for resolved type hints per class

shieldcortex-0.5.0/src/shieldcortex/_version.py

@@ -0,0 +1 @@
+__version__ = "0.5.0"