# notionalpha-clarity
**Python SDK for NotionAlpha Clarity - AI Value Realization Platform**
## Features
- **Cost Tracking** - Track LLM costs across providers (OpenAI, Anthropic, Azure OpenAI)
- **Security Detection** - Detect threats like PII leakage and prompt injection
- **Outcome Tracking** - Link business outcomes to LLM calls
- **ROI Calculation** - Calculate return on investment for AI features
- **Forecasting** - Predict future costs and value
- **Recommendations** - Get optimization suggestions
## Installation
```bash
pip install notionalpha-clarity openai anthropic
```
## Quick Start
### 1. Get Your Configuration
1. Sign up at [notionalpha.com](https://notionalpha.com)
2. Create a provider (OpenAI, Anthropic, or Azure OpenAI)
3. Create a team for cost attribution
4. Copy your `org_id`, `team_id`, and `provider_id`
### 2. Initialize the Client
```python
from notionalpha import NotionAlphaClient
import os
clarity = NotionAlphaClient(
org_id=os.getenv('NOTIONALPHA_ORG_ID'),
team_id=os.getenv('NOTIONALPHA_TEAM_ID'),
environment='production',
provider={
'type': 'openai',
'provider_id': os.getenv('NOTIONALPHA_PROVIDER_ID')
}
)
```
### 3. Make LLM Calls
```python
# OpenAI
response, transaction_id = clarity.chat.completions.create(
model='gpt-4o-mini',
messages=[{'role': 'user', 'content': 'Help me resolve this ticket'}]
)
print(response.choices[0].message.content)
# Cost and security are tracked automatically
```
### 4. Track Outcomes
```python
# Link business outcome to LLM call
clarity.track_outcome(
transaction_id=transaction_id,
type='customer_support',
metadata={
'ticket_id': 'TICKET-456',
'resolution_time_seconds': 120,
'customer_satisfaction': 5,
'time_saved_minutes': 15
}
)
```
### 5. View Value Realization
```python
# Get ROI summary
value = clarity.get_value_realization()
print(f"""
Total Cost: ${value['total_cost']}
Total Value: ${value['total_value']}
ROI: {value['roi']}x
""")
```
## Complete Example: Customer Support Bot
```python
from notionalpha import NotionAlphaClient
import os
clarity = NotionAlphaClient(
org_id=os.getenv('NOTIONALPHA_ORG_ID'),
team_id=os.getenv('NOTIONALPHA_TEAM_ID'),
environment='production',
feature_id='customer-support-bot',
provider={
'type': 'openai',
'provider_id': os.getenv('NOTIONALPHA_PROVIDER_ID')
}
)
async def resolve_ticket(ticket_id: str, question: str):
# Step 1: Make LLM call
response, transaction_id = clarity.chat.completions.create(
model='gpt-4o-mini',
messages=[{'role': 'user', 'content': question}]
)
# Step 2: Track outcome
clarity.track_outcome(
transaction_id=transaction_id,
type='customer_support',
metadata={
'ticket_id': ticket_id,
'time_saved_minutes': 15,
'customer_satisfaction': 5
}
)
return response.choices[0].message.content
# Use it
await resolve_ticket('TICKET-123', 'How do I reset my password?')
# Later: View ROI
value = clarity.get_value_realization()
print(f"ROI: {value['roi']}x") # e.g., "ROI: 25x"
```
## Supported Providers
### OpenAI
```python
clarity = NotionAlphaClient(
org_id='org_xxx',
team_id='team-uuid',
provider={'type': 'openai', 'provider_id': 'provider-uuid'}
)
response, transaction_id = clarity.chat.completions.create(
model='gpt-4o-mini',
messages=[{'role': 'user', 'content': 'Hello!'}]
)
```
### Anthropic
```python
clarity = NotionAlphaClient(
org_id='org_xxx',
team_id='team-uuid',
provider={'type': 'anthropic', 'provider_id': 'provider-uuid'}
)
response, transaction_id = clarity.messages.create(
model='claude-3-5-sonnet-20241022',
max_tokens=1024,
messages=[{'role': 'user', 'content': 'Hello!'}]
)
```
### Azure OpenAI
```python
clarity = NotionAlphaClient(
org_id='org_xxx',
team_id='team-uuid',
provider={
'type': 'azure-openai',
'provider_id': 'provider-uuid',
'deployment_name': 'gpt-4o-mini'
}
)
response, transaction_id = clarity.chat.completions.create(
model='gpt-4o-mini',
messages=[{'role': 'user', 'content': 'Hello!'}]
)
```
## API Reference
### NotionAlphaClient
Main client for interacting with NotionAlpha Clarity.
**Parameters:**
- `org_id` (str): Organization ID from NotionAlpha dashboard
- `team_id` (str): Team ID for cost attribution
- `environment` (str, optional): Environment name (default: 'production')
- `feature_id` (str, optional): Feature ID for granular tracking
- `provider` (dict): Provider configuration
- `api_base_url` (str, optional): Base URL for NotionAlpha API
- `proxy_base_url` (str, optional): Base URL for NotionAlpha proxy
### Methods
#### `chat.completions.create(**kwargs)`
Create a chat completion (OpenAI/Azure OpenAI).
**Returns:** `(response, transaction_id)`
#### `messages.create(**kwargs)`
Create a message (Anthropic).
**Returns:** `(response, transaction_id)`
#### `track_outcome(transaction_id, type, metadata, timestamp=None)`
Track a business outcome.
**Parameters:**
- `transaction_id` (str): Transaction ID from LLM response
- `type` (str): Outcome type (e.g., 'customer_support', 'code_generation')
- `metadata` (dict): Outcome-specific metadata
- `timestamp` (datetime, optional): Outcome timestamp (default: now)
#### `get_value_realization()`
Get value realization summary.
**Returns:** `dict` with `total_cost`, `total_value`, `roi`, etc.
## Development Status
🚧 **Python SDK is currently in development**
For now, you can use direct API integration. See the [API documentation](https://docs.notionalpha.com) for details.
## License
MIT
Raw data
{
"_id": null,
"home_page": null,
"name": "notionalpha-clarity",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "notionalpha, clarity, ai, llm, finops, value-realization, roi, openai, anthropic, azure",
"author": null,
"author_email": "NotionAlpha <support@notionalpha.com>",
"download_url": "https://files.pythonhosted.org/packages/df/ad/956b8d716e7ad45bc6bb1578a33e7d580e577c4f3ebb96cc6ea64c2547c0/notionalpha_clarity-0.1.3.tar.gz",
"platform": null,
"description": "# notionalpha-clarity\n\n**Python SDK for NotionAlpha Clarity - AI Value Realization Platform**\n\n## Features\n\n- **Cost Tracking** - Track LLM costs across providers (OpenAI, Anthropic, Azure OpenAI)\n- **Security Detection** - Detect threats like PII leakage and prompt injection\n- **Outcome Tracking** - Link business outcomes to LLM calls\n- **ROI Calculation** - Calculate return on investment for AI features\n- **Forecasting** - Predict future costs and value\n- **Recommendations** - Get optimization suggestions\n\n## Installation\n\n```bash\npip install notionalpha-clarity openai anthropic\n```\n\n## Quick Start\n\n### 1. Get Your Configuration\n\n1. Sign up at [notionalpha.com](https://notionalpha.com)\n2. Create a provider (OpenAI, Anthropic, or Azure OpenAI)\n3. Create a team for cost attribution\n4. Copy your `org_id`, `team_id`, and `provider_id`\n\n### 2. Initialize the Client\n\n```python\nfrom notionalpha import NotionAlphaClient\nimport os\n\nclarity = NotionAlphaClient(\n org_id=os.getenv('NOTIONALPHA_ORG_ID'),\n team_id=os.getenv('NOTIONALPHA_TEAM_ID'),\n environment='production',\n provider={\n 'type': 'openai',\n 'provider_id': os.getenv('NOTIONALPHA_PROVIDER_ID')\n }\n)\n```\n\n### 3. Make LLM Calls\n\n```python\n# OpenAI\nresponse, transaction_id = clarity.chat.completions.create(\n model='gpt-4o-mini',\n messages=[{'role': 'user', 'content': 'Help me resolve this ticket'}]\n)\n\nprint(response.choices[0].message.content)\n# Cost and security are tracked automatically\n```\n\n### 4. Track Outcomes\n\n```python\n# Link business outcome to LLM call\nclarity.track_outcome(\n transaction_id=transaction_id,\n type='customer_support',\n metadata={\n 'ticket_id': 'TICKET-456',\n 'resolution_time_seconds': 120,\n 'customer_satisfaction': 5,\n 'time_saved_minutes': 15\n }\n)\n```\n\n### 5. View Value Realization\n\n```python\n# Get ROI summary\nvalue = clarity.get_value_realization()\n\nprint(f\"\"\"\n Total Cost: ${value['total_cost']}\n Total Value: ${value['total_value']}\n ROI: {value['roi']}x\n\"\"\")\n```\n\n## Complete Example: Customer Support Bot\n\n```python\nfrom notionalpha import NotionAlphaClient\nimport os\n\nclarity = NotionAlphaClient(\n org_id=os.getenv('NOTIONALPHA_ORG_ID'),\n team_id=os.getenv('NOTIONALPHA_TEAM_ID'),\n environment='production',\n feature_id='customer-support-bot',\n provider={\n 'type': 'openai',\n 'provider_id': os.getenv('NOTIONALPHA_PROVIDER_ID')\n }\n)\n\nasync def resolve_ticket(ticket_id: str, question: str):\n # Step 1: Make LLM call\n response, transaction_id = clarity.chat.completions.create(\n model='gpt-4o-mini',\n messages=[{'role': 'user', 'content': question}]\n )\n\n # Step 2: Track outcome\n clarity.track_outcome(\n transaction_id=transaction_id,\n type='customer_support',\n metadata={\n 'ticket_id': ticket_id,\n 'time_saved_minutes': 15,\n 'customer_satisfaction': 5\n }\n )\n\n return response.choices[0].message.content\n\n# Use it\nawait resolve_ticket('TICKET-123', 'How do I reset my password?')\n\n# Later: View ROI\nvalue = clarity.get_value_realization()\nprint(f\"ROI: {value['roi']}x\") # e.g., \"ROI: 25x\"\n```\n\n## Supported Providers\n\n### OpenAI\n\n```python\nclarity = NotionAlphaClient(\n org_id='org_xxx',\n team_id='team-uuid',\n provider={'type': 'openai', 'provider_id': 'provider-uuid'}\n)\n\nresponse, transaction_id = clarity.chat.completions.create(\n model='gpt-4o-mini',\n messages=[{'role': 'user', 'content': 'Hello!'}]\n)\n```\n\n### Anthropic\n\n```python\nclarity = NotionAlphaClient(\n org_id='org_xxx',\n team_id='team-uuid',\n provider={'type': 'anthropic', 'provider_id': 'provider-uuid'}\n)\n\nresponse, transaction_id = clarity.messages.create(\n model='claude-3-5-sonnet-20241022',\n max_tokens=1024,\n messages=[{'role': 'user', 'content': 'Hello!'}]\n)\n```\n\n### Azure OpenAI\n\n```python\nclarity = NotionAlphaClient(\n org_id='org_xxx',\n team_id='team-uuid',\n provider={\n 'type': 'azure-openai',\n 'provider_id': 'provider-uuid',\n 'deployment_name': 'gpt-4o-mini'\n }\n)\n\nresponse, transaction_id = clarity.chat.completions.create(\n model='gpt-4o-mini',\n messages=[{'role': 'user', 'content': 'Hello!'}]\n)\n```\n\n## API Reference\n\n### NotionAlphaClient\n\nMain client for interacting with NotionAlpha Clarity.\n\n**Parameters:**\n- `org_id` (str): Organization ID from NotionAlpha dashboard\n- `team_id` (str): Team ID for cost attribution\n- `environment` (str, optional): Environment name (default: 'production')\n- `feature_id` (str, optional): Feature ID for granular tracking\n- `provider` (dict): Provider configuration\n- `api_base_url` (str, optional): Base URL for NotionAlpha API\n- `proxy_base_url` (str, optional): Base URL for NotionAlpha proxy\n\n### Methods\n\n#### `chat.completions.create(**kwargs)`\n\nCreate a chat completion (OpenAI/Azure OpenAI).\n\n**Returns:** `(response, transaction_id)`\n\n#### `messages.create(**kwargs)`\n\nCreate a message (Anthropic).\n\n**Returns:** `(response, transaction_id)`\n\n#### `track_outcome(transaction_id, type, metadata, timestamp=None)`\n\nTrack a business outcome.\n\n**Parameters:**\n- `transaction_id` (str): Transaction ID from LLM response\n- `type` (str): Outcome type (e.g., 'customer_support', 'code_generation')\n- `metadata` (dict): Outcome-specific metadata\n- `timestamp` (datetime, optional): Outcome timestamp (default: now)\n\n#### `get_value_realization()`\n\nGet value realization summary.\n\n**Returns:** `dict` with `total_cost`, `total_value`, `roi`, etc.\n\n## Development Status\n\n\ud83d\udea7 **Python SDK is currently in development**\n\nFor now, you can use direct API integration. See the [API documentation](https://docs.notionalpha.com) for details.\n\n## License\n\nMIT\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python SDK for NotionAlpha Clarity - AI Value Realization Platform",
"version": "0.1.3",
"project_urls": {
"Documentation": "https://docs.notionalpha.com",
"Homepage": "https://notionalpha.com",
"Issues": "https://github.com/NotionAlpha/notionalpha/issues",
"Repository": "https://github.com/NotionAlpha/notionalpha"
},
"split_keywords": [
"notionalpha",
" clarity",
" ai",
" llm",
" finops",
" value-realization",
" roi",
" openai",
" anthropic",
" azure"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b843df57f5dc73a8b52e8cec8ce149763ddf2fce7a478fac02591e5baee37a09",
"md5": "a2d7bc492a3366cfcda528381c62ec63",
"sha256": "5aa5d2a63f56621b20c931b7484d1341ac8586ed22e7924fe12d408f5a82d693"
},
"downloads": -1,
"filename": "notionalpha_clarity-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a2d7bc492a3366cfcda528381c62ec63",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 11790,
"upload_time": "2025-10-26T09:21:41",
"upload_time_iso_8601": "2025-10-26T09:21:41.041939Z",
"url": "https://files.pythonhosted.org/packages/b8/43/df57f5dc73a8b52e8cec8ce149763ddf2fce7a478fac02591e5baee37a09/notionalpha_clarity-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "dfad956b8d716e7ad45bc6bb1578a33e7d580e577c4f3ebb96cc6ea64c2547c0",
"md5": "39257756ddce1c09ca108cba300a54f9",
"sha256": "10773bd8d236336d2fd8c8930ccc4b14f898eec79fd7b556fb577e75b0aa6c61"
},
"downloads": -1,
"filename": "notionalpha_clarity-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "39257756ddce1c09ca108cba300a54f9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 12144,
"upload_time": "2025-10-26T09:21:41",
"upload_time_iso_8601": "2025-10-26T09:21:41.974350Z",
"url": "https://files.pythonhosted.org/packages/df/ad/956b8d716e7ad45bc6bb1578a33e7d580e577c4f3ebb96cc6ea64c2547c0/notionalpha_clarity-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-26 09:21:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "NotionAlpha",
"github_project": "notionalpha",
"github_not_found": true,
"lcname": "notionalpha-clarity"
}
JSON
