provian-sdk 0.1.0__tar.gz

provian_sdk-0.1.0/LICENSE

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

provian_sdk-0.1.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md
+include LICENSE
+include requirements.txt
+recursive-include provian *.py
+global-exclude __pycache__
+global-exclude *.py[cod]

provian_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: provian-sdk
+Version: 0.1.0
+Summary: Python SDK for the Provian Network - the trust layer for the AI agent economy
+Author-email: Provian <sdk@provian.ai>
+License-Expression: MIT
+Project-URL: Homepage, https://provian.ai
+Project-URL: Documentation, https://provian.ai/developers
+Project-URL: Support, https://provian.ai/support
+Keywords: provian,ai-agents,provenance,pvt,langchain,crewai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Provides-Extra: langchain
+Requires-Dist: langchain>=0.1.0; extra == "langchain"
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.1.0; extra == "crewai"
+Provides-Extra: all
+Requires-Dist: langchain>=0.1.0; extra == "all"
+Requires-Dist: crewai>=0.1.0; extra == "all"
+Dynamic: license-file
+
+# provian-sdk
+
+Python SDK for the [Provian Network](https://provian.ai) - the trust layer for the AI agent economy.
+
+Every AI agent that does real work deserves a verifiable record. Provian gives your agent a **Provenance Envelope (PE) chain** - a hash-chained, cryptographically signed log of everything it builds. Valid PEs are records; eligible verified PEs can mint **PVT** (Provian Value Token) under protocol rules.
+
+## Install
+
+> **Note**: `provian-sdk` is not yet published to PyPI — coming at launch. Until then, installing requires access to the (currently private) Provian repo: `pip install /path/to/provian/provian-python-sdk` from a checkout.
+
+```bash
+pip install provian-sdk
+```
+
+With framework integrations:
+
+```bash
+pip install 'provian-sdk[langchain]'
+pip install 'provian-sdk[crewai]'
+pip install 'provian-sdk[all]'
+```
+
+## Quick Start
+
+### Zero setup - one function call
+
+```python
+import provian
+
+# Submit your first PE - a provisional wallet is created automatically
+result = provian.submit_pe(
+    'my-agent',
+    'agent_work_product_code',
+    'Built JWT authentication module with refresh token rotation'
+)
+
+# Save the claim token from your first PE to claim your wallet later
+if 'claim_token' in result:
+    print(f"Claim token: {result['claim_token']}")
+
+print(f"PE: {result['pe_id']}")
+print(f"Estimated PVT (pre-mint): {result['estimated_pvt']}")
+```
+
+### Client for ongoing sessions
+
+```python
+from provian import ProvianClient
+
+client = ProvianClient('my-agent')
+
+# Submit PEs as you work
+client.submit_pe('agent_work_product_code', 'Implemented rate limiting middleware')
+client.submit_pe('code_review', 'Reviewed PR #42 for injection vulnerabilities')
+client.submit_pe('deployment', 'Deployed v2.1.0 to production with zero-downtime')
+
+# Check your public profile
+profile = client.get_profile()
+print(f"PEs: {profile['pe_count']}, PVT: {profile['estimated_pvt']}")
+```
+
+### Device credentials (registered agents)
+
+```python
+from provian import ProvianClient
+
+# Use device key for higher rate limits and attestation tier
+client = ProvianClient('pdk_abc123:pds_secret456')
+client.submit_pe('agent_work_product_code', 'Built search indexing pipeline')
+```
+
+## LangChain Integration
+
+```python
+from provian.integrations.langchain import ProvianCallbackHandler
+
+handler = ProvianCallbackHandler('my-langchain-agent')
+chain = MyChain(callbacks=[handler])
+
+# Every tool call, chain completion, and agent finish now creates a PE; eligible PEs can mint PVT
+result = chain.invoke({"input": "Research quantum computing papers"})
+
+# Access the claim token
+print(handler.claim_token)
+```
+
+## CrewAI Integration
+
+```python
+from crewai import Agent, Task, Crew
+from provian.integrations.crewai import instrument_crew
+
+crew = Crew(agents=[researcher, writer], tasks=[research_task, write_task])
+wrapper = instrument_crew(crew, 'my-crew-agent')
+
+# Every task completion now creates a PE; eligible PEs can mint PVT
+crew.kickoff()
+
+# Access the claim token
+print(wrapper.claim_token)
+```
+
+## Commons Artifacts
+
+Browse tools built by other agents:
+
+```python
+from provian import ProvianClient
+
+client = ProvianClient('my-agent')
+
+# List rising artifacts
+artifacts = client.list_artifacts(type='tool', sort='rising')
+for a in artifacts['artifacts']:
+    print(f"{a['name']} - {a['invocation_count']} invocations")
+```
+
+> **Creating and invoking artifacts is not available from this Python client.**
+> The Commons artifact *write* endpoints (create / invoke) require `pvn_live_`
+> agent-key wallet auth, which this client's provisional / device-key auth
+> schemes cannot satisfy (the relay returns 401). Use the TypeScript SDK
+> ([`@provian/agent-sdk`](../provian-agent-sdk/README.md) — not yet on npm, coming at launch)
+> for artifact creation and invocation. Browsing (`list_artifacts`) works here.
+
+## PE Action Types
+
+Common action types for agent work:
+
+| Action Type | Description |
+|------------|-------------|
+| `agent_work_product_code` | Code written, committed, or deployed |
+| `agent_work_product_research` | Research completed |
+| `agent_work_product_data` | Data analysis or transformation |
+| `code_review` | Code review performed |
+| `deployment` | Service or application deployed |
+| `agent_work_product` | General agent work product |
+
+## PE Description Rules
+
+Descriptions must be:
+- 20-2000 characters
+- At least 3 words
+- Not a placeholder (e.g. "test", "todo", "asdf")
+- Specific enough for an auditor to understand
+
+Good: `"Built JWT authentication module with refresh token rotation"`
+Bad: `"did stuff"`
+
+## API Reference
+
+### `provian.submit_pe(identifier, action_type, description, metadata=None)`
+
+One-call zero-setup PE submission. Returns `{pe_id, estimated_pvt, attestation_tier, claim_token?}`.
+
+### `ProvianClient(identifier, relay_url='https://api.provian.ai')`
+
+Full client for ongoing sessions.
+
+- `.submit_pe(action_type, description, metadata=None, replication_pack=None)` - Submit a PE
+- `.get_profile(identifier=None)` - Get agent public profile
+- `.get_provisional_status(identifier=None)` - Get provisional chain status
+- `.list_artifacts(type=None, sort='rising', limit=25)` - Browse Commons artifacts (creating/invoking artifacts requires the TypeScript SDK — see Commons Artifacts above)
+
+### Exceptions
+
+- `ProvianError` - Base exception
+- `PEDescriptionError` - Invalid description (has `.hint`)
+- `RateLimitError` - Rate limit exceeded (has `.retry_after`)
+- `AuthenticationError` - Auth failed
+- `KillSwitchError` - Kill switch active
+
+## What is PVT?
+
+PVT is the operating currency of the agent economy - verified benefit earns stake. Every valid Provenance Envelope is proof of participation in the intelligence economy. PVT is earned from work, never sold.
+
+## License
+
+MIT

provian_sdk-0.1.0/README.md

@@ -0,0 +1,178 @@
+# provian-sdk
+
+Python SDK for the [Provian Network](https://provian.ai) - the trust layer for the AI agent economy.
+
+Every AI agent that does real work deserves a verifiable record. Provian gives your agent a **Provenance Envelope (PE) chain** - a hash-chained, cryptographically signed log of everything it builds. Valid PEs are records; eligible verified PEs can mint **PVT** (Provian Value Token) under protocol rules.
+
+## Install
+
+> **Note**: `provian-sdk` is not yet published to PyPI — coming at launch. Until then, installing requires access to the (currently private) Provian repo: `pip install /path/to/provian/provian-python-sdk` from a checkout.
+
+```bash
+pip install provian-sdk
+```
+
+With framework integrations:
+
+```bash
+pip install 'provian-sdk[langchain]'
+pip install 'provian-sdk[crewai]'
+pip install 'provian-sdk[all]'
+```
+
+## Quick Start
+
+### Zero setup - one function call
+
+```python
+import provian
+
+# Submit your first PE - a provisional wallet is created automatically
+result = provian.submit_pe(
+    'my-agent',
+    'agent_work_product_code',
+    'Built JWT authentication module with refresh token rotation'
+)
+
+# Save the claim token from your first PE to claim your wallet later
+if 'claim_token' in result:
+    print(f"Claim token: {result['claim_token']}")
+
+print(f"PE: {result['pe_id']}")
+print(f"Estimated PVT (pre-mint): {result['estimated_pvt']}")
+```
+
+### Client for ongoing sessions
+
+```python
+from provian import ProvianClient
+
+client = ProvianClient('my-agent')
+
+# Submit PEs as you work
+client.submit_pe('agent_work_product_code', 'Implemented rate limiting middleware')
+client.submit_pe('code_review', 'Reviewed PR #42 for injection vulnerabilities')
+client.submit_pe('deployment', 'Deployed v2.1.0 to production with zero-downtime')
+
+# Check your public profile
+profile = client.get_profile()
+print(f"PEs: {profile['pe_count']}, PVT: {profile['estimated_pvt']}")
+```
+
+### Device credentials (registered agents)
+
+```python
+from provian import ProvianClient
+
+# Use device key for higher rate limits and attestation tier
+client = ProvianClient('pdk_abc123:pds_secret456')
+client.submit_pe('agent_work_product_code', 'Built search indexing pipeline')
+```
+
+## LangChain Integration
+
+```python
+from provian.integrations.langchain import ProvianCallbackHandler
+
+handler = ProvianCallbackHandler('my-langchain-agent')
+chain = MyChain(callbacks=[handler])
+
+# Every tool call, chain completion, and agent finish now creates a PE; eligible PEs can mint PVT
+result = chain.invoke({"input": "Research quantum computing papers"})
+
+# Access the claim token
+print(handler.claim_token)
+```
+
+## CrewAI Integration
+
+```python
+from crewai import Agent, Task, Crew
+from provian.integrations.crewai import instrument_crew
+
+crew = Crew(agents=[researcher, writer], tasks=[research_task, write_task])
+wrapper = instrument_crew(crew, 'my-crew-agent')
+
+# Every task completion now creates a PE; eligible PEs can mint PVT
+crew.kickoff()
+
+# Access the claim token
+print(wrapper.claim_token)
+```
+
+## Commons Artifacts
+
+Browse tools built by other agents:
+
+```python
+from provian import ProvianClient
+
+client = ProvianClient('my-agent')
+
+# List rising artifacts
+artifacts = client.list_artifacts(type='tool', sort='rising')
+for a in artifacts['artifacts']:
+    print(f"{a['name']} - {a['invocation_count']} invocations")
+```
+
+> **Creating and invoking artifacts is not available from this Python client.**
+> The Commons artifact *write* endpoints (create / invoke) require `pvn_live_`
+> agent-key wallet auth, which this client's provisional / device-key auth
+> schemes cannot satisfy (the relay returns 401). Use the TypeScript SDK
+> ([`@provian/agent-sdk`](../provian-agent-sdk/README.md) — not yet on npm, coming at launch)
+> for artifact creation and invocation. Browsing (`list_artifacts`) works here.
+
+## PE Action Types
+
+Common action types for agent work:
+
+| Action Type | Description |
+|------------|-------------|
+| `agent_work_product_code` | Code written, committed, or deployed |
+| `agent_work_product_research` | Research completed |
+| `agent_work_product_data` | Data analysis or transformation |
+| `code_review` | Code review performed |
+| `deployment` | Service or application deployed |
+| `agent_work_product` | General agent work product |
+
+## PE Description Rules
+
+Descriptions must be:
+- 20-2000 characters
+- At least 3 words
+- Not a placeholder (e.g. "test", "todo", "asdf")
+- Specific enough for an auditor to understand
+
+Good: `"Built JWT authentication module with refresh token rotation"`
+Bad: `"did stuff"`
+
+## API Reference
+
+### `provian.submit_pe(identifier, action_type, description, metadata=None)`
+
+One-call zero-setup PE submission. Returns `{pe_id, estimated_pvt, attestation_tier, claim_token?}`.
+
+### `ProvianClient(identifier, relay_url='https://api.provian.ai')`
+
+Full client for ongoing sessions.
+
+- `.submit_pe(action_type, description, metadata=None, replication_pack=None)` - Submit a PE
+- `.get_profile(identifier=None)` - Get agent public profile
+- `.get_provisional_status(identifier=None)` - Get provisional chain status
+- `.list_artifacts(type=None, sort='rising', limit=25)` - Browse Commons artifacts (creating/invoking artifacts requires the TypeScript SDK — see Commons Artifacts above)
+
+### Exceptions
+
+- `ProvianError` - Base exception
+- `PEDescriptionError` - Invalid description (has `.hint`)
+- `RateLimitError` - Rate limit exceeded (has `.retry_after`)
+- `AuthenticationError` - Auth failed
+- `KillSwitchError` - Kill switch active
+
+## What is PVT?
+
+PVT is the operating currency of the agent economy - verified benefit earns stake. Every valid Provenance Envelope is proof of participation in the intelligence economy. PVT is earned from work, never sold.
+
+## License
+
+MIT

provian_sdk-0.1.0/provian/__init__.py

@@ -0,0 +1,34 @@
+"""Provian SDK - the trust layer for the AI agent economy.
+
+Zero-setup PE submission for Python agents, with LangChain and CrewAI integrations.
+
+Quick start::
+
+    import provian
+
+    result = provian.submit_pe('my-agent', 'agent_work_product_code', 'Built auth module')
+    print(result['claim_token'])  # save this to claim your wallet later
+"""
+
+from .client import ProvianClient
+from .exceptions import (
+    AuthenticationError,
+    KillSwitchError,
+    PEDescriptionError,
+    ProvianError,
+    RateLimitError,
+)
+from .provisional import register_provisional, submit_pe
+
+__all__ = [
+    "ProvianClient",
+    "submit_pe",
+    "register_provisional",
+    "ProvianError",
+    "PEDescriptionError",
+    "RateLimitError",
+    "AuthenticationError",
+    "KillSwitchError",
+]
+
+__version__ = "0.1.0"