forma-sdk 1.1.0__py3-none-any.whl

forma_sdk-1.1.0.dist-info/METADATA

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: forma-sdk
+Version: 1.1.0
+Summary: FORMA — AI agent compliance SDK. Zero-config tracking, EU AI Act/DPDP/RBI compliance, cryptographic audit trails.
+Home-page: https://github.com/amit5115/forma-sdk
+Author: FORMA
+Author-email: sdk@forma.ai
+Keywords: ai agents compliance eu-ai-act rbi dpdp audit cryptography llm openai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+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 :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: cli
+Requires-Dist: click>=8.0; extra == "cli"
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.20; extra == "anthropic"
+Provides-Extra: litellm
+Requires-Dist: litellm>=1.0; extra == "litellm"
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1; extra == "langchain"
+Provides-Extra: all
+Requires-Dist: click>=8.0; extra == "all"
+Requires-Dist: openai>=1.0; extra == "all"
+Requires-Dist: anthropic>=0.20; extra == "all"
+Requires-Dist: litellm>=1.0; extra == "all"
+Requires-Dist: langchain-core>=0.1; extra == "all"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# FORMA SDK
+
+**Make non-compliance impossible — in one line of code.**
+
+FORMA doesn't just record what your AI did; it **blocks non-compliant decisions before they execute**. Add `enforce=[...]` and PII leaks, prompt injections, and policy violations are stopped at runtime — then every decision is cryptographically signed and mapped to RBI, DPDP, EU AI Act, and ISO 42001.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+
+---
+
+## Install
+
+```bash
+pip install forma-sdk
+```
+
+Import name is `trustlayer` (the legacy alias `provn` also works):
+
+```python
+import trustlayer as tl
+```
+
+## Quickstart — runtime enforcement
+
+```python
+import trustlayer as tl
+
+tl.init(api_key="tl_live_YOUR_KEY")   # from forma.2bd.net → Settings
+
+@tl.agent(
+    purpose="Loan application evaluation",
+    risk_level="HIGH",
+    enforce=["rbi_ml_risk", "dpdp"],   # ← blocks violations BEFORE they run
+)
+def approve_loan(application: dict) -> dict:
+    return run_underwriting_model(application)
+```
+
+Now, before any LLM or tool call executes:
+
+- An Aadhaar / PAN / card number in the prompt → **blocked** (DPDP)
+- "Ignore previous instructions…" / jailbreaks → **blocked**
+- "Auto-approve without review" → **blocked** (RBI human-review rule)
+
+A blocked action raises `ComplianceViolation`, and every decision (allow / warn / block) lands in your signed audit trail. The gate runs **locally in ~1 ms** — no network hop in your request path.
+
+```python
+from trustlayer import ComplianceViolation
+
+try:
+    result = approve_loan(application)
+except ComplianceViolation as e:
+    print(e.reason)   # "PII detected in LLM prompt: Aadhaar number. ..."
+```
+
+## Zero-config tracking (no enforcement)
+
+```python
+import trustlayer as tl
+tl.init(api_key="tl_live_YOUR_KEY")
+
+# Every OpenAI / Anthropic / LangChain / LiteLLM call is now auto-captured —
+# tokens, cost, latency, anomaly score — with no other code changes.
+```
+
+## Human approvals (EU AI Act Article 14 / RBI human review)
+
+```python
+@tl.track
+@tl.require_approval(
+    when=lambda result: result["amount"] > 1_000_000,   # only high-stakes
+    message="Loan above ₹10L requires human review.",
+)
+def approve_loan(application: dict) -> dict:
+    return run_underwriting_model(application)
+```
+
+The decision pauses in your FORMA Approvals inbox until a human approves or rejects. Fail-closed: a timeout or unreachable API is treated as a denial — a skipped review never silently passes.
+
+---
+
+## Policy packs
+
+| Pack | Region | Enforces |
+|------|--------|----------|
+| `dpdp` | India | Aadhaar / PAN / card / phone blocked from prompts & tool args; consent-bypass blocked |
+| `rbi_ml_risk` | India Banking | auto-approval-without-review blocked; fund-disbursal routed to approval |
+| `eu_ai_act` | EU | human-oversight bypass (Art. 14) & logging suppression (Art. 12) blocked; PII protection |
+| `iso42001` | Global | concealing AI involvement blocked |
+
+---
+
+## Manual step control
+
+```python
+import openai
+import trustlayer as tl
+
+tracker = tl.init(api_key="tl_live_YOUR_KEY", auto_capture=False)
+
+@tracker.track(name="my-agent")
+def my_agent(task: str) -> str:
+    with tracker.llm_call(label="generate", model="gpt-4o", prompt=task) as step:
+        resp = openai.chat.completions.create(
+            model="gpt-4o",
+            messages=[{"role": "user", "content": task}],
+        )
+        step.prompt_tokens     = resp.usage.prompt_tokens
+        step.completion_tokens = resp.usage.completion_tokens
+        return resp.choices[0].message.content
+
+# For tools:  with tracker.tool_call("send_email", {"to": addr}): ...
+```
+
+## Kill switch
+
+Pass `kill_switch=True` to `@tl.agent(...)` (or `tl.init(kill_switch=True)`). When you trigger a kill from the dashboard, the next LLM/tool call raises `KillSwitchTriggered` in under ~100 ms.
+
+## CI/CD compliance gate
+
+```bash
+# Blocks the deploy (exit 1) if any agent is below the threshold
+trustlayer gate --pre-deploy --fail-below 80
+```
+
+---
+
+## `tl.init()` parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `api_key` | `str` | Your FORMA API key (`tl_live_…` / `tl_test_…`) |
+| `enforce` | `list[str]` | Framework packs enforced on every call, e.g. `["dpdp"]` |
+| `human_sponsor` | `str` | Accountable human (EU AI Act Art. 14 / RBI) |
+| `auto_capture` | `bool` | Auto-patch OpenAI/Anthropic/LangChain/LiteLLM (default `True`) |
+| `kill_switch` | `bool` | Start the process-level kill watcher (default `False`) |
+| `compliance` | `list[str]` | Frameworks for scoring/reports |
+| `agent_name` | `str` | Display name for ambient auto-captured runs |
+
+---
+
+## Node.js / TypeScript
+
+```bash
+npm install forma-sdk
+```
+
+```ts
+import * as tl from "forma-sdk";
+
+tl.init({ apiKey: "tl_live_YOUR_KEY" });
+
+const myAgent = tl.track(
+  async (task: string) => { /* your code */ return "done"; },
+  { name: "my-agent" },
+);
+```
+
+> **Note:** runtime enforcement (`enforce`), `agent`, and approvals are **Python-only** today. The Node SDK currently provides auto-tracking (`init` + `track`); enforcement parity is on the roadmap.
+
+---
+
+## Dashboard & docs
+
+- Dashboard: **[forma.2bd.net](https://forma.2bd.net)**
+- Developer guide: [forma.2bd.net/developer-guide](https://forma.2bd.net/developer-guide)
+- Generate a tailored snippet: [forma.2bd.net/snippet-generator](https://forma.2bd.net/snippet-generator)
+
+## License
+
+MIT — see [LICENSE](LICENSE).

forma_sdk-1.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+forma_sdk-1.1.0.dist-info/licenses/LICENSE,sha256=XcrPEcYkGOsx3wUJ2ahxR4cwFgzWHEvwKG0UlPgZuDI,1062
+provn/__init__.py,sha256=J1PKcwde7xcE2eDoqBp7BHPLJKPfEu0oustmJoQFZrw,4155
+trustlayer/__init__.py,sha256=QUVWXPStW08x0vrnE1QO_drXGqnoct9Vfkj1lhzPyD8,5970
+trustlayer/approval.py,sha256=IPMh3FfhC_WGOUhszmVRC3s78LDD8b9jiBzk6WeSiUE,9298
+trustlayer/auto.py,sha256=AsfnVXHLRsETtFjCuZ0NVCo9_WshIN_lfAODInJJAPs,29909
+trustlayer/cli.py,sha256=GlbPOKtMiYJPd7MY0N1BN7H_xlHGNir2sBeML6-X2TE,22741
+trustlayer/client.py,sha256=tWO5XwvK_L0qt59C-VNh59hoT_koQNp6bCXzBIWOfE0,6376
+trustlayer/crypto.py,sha256=xYDCD17tnyZvhyBZLcEpypF-cBQBEqjf5crq3CfxRKw,6132
+trustlayer/gate_local.py,sha256=G0ByFTjMf7wWaob8iPjV8SgYQ6NkFEibeeB4H0jfur0,12750
+trustlayer/models.py,sha256=OUzN-whnqxa85PXwxa2i605P53AYq1xJZ85zKaKWft4,3094
+trustlayer/tracker.py,sha256=tUEFUeHkm0oaZ-ey2_IVNXtAWRW4fYQGToBGaSpUGVY,29514
+forma_sdk-1.1.0.dist-info/METADATA,sha256=eJpItuLaFcK8zY-hfMxDuGsw0FXlZxCwk8c2OVfIDxo,7475
+forma_sdk-1.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+forma_sdk-1.1.0.dist-info/entry_points.txt,sha256=kiyAd-hnyoaSUJVEe90v0IxyyHLYi894p-nSTApIHLE,74
+forma_sdk-1.1.0.dist-info/top_level.txt,sha256=tbicwtwQi-C0BQKBUrqS9PRB3HLwbISk3PW7uSmV2qQ,17
+forma_sdk-1.1.0.dist-info/RECORD,,

forma_sdk-1.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

forma_sdk-1.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+provn = provn.cli:main
+trustlayer = trustlayer.cli:main

forma_sdk-1.1.0.dist-info/licenses/LICENSE

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

forma_sdk-1.1.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+provn
+trustlayer

provn/__init__.py

@@ -0,0 +1,132 @@
+"""
+provn — zero-config AI agent observability and control.
+
+Usage::
+
+    import provn
+    provn.init(api_key="tl_live_xxx")
+
+    # That's it. Every LLM call (OpenAI, Anthropic, LiteLLM, LangChain) is now:
+    #   - captured as a real AgentRun (not just shadow events)
+    #   - gate-checked before execution (compliance firewall)
+    #   - kill-switch aware (global process-level kill watch)
+    #   - cost + token tracked
+    #   - drift detected server-side
+    #   - compliance evaluated
+
+Decorators still work identically and take precedence over ambient runs::
+
+    @provn.agent(
+        purpose="Customer support",
+        risk_level="HIGH",
+        kill_switch=True,
+        compliance=["EU_AI_ACT"],
+    )
+    def support_agent(ticket: str) -> dict: ...
+"""
+from __future__ import annotations
+
+import trustlayer as _tl
+from trustlayer import (
+    AgentRun,
+    ApprovalRejectedError,
+    ApprovalTimeoutError,
+    ComplianceViolation,
+    KillSwitchTriggered,
+    PROVNClient,
+    PROVNTracker,
+    StepType,
+    TraceStep,
+    agent,
+    generate_keypair,
+    get_passport_header,
+    get_public_key_pem,
+    sign_run,
+    track,
+    verify_run,
+)
+
+__version__ = _tl.__version__
+
+
+def init(
+    api_key: "str | None" = None,
+    api_url: "str | None" = None,
+    agent_name: "str | None" = None,
+    human_sponsor: "str | None" = None,
+    kill_switch: bool = False,
+    gate: bool = True,
+    compliance: "list[str] | None" = None,
+    auto_capture: bool = True,
+    ambient_runs: bool = True,
+) -> PROVNTracker:
+    """
+    Initialize PROVN with zero-config defaults.
+
+    One call gives you full AI agent observability and governance::
+
+        import provn
+        provn.init(api_key="tl_live_xxx")
+
+    After this, all LLM calls across OpenAI, Anthropic, LiteLLM, and LangChain
+    are automatically captured, gate-checked, kill-switch aware, cost-tracked,
+    and fed into drift detection and compliance evaluation — no decorators needed.
+
+    Args:
+        api_key:       Your PROVN API key (or set TRUSTLAYER_API_KEY env var).
+        api_url:       PROVN backend URL (default: http://localhost:8001).
+        agent_name:    Display name for auto-captured ambient runs. Defaults to
+                       the basename of sys.argv[0].
+        human_sponsor: Accountable human for compliance (e.g. "alice@company.com").
+        kill_switch:   Start a global process-level kill-switch watcher. When an
+                       operator triggers a kill for this agent, the next LLM call
+                       raises KillSwitchTriggered before executing.
+        gate:          Pre-check every auto-captured LLM call against the
+                       compliance gate. Raises ComplianceViolation on a "block"
+                       decision. Defaults to True.
+        compliance:    Compliance frameworks to enforce, e.g.
+                       ["EU_AI_ACT", "RBI_MRM", "DPDP"].
+        auto_capture:  Monkey-patch all supported LLM libraries on init.
+                       Defaults to True.
+        ambient_runs:  Create real AgentRuns for undecorated LLM calls instead
+                       of anonymous shadow events. Enables drift detection,
+                       compliance evaluation, and cost reporting without any
+                       decorators. Defaults to True.
+
+    Returns:
+        PROVNTracker instance. Useful if you want to use tracker.llm_call(),
+        tracker.tool_call(), or @tracker.agent() alongside zero-config mode.
+    """
+    tracker = _tl.init(
+        api_key=api_key,
+        api_url=api_url,
+        agent_name=agent_name,
+        human_sponsor=human_sponsor,
+        auto_capture=auto_capture,
+        kill_switch=kill_switch,
+        gate=gate,
+        compliance=compliance,
+        ambient_runs=ambient_runs,
+    )
+    return tracker
+
+
+__all__ = [
+    "init",
+    "track",
+    "agent",
+    "get_passport_header",
+    "PROVNTracker",
+    "PROVNClient",
+    "AgentRun",
+    "TraceStep",
+    "StepType",
+    "KillSwitchTriggered",
+    "ComplianceViolation",
+    "ApprovalRejectedError",
+    "ApprovalTimeoutError",
+    "generate_keypair",
+    "get_public_key_pem",
+    "sign_run",
+    "verify_run",
+]

trustlayer/__init__.py

@@ -0,0 +1,180 @@
+from .tracker import track, agent, PROVNTracker, KillSwitchTriggered, ComplianceViolation
+from .client import PROVNClient
+from .models import AgentRun, TraceStep, StepType
+from .approval import ApprovalRejectedError, ApprovalTimeoutError
+from .crypto import generate_keypair, get_public_key_pem, sign_run, verify_run
+
+__version__ = "0.6.0"
+
+
+def init(
+    api_key: "str | None" = None,
+    api_url: "str | None" = None,
+    agent_name: "str | None" = None,
+    human_sponsor: "str | None" = None,
+    auto_capture: bool = True,
+    kill_switch: bool = False,
+    gate: bool = True,
+    compliance: "list[str] | None" = None,
+    ambient_runs: bool = True,
+    enforce: "list[str] | None" = None,
+) -> PROVNTracker:
+    """
+    Initialize FORMA with zero-config defaults.
+
+    Sets the module-level default tracker used by @track and @agent.
+    Call this once at the top of your application.
+
+        import trustlayer as tl
+
+        tl.init(api_key="tl_live_...", enforce=["dpdp"])
+
+        # Every LLM call is now ENFORCED: PII, prompt injection, and policy
+        # violations are blocked BEFORE the call executes — and every
+        # decision lands in the FORMA audit trail. No decorators needed.
+
+        # Or with full per-agent governance:
+        @tl.agent(
+            purpose="Loan application evaluation",
+            risk_level="HIGH",
+            kill_switch=True,
+            enforce=["rbi_ml_risk", "dpdp"],
+        )
+        def approve_loan(application: dict): ...
+
+    Args:
+        api_key:       FORMA API key (or FORMA_API_KEY env var).
+        api_url:       FORMA backend URL.
+        agent_name:    Display name for ambient auto-captured runs.
+        human_sponsor: Accountable human for compliance records.
+        auto_capture:  Monkey-patch OpenAI/Anthropic/LiteLLM/LangChain. Default True.
+        kill_switch:   Start a global process-level kill-switch watcher.
+        gate:          Pre-check every auto-captured LLM call via compliance gate.
+        compliance:    Compliance frameworks, e.g. ["EU_AI_ACT", "RBI_MRM"].
+        ambient_runs:  Create real AgentRuns for undecorated LLM calls. Default True.
+        enforce:       Framework policy packs enforced locally on every call
+                       (e.g. ["dpdp", "rbi_ml_risk", "eu_ai_act"]). Violations
+                       raise ComplianceViolation before the call executes.
+
+    Returns the tracker instance if you need tracker.llm_call() etc.
+    """
+    import trustlayer.tracker as _mod
+
+    tracker = PROVNTracker(
+        api_key=api_key,
+        api_url=api_url,
+        agent_name=agent_name,
+        human_sponsor=human_sponsor,
+        auto_capture=auto_capture,
+    )
+    _mod._default_tracker = tracker
+
+    tracker._configure_ambient(
+        agent_name=agent_name,
+        compliance=compliance,
+        gate=gate,
+        ambient_runs=ambient_runs,
+    )
+
+    if enforce:
+        try:
+            from .gate_local import get_shared_cache
+            cache = get_shared_cache(tracker._client)
+            if cache:
+                import trustlayer.auto as _auto
+                cache.register(_auto._ambient_config["agent_name"], list(enforce))
+        except Exception:
+            pass  # never fail init due to enforcement setup
+
+    if kill_switch:
+        try:
+            tracker._start_global_kill_watch(agent_name=agent_name)
+        except Exception:
+            pass  # never fail init due to kill-switch setup
+
+    return tracker
+
+
+def require_approval(
+    via: str = "forma",
+    url: "str | None" = None,
+    timeout: int = 3600,
+    poll_interval: int = 5,
+    message: "str | None" = None,
+    when=None,
+    title: "str | None" = None,
+):
+    """
+    Module-level @require_approval — pause the agent until a human decides
+    in the FORMA Approvals inbox (dashboard → Approvals).
+
+        @tl.track
+        @tl.require_approval(
+            when=lambda result: result["amount"] > 1_000_000,
+            message="Loan above ₹10L requires human review (RBI).",
+        )
+        def approve_loan(application): ...
+    """
+    import trustlayer.tracker as _mod
+    return _mod._get_default_tracker().require_approval(
+        via=via, url=url, timeout=timeout, poll_interval=poll_interval,
+        message=message, when=when, title=title,
+    )
+
+
+def get_passport_header(agent_name: "str | None" = None) -> dict:
+    """
+    Returns the X-PROVN-Passport HTTP header for inter-agent trust.
+
+    Use this when your agent calls another company's API that supports
+    the PROVN Inter-Agent Trust Protocol.
+
+    Example:
+        headers = tl.get_passport_header(agent_name="loan-approval-agent")
+        response = requests.post("https://api.partner.com/process",
+                                 headers=headers, json=payload)
+
+    The receiving API can verify your agent at:
+        GET /agent-trust/verify/{passport_id}
+    """
+    import trustlayer.tracker as _mod
+    tracker = _mod._get_default_tracker()
+    try:
+        import urllib.request, json as _json
+        url = f"{tracker.api_url.rstrip('/')}/agent-trust/my-passport"
+        req = urllib.request.Request(
+            url,
+            headers={"X-API-Key": tracker.api_key},
+        )
+        with urllib.request.urlopen(req, timeout=5) as resp:
+            data = _json.loads(resp.read())
+            agents = data.get("agents", [])
+            if agent_name:
+                agents = [a for a in agents if a.get("agent_name") == agent_name]
+            if agents:
+                return {"X-PROVN-Passport": agents[0]["passport_id"]}
+    except Exception:
+        pass
+    return {}
+
+
+__all__ = [
+    "track",
+    "agent",
+    "init",
+    "require_approval",
+    "get_passport_header",
+    "PROVNTracker",
+    "PROVNClient",
+    "AgentRun",
+    "TraceStep",
+    "StepType",
+    "KillSwitchTriggered",
+    "ComplianceViolation",
+    "ApprovalRejectedError",
+    "ApprovalTimeoutError",
+    "generate_keypair",
+    "get_public_key_pem",
+    "sign_run",
+    "verify_run",
+]