smartflow-sdk 0.2.0__tar.gz

smartflow_sdk-0.2.0/LICENSE

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

smartflow_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,345 @@
+Metadata-Version: 2.4
+Name: smartflow-sdk
+Version: 0.2.0
+Summary: Developer SDK for Smartflow AI orchestration, caching, compliance, and governance
+Author-email: "Langsmart, Inc." <scott@sragrouptx.com>
+License-Expression: MIT
+Project-URL: Homepage, https://smartflow.ai
+Project-URL: Documentation, https://docs.smartflow.ai/sdk/python
+Project-URL: Repository, https://github.com/langsmart/smartflow-sdk-python
+Project-URL: Changelog, https://github.com/langsmart/smartflow-sdk-python/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/langsmart/smartflow-sdk-python/issues
+Keywords: ai,llm,openai,anthropic,claude,gpt,caching,compliance,governance,orchestration,proxy,agents,ml,enterprise
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Provides-Extra: nest
+Requires-Dist: nest-asyncio>=1.5; extra == "nest"
+Dynamic: license-file
+
+# Smartflow Python SDK
+
+The official Python SDK for [Smartflow](https://smartflow.ai) - the enterprise AI orchestration, caching, compliance, and governance platform.
+
+## Features
+
+- **🚀 Simple API** - Chat, embeddings, and completions with one line of code
+- **💰 60-80% Cost Savings** - 3-layer semantic caching (L1/L2/L3)
+- **🛡️ ML-Powered Compliance** - Intelligent PII detection with adaptive learning
+- **🔄 Automatic Failover** - Multi-provider routing with intelligent fallback
+- **📊 Full Audit Trail** - VAS logs for every AI interaction
+- **🤖 Agent Builder** - Create AI agents with built-in compliance
+- **📈 Workflow Orchestration** - Chain AI operations with branching and error handling
+
+## Installation
+
+```bash
+pip install smartflow-sdk
+```
+
+## Quick Start
+
+### Async Usage (Recommended)
+
+```python
+import asyncio
+from smartflow import SmartflowClient
+
+async def main():
+    async with SmartflowClient("http://your-smartflow:7775") as sf:
+        # Simple chat
+        response = await sf.chat("What is machine learning?")
+        print(response)
+        
+        # Check cache stats
+        stats = await sf.get_cache_stats()
+        print(f"Cache hit rate: {stats.hit_rate:.1%}")
+        print(f"Tokens saved: {stats.tokens_saved:,}")
+
+asyncio.run(main())
+```
+
+### Sync Usage
+
+```python
+from smartflow import SyncSmartflowClient
+
+sf = SyncSmartflowClient("http://your-smartflow:7775")
+
+response = sf.chat("Explain quantum computing")
+print(response)
+
+sf.close()
+```
+
+### OpenAI Drop-in Replacement
+
+Just change the `base_url` - your existing OpenAI code works with Smartflow!
+
+```python
+from openai import OpenAI
+
+# Point to Smartflow instead of OpenAI
+client = OpenAI(
+    base_url="http://your-smartflow:7775/v1",
+    api_key="your-key"  # Or use Smartflow's stored keys
+)
+
+response = client.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Hello!"}]
+)
+print(response.choices[0].message.content)
+```
+
+## Intelligent Compliance (ML-Powered)
+
+Smartflow's adaptive learning compliance engine provides:
+
+- **Regex Pattern Matching** - SSN, credit cards, emails, phone numbers, etc.
+- **ML Embedding Similarity** - Semantic violation detection
+- **Behavioral Analysis** - User pattern tracking and anomaly detection
+- **Organization Baselines** - Deviation detection from org norms
+
+```python
+async with SmartflowClient("http://your-smartflow:7775") as sf:
+    # Scan content for compliance issues
+    result = await sf.intelligent_scan(
+        content="My SSN is 123-45-6789 and my email is john@example.com",
+        user_id="user123",
+        org_id="acme_corp"
+    )
+    
+    print(f"Risk Score: {result.risk_score:.2f}")
+    print(f"Risk Level: {result.risk_level}")
+    print(f"Action: {result.recommended_action}")
+    print(f"Explanation: {result.explanation}")
+    
+    # Check regex violations
+    for violation in result.regex_violations:
+        print(f"  - {violation['violation_type']}: {violation['severity']}")
+    
+    # Submit feedback to improve detection
+    await sf.submit_compliance_feedback(
+        scan_id="scan_abc123",
+        is_false_positive=True,
+        notes="This was a test number"
+    )
+    
+    # Get learning status
+    learning = await sf.get_learning_summary()
+    print(f"Users tracked: {learning.total_users}")
+    print(f"Learning complete: {learning.users_learning_complete}")
+    
+    # Get ML stats
+    ml_stats = await sf.get_ml_stats()
+    print(f"Total patterns: {ml_stats.total_patterns}")
+    print(f"Learned patterns: {ml_stats.learned_patterns}")
+```
+
+## Building AI Agents
+
+Create AI agents with built-in compliance scanning and conversation memory:
+
+```python
+from smartflow import SmartflowClient, SmartflowAgent
+
+async with SmartflowClient("http://your-smartflow:7775") as sf:
+    agent = SmartflowAgent(
+        client=sf,
+        name="CustomerSupport",
+        model="gpt-4o",
+        system_prompt="""You are a helpful customer support agent for TechCorp.
+        Be professional, friendly, and always protect customer data.""",
+        compliance_policy="enterprise_standard",
+        enable_compliance_scan=True,
+        user_id="support_agent_1",
+        org_id="techcorp"
+    )
+    
+    # Chat with automatic compliance scanning
+    response = await agent.chat("How do I reset my password?")
+    print(response)
+    
+    # Conversation memory is maintained
+    response = await agent.chat("What about two-factor authentication?")
+    print(response)
+    
+    # Get conversation history
+    history = agent.get_history()
+    print(f"Messages: {len(history)}")
+    
+    # Clear and start fresh
+    agent.clear_history()
+```
+
+## Workflow Orchestration
+
+Chain AI operations with branching, parallel execution, and error handling:
+
+```python
+from smartflow import SmartflowClient, SmartflowWorkflow
+
+async with SmartflowClient("http://your-smartflow:7775") as sf:
+    workflow = SmartflowWorkflow(sf, name="TicketClassification")
+    
+    # Step 1: Classify the ticket
+    workflow.add_step(
+        name="classify",
+        action="chat",
+        config={
+            "prompt": "Classify this support ticket into one of: billing, technical, account. Ticket: {input}",
+            "model": "gpt-4o-mini"
+        },
+        next_steps=["route"]
+    )
+    
+    # Step 2: Route based on classification
+    workflow.add_step(
+        name="route",
+        action="condition",
+        config={
+            "field": "output",
+            "cases": {
+                "billing": "billing_response",
+                "technical": "technical_response",
+                "account": "account_response"
+            },
+            "default": "general_response"
+        }
+    )
+    
+    # Execute the workflow
+    result = await workflow.execute({"input": "My payment failed yesterday"})
+    
+    print(f"Success: {result.success}")
+    print(f"Output: {result.output}")
+    print(f"Steps executed: {result.steps_executed}")
+    print(f"Execution time: {result.execution_time_ms:.1f}ms")
+```
+
+## Monitoring & Analytics
+
+```python
+async with SmartflowClient("http://your-smartflow:7775") as sf:
+    # System health
+    health = await sf.health_comprehensive()
+    print(f"Status: {health.status}")
+    print(f"Uptime: {health.uptime_seconds / 3600:.1f} hours")
+    
+    # Provider health
+    providers = await sf.get_provider_health()
+    for p in providers:
+        print(f"{p.provider}: {p.status} ({p.latency_ms:.0f}ms)")
+    
+    # Cache statistics
+    cache = await sf.get_cache_stats()
+    print(f"Hit rate: {cache.hit_rate:.1%}")
+    print(f"L1 hits: {cache.l1_hits}")
+    print(f"L2 hits: {cache.l2_hits}")
+    print(f"Tokens saved: {cache.tokens_saved:,}")
+    
+    # Audit logs
+    logs = await sf.get_logs(limit=10)
+    for log in logs:
+        print(f"{log.timestamp}: {log.provider}/{log.model} - {log.tokens_used} tokens")
+```
+
+## Configuration
+
+### Client Options
+
+```python
+sf = SmartflowClient(
+    base_url="http://smartflow:7775",      # Proxy URL
+    api_key="your-api-key",                 # Optional API key
+    timeout=30.0,                           # Request timeout
+    management_port=7778,                   # Management API port
+    compliance_port=7777,                   # Compliance API port
+    bridge_port=3500,                       # Hybrid bridge port
+)
+```
+
+### Environment Variables
+
+```bash
+export SMARTFLOW_URL="http://your-smartflow:7775"
+export SMARTFLOW_API_KEY="your-key"
+```
+
+## API Reference
+
+### SmartflowClient Methods
+
+| Method | Description |
+|--------|-------------|
+| `chat()` | Simple chat with AI |
+| `chat_completions()` | OpenAI-compatible completions |
+| `embeddings()` | Generate text embeddings |
+| `claude_message()` | Anthropic Claude API |
+| `intelligent_scan()` | ML-powered compliance scan |
+| `check_compliance()` | Basic compliance check |
+| `get_cache_stats()` | Cache hit rates and savings |
+| `health()` | Quick health check |
+| `health_comprehensive()` | Full system health |
+| `get_logs()` | VAS audit logs |
+| `get_provider_health()` | Provider status |
+
+### SmartflowAgent Methods
+
+| Method | Description |
+|--------|-------------|
+| `chat()` | Chat with compliance scanning |
+| `clear_history()` | Reset conversation |
+| `get_history()` | Get conversation history |
+
+### SmartflowWorkflow Methods
+
+| Method | Description |
+|--------|-------------|
+| `add_step()` | Add a workflow step |
+| `set_entry()` | Set entry point |
+| `execute()` | Run the workflow |
+
+## Examples
+
+See the [examples/](./examples/) directory for more:
+
+- `simple_chat.py` - Basic chat usage
+- `compliance_check.py` - PII detection and redaction
+- `system_monitoring.py` - Health and analytics
+- `openai_drop_in.py` - OpenAI compatibility
+- `agent_example.py` - Building AI agents
+- `workflow_example.py` - Workflow orchestration
+
+## License
+
+MIT License - see [LICENSE](./LICENSE) for details.
+
+## Support
+
+- Documentation: https://docs.smartflow.ai/sdk/python
+- Issues: https://github.com/langsmart/smartflow-sdk-python/issues
+- Email: support@smartflow.ai
+
+---
+
+Built with ❤️ by [Langsmart, Inc.](https://smartflow.ai)

smartflow_sdk-0.2.0/README.md

@@ -0,0 +1,308 @@
+# Smartflow Python SDK
+
+The official Python SDK for [Smartflow](https://smartflow.ai) - the enterprise AI orchestration, caching, compliance, and governance platform.
+
+## Features
+
+- **🚀 Simple API** - Chat, embeddings, and completions with one line of code
+- **💰 60-80% Cost Savings** - 3-layer semantic caching (L1/L2/L3)
+- **🛡️ ML-Powered Compliance** - Intelligent PII detection with adaptive learning
+- **🔄 Automatic Failover** - Multi-provider routing with intelligent fallback
+- **📊 Full Audit Trail** - VAS logs for every AI interaction
+- **🤖 Agent Builder** - Create AI agents with built-in compliance
+- **📈 Workflow Orchestration** - Chain AI operations with branching and error handling
+
+## Installation
+
+```bash
+pip install smartflow-sdk
+```
+
+## Quick Start
+
+### Async Usage (Recommended)
+
+```python
+import asyncio
+from smartflow import SmartflowClient
+
+async def main():
+    async with SmartflowClient("http://your-smartflow:7775") as sf:
+        # Simple chat
+        response = await sf.chat("What is machine learning?")
+        print(response)
+        
+        # Check cache stats
+        stats = await sf.get_cache_stats()
+        print(f"Cache hit rate: {stats.hit_rate:.1%}")
+        print(f"Tokens saved: {stats.tokens_saved:,}")
+
+asyncio.run(main())
+```
+
+### Sync Usage
+
+```python
+from smartflow import SyncSmartflowClient
+
+sf = SyncSmartflowClient("http://your-smartflow:7775")
+
+response = sf.chat("Explain quantum computing")
+print(response)
+
+sf.close()
+```
+
+### OpenAI Drop-in Replacement
+
+Just change the `base_url` - your existing OpenAI code works with Smartflow!
+
+```python
+from openai import OpenAI
+
+# Point to Smartflow instead of OpenAI
+client = OpenAI(
+    base_url="http://your-smartflow:7775/v1",
+    api_key="your-key"  # Or use Smartflow's stored keys
+)
+
+response = client.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Hello!"}]
+)
+print(response.choices[0].message.content)
+```
+
+## Intelligent Compliance (ML-Powered)
+
+Smartflow's adaptive learning compliance engine provides:
+
+- **Regex Pattern Matching** - SSN, credit cards, emails, phone numbers, etc.
+- **ML Embedding Similarity** - Semantic violation detection
+- **Behavioral Analysis** - User pattern tracking and anomaly detection
+- **Organization Baselines** - Deviation detection from org norms
+
+```python
+async with SmartflowClient("http://your-smartflow:7775") as sf:
+    # Scan content for compliance issues
+    result = await sf.intelligent_scan(
+        content="My SSN is 123-45-6789 and my email is john@example.com",
+        user_id="user123",
+        org_id="acme_corp"
+    )
+    
+    print(f"Risk Score: {result.risk_score:.2f}")
+    print(f"Risk Level: {result.risk_level}")
+    print(f"Action: {result.recommended_action}")
+    print(f"Explanation: {result.explanation}")
+    
+    # Check regex violations
+    for violation in result.regex_violations:
+        print(f"  - {violation['violation_type']}: {violation['severity']}")
+    
+    # Submit feedback to improve detection
+    await sf.submit_compliance_feedback(
+        scan_id="scan_abc123",
+        is_false_positive=True,
+        notes="This was a test number"
+    )
+    
+    # Get learning status
+    learning = await sf.get_learning_summary()
+    print(f"Users tracked: {learning.total_users}")
+    print(f"Learning complete: {learning.users_learning_complete}")
+    
+    # Get ML stats
+    ml_stats = await sf.get_ml_stats()
+    print(f"Total patterns: {ml_stats.total_patterns}")
+    print(f"Learned patterns: {ml_stats.learned_patterns}")
+```
+
+## Building AI Agents
+
+Create AI agents with built-in compliance scanning and conversation memory:
+
+```python
+from smartflow import SmartflowClient, SmartflowAgent
+
+async with SmartflowClient("http://your-smartflow:7775") as sf:
+    agent = SmartflowAgent(
+        client=sf,
+        name="CustomerSupport",
+        model="gpt-4o",
+        system_prompt="""You are a helpful customer support agent for TechCorp.
+        Be professional, friendly, and always protect customer data.""",
+        compliance_policy="enterprise_standard",
+        enable_compliance_scan=True,
+        user_id="support_agent_1",
+        org_id="techcorp"
+    )
+    
+    # Chat with automatic compliance scanning
+    response = await agent.chat("How do I reset my password?")
+    print(response)
+    
+    # Conversation memory is maintained
+    response = await agent.chat("What about two-factor authentication?")
+    print(response)
+    
+    # Get conversation history
+    history = agent.get_history()
+    print(f"Messages: {len(history)}")
+    
+    # Clear and start fresh
+    agent.clear_history()
+```
+
+## Workflow Orchestration
+
+Chain AI operations with branching, parallel execution, and error handling:
+
+```python
+from smartflow import SmartflowClient, SmartflowWorkflow
+
+async with SmartflowClient("http://your-smartflow:7775") as sf:
+    workflow = SmartflowWorkflow(sf, name="TicketClassification")
+    
+    # Step 1: Classify the ticket
+    workflow.add_step(
+        name="classify",
+        action="chat",
+        config={
+            "prompt": "Classify this support ticket into one of: billing, technical, account. Ticket: {input}",
+            "model": "gpt-4o-mini"
+        },
+        next_steps=["route"]
+    )
+    
+    # Step 2: Route based on classification
+    workflow.add_step(
+        name="route",
+        action="condition",
+        config={
+            "field": "output",
+            "cases": {
+                "billing": "billing_response",
+                "technical": "technical_response",
+                "account": "account_response"
+            },
+            "default": "general_response"
+        }
+    )
+    
+    # Execute the workflow
+    result = await workflow.execute({"input": "My payment failed yesterday"})
+    
+    print(f"Success: {result.success}")
+    print(f"Output: {result.output}")
+    print(f"Steps executed: {result.steps_executed}")
+    print(f"Execution time: {result.execution_time_ms:.1f}ms")
+```
+
+## Monitoring & Analytics
+
+```python
+async with SmartflowClient("http://your-smartflow:7775") as sf:
+    # System health
+    health = await sf.health_comprehensive()
+    print(f"Status: {health.status}")
+    print(f"Uptime: {health.uptime_seconds / 3600:.1f} hours")
+    
+    # Provider health
+    providers = await sf.get_provider_health()
+    for p in providers:
+        print(f"{p.provider}: {p.status} ({p.latency_ms:.0f}ms)")
+    
+    # Cache statistics
+    cache = await sf.get_cache_stats()
+    print(f"Hit rate: {cache.hit_rate:.1%}")
+    print(f"L1 hits: {cache.l1_hits}")
+    print(f"L2 hits: {cache.l2_hits}")
+    print(f"Tokens saved: {cache.tokens_saved:,}")
+    
+    # Audit logs
+    logs = await sf.get_logs(limit=10)
+    for log in logs:
+        print(f"{log.timestamp}: {log.provider}/{log.model} - {log.tokens_used} tokens")
+```
+
+## Configuration
+
+### Client Options
+
+```python
+sf = SmartflowClient(
+    base_url="http://smartflow:7775",      # Proxy URL
+    api_key="your-api-key",                 # Optional API key
+    timeout=30.0,                           # Request timeout
+    management_port=7778,                   # Management API port
+    compliance_port=7777,                   # Compliance API port
+    bridge_port=3500,                       # Hybrid bridge port
+)
+```
+
+### Environment Variables
+
+```bash
+export SMARTFLOW_URL="http://your-smartflow:7775"
+export SMARTFLOW_API_KEY="your-key"
+```
+
+## API Reference
+
+### SmartflowClient Methods
+
+| Method | Description |
+|--------|-------------|
+| `chat()` | Simple chat with AI |
+| `chat_completions()` | OpenAI-compatible completions |
+| `embeddings()` | Generate text embeddings |
+| `claude_message()` | Anthropic Claude API |
+| `intelligent_scan()` | ML-powered compliance scan |
+| `check_compliance()` | Basic compliance check |
+| `get_cache_stats()` | Cache hit rates and savings |
+| `health()` | Quick health check |
+| `health_comprehensive()` | Full system health |
+| `get_logs()` | VAS audit logs |
+| `get_provider_health()` | Provider status |
+
+### SmartflowAgent Methods
+
+| Method | Description |
+|--------|-------------|
+| `chat()` | Chat with compliance scanning |
+| `clear_history()` | Reset conversation |
+| `get_history()` | Get conversation history |
+
+### SmartflowWorkflow Methods
+
+| Method | Description |
+|--------|-------------|
+| `add_step()` | Add a workflow step |
+| `set_entry()` | Set entry point |
+| `execute()` | Run the workflow |
+
+## Examples
+
+See the [examples/](./examples/) directory for more:
+
+- `simple_chat.py` - Basic chat usage
+- `compliance_check.py` - PII detection and redaction
+- `system_monitoring.py` - Health and analytics
+- `openai_drop_in.py` - OpenAI compatibility
+- `agent_example.py` - Building AI agents
+- `workflow_example.py` - Workflow orchestration
+
+## License
+
+MIT License - see [LICENSE](./LICENSE) for details.
+
+## Support
+
+- Documentation: https://docs.smartflow.ai/sdk/python
+- Issues: https://github.com/langsmart/smartflow-sdk-python/issues
+- Email: support@smartflow.ai
+
+---
+
+Built with ❤️ by [Langsmart, Inc.](https://smartflow.ai)