# IntentGuard
IntentGuard is a Python library for verifying code properties using natural language assertions. It seamlessly integrates with popular testing frameworks like pytest and unittest, allowing developers to express complex code expectations in plain English while maintaining the structure of traditional test suites.
## Why IntentGuard?
Traditional testing approaches often require extensive boilerplate code to verify complex properties. IntentGuard bridges this gap by allowing developers to express sophisticated test cases in natural language, particularly useful for scenarios where writing conventional test code would be impractical or time-consuming.
### Key Features
1. **Natural Language Test Cases:** Write test assertions in plain English.
2. **Framework Integration:** Works with pytest, unittest, and other testing frameworks.
3. **Deterministic Results:** Uses a voting mechanism and controlled sampling for consistent results.
4. **Flexible Verification:** Test complex code properties that would be difficult to verify traditionally.
5. **Detailed Failure Explanations:** Provides clear explanations when assertions fail, helping you understand the root cause and fix issues faster.
6. **Efficient Result Caching:** Caches assertion results to avoid redundant processing and speed up test execution.
## When to Use IntentGuard
IntentGuard is designed for scenarios where traditional test implementation would be impractical or require excessive code. For example:
```python
# Traditional approach would require:
# 1. Iterating through all methods
# 2. Parsing AST for each method
# 3. Checking exception handling patterns
# 4. Verifying logging calls
# 5. Maintaining complex test code
# With IntentGuard:
def test_error_handling():
ig.assert_code(
"All methods in {module} should use the custom ErrorHandler class for exception management, and log errors before re-raising them",
{"module": my_critical_module}
)
# Another example - checking documentation consistency
def test_docstring_completeness():
ig.assert_code(
"All public methods in {module} should have docstrings that include Parameters, Returns, and Examples sections",
{"module": my_api_module}
)
```
## How It Works
### Deterministic Testing
IntentGuard employs several mechanisms to ensure consistent and reliable results:
1. **Voting Mechanism**: Each assertion is evaluated multiple times (configurable through `num_evaluations`), and the majority result is used
2. **Temperature Control**: Uses low temperature for LLM sampling to reduce randomness
3. **Structured Prompts**: Converts natural language assertions into structured prompts for consistent LLM interpretation
```python
# Configure determinism settings
options = IntentGuardOptions(
num_evaluations=5, # Number of evaluations per assertion
)
```
## Installation
```bash
pip install intentguard
```
## Basic Usage
### With pytest
```python
import intentguard as ig
def test_code_properties():
guard = ig.IntentGuard()
# Test code organization
guard.assert_code(
"Classes in {module} should follow the Single Responsibility Principle",
{"module": my_module}
)
# Test security practices
guard.assert_code(
"All database queries in {module} should be parameterized to prevent SQL injection",
{"module": db_module}
)
```
### With unittest
```python
import unittest
import intentguard as ig
class TestCodeQuality(unittest.TestCase):
def setUp(self):
self.guard = ig.IntentGuard()
def test_error_handling(self):
self.guard.assert_code(
"All API endpoints in {module} should have proper input validation",
{"module": api_module}
)
```
## Advanced Usage
### Custom Evaluation Options
```python
import intentguard as ig
options = ig.IntentGuardOptions(
num_evaluations=7, # Increase number of evaluations
model="gpt-4o-2024-08-06", # Use a more capable model
)
guard = ig.IntentGuard(options)
```
## Contributing
Contributions are welcome! Check out our [roadmap](ROADMAP.md) for planned features.
## License
[MIT License](LICENSE)
## Acknowledgements
This project uses [LiteLLM](https://github.com/BerriAI/litellm) for LLM integration.
---
IntentGuard is designed to complement, not replace, traditional testing approaches. It's most effective when used for complex code properties that are difficult to verify through conventional means.
Raw data
{
"_id": null,
"home_page": "https://github.com/kdunee/intentguard",
"name": "intentguard",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "testing, pytest, unittest, ai-testing, llm, code-verification, natural-language, test-automation, code-quality, language-models",
"author": "Kosma Dunikowski",
"author_email": "kosmadunikowski@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/3d/16/b38cba935a4a879e469c96d23eb3cbe0bdda7d66ac7b879e2d8882d8cfb0/intentguard-1.3.1.tar.gz",
"platform": null,
"description": "# IntentGuard\n\n\n\n\n\n\n\n\nIntentGuard is a Python library for verifying code properties using natural language assertions. It seamlessly integrates with popular testing frameworks like pytest and unittest, allowing developers to express complex code expectations in plain English while maintaining the structure of traditional test suites.\n\n## Why IntentGuard?\n\nTraditional testing approaches often require extensive boilerplate code to verify complex properties. IntentGuard bridges this gap by allowing developers to express sophisticated test cases in natural language, particularly useful for scenarios where writing conventional test code would be impractical or time-consuming.\n\n### Key Features\n\n1. **Natural Language Test Cases:** Write test assertions in plain English.\n2. **Framework Integration:** Works with pytest, unittest, and other testing frameworks.\n3. **Deterministic Results:** Uses a voting mechanism and controlled sampling for consistent results.\n4. **Flexible Verification:** Test complex code properties that would be difficult to verify traditionally.\n5. **Detailed Failure Explanations:** Provides clear explanations when assertions fail, helping you understand the root cause and fix issues faster.\n6. **Efficient Result Caching:** Caches assertion results to avoid redundant processing and speed up test execution.\n\n## When to Use IntentGuard\n\nIntentGuard is designed for scenarios where traditional test implementation would be impractical or require excessive code. For example:\n\n```python\n# Traditional approach would require:\n# 1. Iterating through all methods\n# 2. Parsing AST for each method\n# 3. Checking exception handling patterns\n# 4. Verifying logging calls\n# 5. Maintaining complex test code\n\n# With IntentGuard:\ndef test_error_handling():\n ig.assert_code(\n \"All methods in {module} should use the custom ErrorHandler class for exception management, and log errors before re-raising them\",\n {\"module\": my_critical_module}\n )\n\n# Another example - checking documentation consistency\ndef test_docstring_completeness():\n ig.assert_code(\n \"All public methods in {module} should have docstrings that include Parameters, Returns, and Examples sections\",\n {\"module\": my_api_module}\n )\n```\n\n## How It Works\n\n### Deterministic Testing\n\nIntentGuard employs several mechanisms to ensure consistent and reliable results:\n\n1. **Voting Mechanism**: Each assertion is evaluated multiple times (configurable through `num_evaluations`), and the majority result is used\n2. **Temperature Control**: Uses low temperature for LLM sampling to reduce randomness\n3. **Structured Prompts**: Converts natural language assertions into structured prompts for consistent LLM interpretation\n\n```python\n# Configure determinism settings\noptions = IntentGuardOptions(\n num_evaluations=5, # Number of evaluations per assertion\n)\n```\n\n## Installation\n\n```bash\npip install intentguard\n```\n\n## Basic Usage\n\n### With pytest\n\n```python\nimport intentguard as ig\n\ndef test_code_properties():\n guard = ig.IntentGuard()\n \n # Test code organization\n guard.assert_code(\n \"Classes in {module} should follow the Single Responsibility Principle\",\n {\"module\": my_module}\n )\n \n # Test security practices\n guard.assert_code(\n \"All database queries in {module} should be parameterized to prevent SQL injection\",\n {\"module\": db_module}\n )\n```\n\n### With unittest\n\n```python\nimport unittest\nimport intentguard as ig\n\nclass TestCodeQuality(unittest.TestCase):\n def setUp(self):\n self.guard = ig.IntentGuard()\n \n def test_error_handling(self):\n self.guard.assert_code(\n \"All API endpoints in {module} should have proper input validation\",\n {\"module\": api_module}\n )\n```\n\n## Advanced Usage\n\n### Custom Evaluation Options\n\n```python\nimport intentguard as ig\n\noptions = ig.IntentGuardOptions(\n num_evaluations=7, # Increase number of evaluations\n model=\"gpt-4o-2024-08-06\", # Use a more capable model\n)\n\nguard = ig.IntentGuard(options)\n```\n\n## Contributing\n\nContributions are welcome! Check out our [roadmap](ROADMAP.md) for planned features.\n\n## License\n\n[MIT License](LICENSE)\n\n## Acknowledgements\n\nThis project uses [LiteLLM](https://github.com/BerriAI/litellm) for LLM integration.\n\n---\n\nIntentGuard is designed to complement, not replace, traditional testing approaches. It's most effective when used for complex code properties that are difficult to verify through conventional means.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python library for verifying code properties using natural language assertions.",
"version": "1.3.1",
"project_urls": {
"Homepage": "https://github.com/kdunee/intentguard"
},
"split_keywords": [
"testing",
" pytest",
" unittest",
" ai-testing",
" llm",
" code-verification",
" natural-language",
" test-automation",
" code-quality",
" language-models"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1ee67aaf799d7f4118cee8f46755c097864d9f96ca6608f8f8071da57c0f0601",
"md5": "840ec196fdd0bb20e23efb4f5b42a90b",
"sha256": "113f99153b2eb7adcf577916b0cf67d0cf36ce17d41dd6d98cf12a5ae31b15ef"
},
"downloads": -1,
"filename": "intentguard-1.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "840ec196fdd0bb20e23efb4f5b42a90b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 9614,
"upload_time": "2024-11-19T20:21:34",
"upload_time_iso_8601": "2024-11-19T20:21:34.807617Z",
"url": "https://files.pythonhosted.org/packages/1e/e6/7aaf799d7f4118cee8f46755c097864d9f96ca6608f8f8071da57c0f0601/intentguard-1.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3d16b38cba935a4a879e469c96d23eb3cbe0bdda7d66ac7b879e2d8882d8cfb0",
"md5": "f412ccc0bf698e368c81389edebedb3e",
"sha256": "3d2cfaad2ed1424386101a269ba444271df7a2675c8bba24513384337b41fff6"
},
"downloads": -1,
"filename": "intentguard-1.3.1.tar.gz",
"has_sig": false,
"md5_digest": "f412ccc0bf698e368c81389edebedb3e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 9488,
"upload_time": "2024-11-19T20:21:36",
"upload_time_iso_8601": "2024-11-19T20:21:36.381380Z",
"url": "https://files.pythonhosted.org/packages/3d/16/b38cba935a4a879e469c96d23eb3cbe0bdda7d66ac7b879e2d8882d8cfb0/intentguard-1.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-19 20:21:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kdunee",
"github_project": "intentguard",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "intentguard"
}
JSON
