| Name | aisentinel-sdk JSON |
| Version |
0.1.3
JSON |
| download |
| home_page | None |
| Summary | AISentinel Python SDK for AI governance and security |
| upload_time | 2025-10-21 22:22:11 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
ai
governance
security
sdk
agent
audit
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# AISentinel Python SDK
[](https://pypi.org/project/aisentinel-sdk/)
[](https://pypi.org/project/aisentinel-sdk/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/mfifth/aisentinel-python-sdk/actions/workflows/ci.yml)
The official Python SDK for AISentinel - zero-latency governance for AI agents.
## Features
- **Preflight Checks**: Validate agent actions before execution
- **Offline Support**: Continue operating when network connectivity is lost
- **Local Caching**: Cache decisions and rulepacks for improved performance
- **Multi-tenant**: Support for multiple organizations and environments
- **Thread-safe**: Designed for concurrent agent deployments
- **Embedded Database**: SQLite-based storage for audit logs and metrics
## Installation
```bash
pip install aisentinel-sdk
```
## Quick Start
```python
from aisentinel import Governor
# Initialize the governor
governor = Governor(
base_url="https://aisentinel.fly.dev",
token="your-api-token"
)
# Check if an action is allowed
candidate = {
"tool": "web_search",
"args": {"query": "python tutorials"}
}
state = {"user_id": "user123", "session_id": "sess456"}
decision = governor.preflight(candidate, state)
if decision["allowed"]:
# Execute your tool
result = perform_web_search(candidate["args"]["query"])
print(f"Search results: {result}")
else:
print(f"Blocked: {decision['reasons']}")
```
## Advanced Usage
### Offline Mode
The SDK automatically handles network interruptions and queues operations for later execution:
```python
# The governor automatically detects connectivity and handles offline scenarios
governor = Governor(token="your-token")
# If offline, decisions are cached or deferred
decision = governor.preflight(candidate, state)
```
### Multi-tenant Support
```python
# Configure multiple tenants
governor = Governor(token="default-token")
# Use tenant-specific tokens
decision = governor.preflight(candidate, state, tenant_id="tenant-123")
```
### Rulepack Management
```python
# Fetch and cache rulepacks
rulepack = governor.fetch_rulepack("security-rules", version="1.2.0")
print(f"Rulepack version: {rulepack['version']}")
```
### Guarded Execution
```python
# Automatically execute allowed actions, return alternatives for blocked ones
def search_web(query):
return {"results": ["result1", "result2"]}
result = governor.guarded_execute(
search_web,
{"tool": "web_search", "args": {"query": "python"}},
{"user_id": "user123"}
)
if "error" in result:
print(f"Action blocked: {result['error']}")
else:
print(f"Results: {result}")
```
## Configuration
Configure the SDK via environment variables, config files, or programmatically:
```bash
# Environment variables
export AISENTINEL_BASE_URL="https://aisentinel.fly.dev"
export AISENTINEL_TOKEN="your-token"
export AISENTINEL_CACHE_TTL_SECONDS="600"
```
```python
# Programmatic configuration
from aisentinel import Governor, SDKConfig
config = SDKConfig.load(
overrides={
"base_url": "https://aisentinel.fly.dev",
"token": "your-token",
"offline_mode_enabled": True
}
)
governor = Governor(config=config)
```
### Config File
Create a `aisentinel.json` file:
```json
{
"base_url": "https://aisentinel.fly.dev",
"token": "your-token",
"cache_ttl_seconds": 300,
"offline_mode_enabled": true,
"tenants": {
"tenant-1": {
"token": "tenant-specific-token"
}
}
}
```
## Integration Examples
### LangChain Integration
```python
from langchain.tools import Tool
from aisentinel import Governor
governor = Governor(token="your-token")
def guarded_web_search(query: str) -> str:
candidate = {"tool": "web_search", "args": {"query": query}}
state = {"user_id": "agent123"}
decision = governor.preflight(candidate, state)
if not decision["allowed"]:
return f"Search blocked: {decision['reasons'][0]}"
# Perform actual search
return perform_search(query)
search_tool = Tool(
name="WebSearch",
description="Search the web for information",
func=guarded_web_search
)
```
### CrewAI Integration
```python
from crewai import Agent, Task
from aisentinel import Governor
governor = Governor(token="your-token")
class GovernedAgent(Agent):
def __init__(self, **kwargs):
super().__init__(**kwargs)
self.governor = governor
def execute_task(self, task: Task):
# Check if task execution is allowed
candidate = {
"tool": "agent_execution",
"args": {"task": task.description}
}
state = {"agent_id": self.id}
decision = self.governor.preflight(candidate, state)
if not decision["allowed"]:
raise ValueError(f"Task execution blocked: {decision['reasons']}")
return super().execute_task(task)
```
## API Reference
### Governor
The main SDK class for AISentinel governance.
#### Methods
- `preflight(candidate, state, tenant_id=None)` - Check if an action is allowed
- `guarded_execute(func, candidate, state, tenant_id=None)` - Execute function if allowed
- `fetch_rulepack(rulepack_id, version=None)` - Fetch rulepack with caching
- `get_cache_metrics()` - Get cache performance metrics
### SDKConfig
Configuration management for the SDK.
#### Methods
- `SDKConfig.load(file_path=None, env_prefix="AISENTINEL_", overrides=None)` - Load configuration
## Development
```bash
# Clone the repository
git clone https://github.com/aisentinel/aisentinel-python-sdk.git
cd aisentinel-python-sdk
# Install development dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Run linting
black aisentinel/
isort aisentinel/
mypy aisentinel/
```
## Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Support
- 📖 [Documentation](https://aisentinel.fly.dev/docs)
- 🐛 [Issue Tracker](https://github.com/mfifth/aisentinel-python-sdk/issues)
Raw data
{
"_id": null,
"home_page": null,
"name": "aisentinel-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "AISentinel Team <team@aisentinel.info>",
"keywords": "ai, governance, security, sdk, agent, audit",
"author": null,
"author_email": "AISentinel Team <team@aisentinel.info>",
"download_url": "https://files.pythonhosted.org/packages/fc/a7/9ea68b3b05eed8ada0a03768186b7028cb416c00288ba37233c269421179/aisentinel_sdk-0.1.3.tar.gz",
"platform": null,
"description": "# AISentinel Python SDK\n\n[](https://pypi.org/project/aisentinel-sdk/)\n[](https://pypi.org/project/aisentinel-sdk/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/mfifth/aisentinel-python-sdk/actions/workflows/ci.yml)\n\nThe official Python SDK for AISentinel - zero-latency governance for AI agents.\n\n## Features\n\n- **Preflight Checks**: Validate agent actions before execution\n- **Offline Support**: Continue operating when network connectivity is lost\n- **Local Caching**: Cache decisions and rulepacks for improved performance\n- **Multi-tenant**: Support for multiple organizations and environments\n- **Thread-safe**: Designed for concurrent agent deployments\n- **Embedded Database**: SQLite-based storage for audit logs and metrics\n\n## Installation\n\n```bash\npip install aisentinel-sdk\n```\n\n## Quick Start\n\n```python\nfrom aisentinel import Governor\n\n# Initialize the governor\ngovernor = Governor(\n base_url=\"https://aisentinel.fly.dev\",\n token=\"your-api-token\"\n)\n\n# Check if an action is allowed\ncandidate = {\n \"tool\": \"web_search\",\n \"args\": {\"query\": \"python tutorials\"}\n}\n\nstate = {\"user_id\": \"user123\", \"session_id\": \"sess456\"}\n\ndecision = governor.preflight(candidate, state)\n\nif decision[\"allowed\"]:\n # Execute your tool\n result = perform_web_search(candidate[\"args\"][\"query\"])\n print(f\"Search results: {result}\")\nelse:\n print(f\"Blocked: {decision['reasons']}\")\n```\n\n## Advanced Usage\n\n### Offline Mode\n\nThe SDK automatically handles network interruptions and queues operations for later execution:\n\n```python\n# The governor automatically detects connectivity and handles offline scenarios\ngovernor = Governor(token=\"your-token\")\n\n# If offline, decisions are cached or deferred\ndecision = governor.preflight(candidate, state)\n```\n\n### Multi-tenant Support\n\n```python\n# Configure multiple tenants\ngovernor = Governor(token=\"default-token\")\n\n# Use tenant-specific tokens\ndecision = governor.preflight(candidate, state, tenant_id=\"tenant-123\")\n```\n\n### Rulepack Management\n\n```python\n# Fetch and cache rulepacks\nrulepack = governor.fetch_rulepack(\"security-rules\", version=\"1.2.0\")\nprint(f\"Rulepack version: {rulepack['version']}\")\n```\n\n### Guarded Execution\n\n```python\n# Automatically execute allowed actions, return alternatives for blocked ones\ndef search_web(query):\n return {\"results\": [\"result1\", \"result2\"]}\n\nresult = governor.guarded_execute(\n search_web,\n {\"tool\": \"web_search\", \"args\": {\"query\": \"python\"}},\n {\"user_id\": \"user123\"}\n)\n\nif \"error\" in result:\n print(f\"Action blocked: {result['error']}\")\nelse:\n print(f\"Results: {result}\")\n```\n\n## Configuration\n\nConfigure the SDK via environment variables, config files, or programmatically:\n\n```bash\n# Environment variables\nexport AISENTINEL_BASE_URL=\"https://aisentinel.fly.dev\"\nexport AISENTINEL_TOKEN=\"your-token\"\nexport AISENTINEL_CACHE_TTL_SECONDS=\"600\"\n```\n\n```python\n# Programmatic configuration\nfrom aisentinel import Governor, SDKConfig\n\nconfig = SDKConfig.load(\n overrides={\n \"base_url\": \"https://aisentinel.fly.dev\",\n \"token\": \"your-token\",\n \"offline_mode_enabled\": True\n }\n)\n\ngovernor = Governor(config=config)\n```\n\n### Config File\n\nCreate a `aisentinel.json` file:\n\n```json\n{\n \"base_url\": \"https://aisentinel.fly.dev\",\n \"token\": \"your-token\",\n \"cache_ttl_seconds\": 300,\n \"offline_mode_enabled\": true,\n \"tenants\": {\n \"tenant-1\": {\n \"token\": \"tenant-specific-token\"\n }\n }\n}\n```\n\n## Integration Examples\n\n### LangChain Integration\n\n```python\nfrom langchain.tools import Tool\nfrom aisentinel import Governor\n\ngovernor = Governor(token=\"your-token\")\n\ndef guarded_web_search(query: str) -> str:\n candidate = {\"tool\": \"web_search\", \"args\": {\"query\": query}}\n state = {\"user_id\": \"agent123\"}\n\n decision = governor.preflight(candidate, state)\n if not decision[\"allowed\"]:\n return f\"Search blocked: {decision['reasons'][0]}\"\n\n # Perform actual search\n return perform_search(query)\n\nsearch_tool = Tool(\n name=\"WebSearch\",\n description=\"Search the web for information\",\n func=guarded_web_search\n)\n```\n\n### CrewAI Integration\n\n```python\nfrom crewai import Agent, Task\nfrom aisentinel import Governor\n\ngovernor = Governor(token=\"your-token\")\n\nclass GovernedAgent(Agent):\n def __init__(self, **kwargs):\n super().__init__(**kwargs)\n self.governor = governor\n\n def execute_task(self, task: Task):\n # Check if task execution is allowed\n candidate = {\n \"tool\": \"agent_execution\",\n \"args\": {\"task\": task.description}\n }\n state = {\"agent_id\": self.id}\n\n decision = self.governor.preflight(candidate, state)\n if not decision[\"allowed\"]:\n raise ValueError(f\"Task execution blocked: {decision['reasons']}\")\n\n return super().execute_task(task)\n```\n\n## API Reference\n\n### Governor\n\nThe main SDK class for AISentinel governance.\n\n#### Methods\n\n- `preflight(candidate, state, tenant_id=None)` - Check if an action is allowed\n- `guarded_execute(func, candidate, state, tenant_id=None)` - Execute function if allowed\n- `fetch_rulepack(rulepack_id, version=None)` - Fetch rulepack with caching\n- `get_cache_metrics()` - Get cache performance metrics\n\n### SDKConfig\n\nConfiguration management for the SDK.\n\n#### Methods\n\n- `SDKConfig.load(file_path=None, env_prefix=\"AISENTINEL_\", overrides=None)` - Load configuration\n\n## Development\n\n```bash\n# Clone the repository\ngit clone https://github.com/aisentinel/aisentinel-python-sdk.git\ncd aisentinel-python-sdk\n\n# Install development dependencies\npip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Run linting\nblack aisentinel/\nisort aisentinel/\nmypy aisentinel/\n```\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\n- \ud83d\udcd6 [Documentation](https://aisentinel.fly.dev/docs)\n- \ud83d\udc1b [Issue Tracker](https://github.com/mfifth/aisentinel-python-sdk/issues)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "AISentinel Python SDK for AI governance and security",
"version": "0.1.3",
"project_urls": {
"Changelog": "https://github.com/aisentinel/aisentinel-python-sdk/blob/main/CHANGELOG.md",
"Documentation": "https://docs.aisentinel.ai/python",
"Homepage": "https://aisentinel.ai",
"Issues": "https://github.com/aisentinel/aisentinel-python-sdk/issues",
"Repository": "https://github.com/aisentinel/aisentinel-python-sdk"
},
"split_keywords": [
"ai",
" governance",
" security",
" sdk",
" agent",
" audit"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "45484c633654673529c4d756b2aa5d97dd242156cacf5db2c842017ab8022e2c",
"md5": "47e096ec78a7e3c1637b199e255b094b",
"sha256": "d72d7888e5f531046375f805f2bcbc0f856693e05852d1e6c71f43e93e74283a"
},
"downloads": -1,
"filename": "aisentinel_sdk-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "47e096ec78a7e3c1637b199e255b094b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 14449,
"upload_time": "2025-10-21T22:22:10",
"upload_time_iso_8601": "2025-10-21T22:22:10.137732Z",
"url": "https://files.pythonhosted.org/packages/45/48/4c633654673529c4d756b2aa5d97dd242156cacf5db2c842017ab8022e2c/aisentinel_sdk-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "fca79ea68b3b05eed8ada0a03768186b7028cb416c00288ba37233c269421179",
"md5": "f307c6b3aa8d6502dfab2f72bbe458cf",
"sha256": "11d4ae71a89189f9ae1389d82ba6c526128da27ff36926662383fddff6cb54dd"
},
"downloads": -1,
"filename": "aisentinel_sdk-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "f307c6b3aa8d6502dfab2f72bbe458cf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 16232,
"upload_time": "2025-10-21T22:22:11",
"upload_time_iso_8601": "2025-10-21T22:22:11.127911Z",
"url": "https://files.pythonhosted.org/packages/fc/a7/9ea68b3b05eed8ada0a03768186b7028cb416c00288ba37233c269421179/aisentinel_sdk-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-21 22:22:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aisentinel",
"github_project": "aisentinel-python-sdk",
"github_not_found": true,
"lcname": "aisentinel-sdk"
}
