intent-drift 0.1.0__tar.gz

intent_drift-0.1.0/LICENSE

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

intent_drift-0.1.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: intent-drift
+Version: 0.1.0
+Summary: A production-quality library for detecting intent drift in AI-assisted development
+Author-email: Shaurya Gangrade <shauryagangrade11@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/shauryagangrade/intent-drift
+Project-URL: Repository, https://github.com/shauryagangrade/intent-drift
+Project-URL: Issues, https://github.com/shauryagangrade/intent-drift/issues
+Project-URL: Documentation, https://github.com/shauryagangrade/intent-drift#readme
+Keywords: intent-drift,ai-agents,alignment,llm,quality-assurance,evaluation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: pre-commit>=3.0.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=6.0.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=1.3.0; extra == "docs"
+Requires-Dist: myst-parser>=1.0.0; extra == "docs"
+Dynamic: license-file
+
+# Intent Alignment Engine
+
+A production-quality, open-source Python library that helps AI coding agents detect and prevent intent drift during development sessions.
+
+## 🎯 Vision
+
+AI coding agents frequently begin working toward the correct objective, but gradually shift toward solving a different problem. This engine acts as an independent "second opinion" that continuously evaluates whether the current work remains aligned with the original request.
+
+## 🔧 Features
+
+- **Evidence-Based Reasoning**: Evaluates multiple independent forms of evidence rather than simple similarity scoring
+- **Explainable Assessments**: Every conclusion is traceable to specific evidence points
+- **Pluggable Architecture**: Easy to extend with new evidence providers
+- **Timeline Tracking**: Monitor alignment drift over time
+- **Framework Agnostic**: Works with any AI coding agent (Claude Code, Codex, Gemini, etc.)
+- **Type Safe**: Full type hints with Pydantic models and dataclasses
+- **Well Tested**: Comprehensive unit and integration tests
+
+## 📦 Installation
+
+```bash
+pip install intent-drift
+```
+
+## 🚀 Quick Start
+
+```python
+from intent_alignment import IntentAlignmentEngine
+from intent_alignment.models import AlignmentContext
+
+engine = IntentAlignmentEngine()
+
+context = AlignmentContext(
+    original_goal="Reduce the application's memory usage.",
+    current_plan="Optimizing startup latency for faster initialization.",
+    execution_context={
+        "edited_files": ["main.py", "startup.py"],
+        "git_diff": "+ def optimize_startup():\n+     # ... startup optimizations\n",
+        "recent_commands": ["pip install numpy", "python -m profiler"],
+        "reasoning_summary": "Focusing on startup performance improvements"
+    }
+)
+
+report = engine.evaluate(context)
+
+print(f"Overall Alignment: {report.overall_alignment}%")
+print(f"Status: {report.status}")
+print(f"Confidence: {report.confidence}%")
+print(f"Recommendation: {report.recommendation}")
+```
+
+## 📊 Example Output
+
+```
+Intent Alignment Report
+
+Overall Alignment
+68%
+
+Status
+Moderate Drift
+
+Confidence
+89%
+
+Original Goal
+Reduce the application's memory usage.
+
+Current Goal
+Optimize startup initialization.
+
+Summary
+The current work has gradually shifted toward startup performance rather than runtime memory reduction.
+
+Evidence
+✓ Goal partially overlaps
+✓ Constraints remain satisfied
+⚠ Edited files primarily affect startup logic
+⚠ Current implementation no longer targets memory allocation
+⚠ Dependency changes favor performance over memory optimization
+
+Risk
+Additional work is unlikely to improve runtime memory usage.
+
+Recommendation
+Pause and confirm whether startup optimization was intentional before continuing.
+```
+
+## 🏗️ Architecture
+
+```
+intent-drift/
+├── src/
+│   └── intent_alignment/
+│       ├── __init__.py
+│       ├── engine.py              # Main engine class
+│       ├── models.py              # Data models (Pydantic/dataclasses)
+│       ├── parser.py              # Context parsing utilities
+│       ├── evidence/              # Evidence provider implementations
+│       │   ├── __init__.py
+│       │   ├── base.py            # Abstract EvidenceProvider
+│       │   ├── goal_provider.py
+│       │   ├── constraint_provider.py
+│       │   ├── scope_provider.py
+│       │   ├── file_graph_provider.py
+│       │   ├── dependency_provider.py
+│       │   ├── architecture_provider.py
+│       │   ├── plan_provider.py
+│       │   └── execution_provider.py
+│       ├── scoring.py             # Evidence scoring and aggregation
+│       ├── report.py              # Report generation
+│       └── api.py                 # Public API interface
+├── tests/
+│   ├── unit/
+│   └── integration/
+├── examples/
+├── docs/
+├── pyproject.toml
+└── LICENSE
+```
+
+## 🧪 Testing
+
+Run the test suite:
+
+```bash
+pytest tests/
+```
+
+## 📚 Documentation
+
+See the [docs/](docs/) directory for:
+- [Architecture Overview](docs/architecture.md)
+- [Evidence Providers](docs/evidence_providers.md)
+- [Public API Reference](docs/api.md)
+- [Extending the Engine](docs/extending.md)
+- [Contributing Guidelines](CONTRIBUTING.md)
+
+## 🤝 Contributing
+
+Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+Inspired by the challenges of intent drift in AI-assisted development and the need for transparent, explainable alignment checking mechanisms.

intent_drift-0.1.0/README.md

@@ -0,0 +1,149 @@
+# Intent Alignment Engine
+
+A production-quality, open-source Python library that helps AI coding agents detect and prevent intent drift during development sessions.
+
+## 🎯 Vision
+
+AI coding agents frequently begin working toward the correct objective, but gradually shift toward solving a different problem. This engine acts as an independent "second opinion" that continuously evaluates whether the current work remains aligned with the original request.
+
+## 🔧 Features
+
+- **Evidence-Based Reasoning**: Evaluates multiple independent forms of evidence rather than simple similarity scoring
+- **Explainable Assessments**: Every conclusion is traceable to specific evidence points
+- **Pluggable Architecture**: Easy to extend with new evidence providers
+- **Timeline Tracking**: Monitor alignment drift over time
+- **Framework Agnostic**: Works with any AI coding agent (Claude Code, Codex, Gemini, etc.)
+- **Type Safe**: Full type hints with Pydantic models and dataclasses
+- **Well Tested**: Comprehensive unit and integration tests
+
+## 📦 Installation
+
+```bash
+pip install intent-drift
+```
+
+## 🚀 Quick Start
+
+```python
+from intent_alignment import IntentAlignmentEngine
+from intent_alignment.models import AlignmentContext
+
+engine = IntentAlignmentEngine()
+
+context = AlignmentContext(
+    original_goal="Reduce the application's memory usage.",
+    current_plan="Optimizing startup latency for faster initialization.",
+    execution_context={
+        "edited_files": ["main.py", "startup.py"],
+        "git_diff": "+ def optimize_startup():\n+     # ... startup optimizations\n",
+        "recent_commands": ["pip install numpy", "python -m profiler"],
+        "reasoning_summary": "Focusing on startup performance improvements"
+    }
+)
+
+report = engine.evaluate(context)
+
+print(f"Overall Alignment: {report.overall_alignment}%")
+print(f"Status: {report.status}")
+print(f"Confidence: {report.confidence}%")
+print(f"Recommendation: {report.recommendation}")
+```
+
+## 📊 Example Output
+
+```
+Intent Alignment Report
+
+Overall Alignment
+68%
+
+Status
+Moderate Drift
+
+Confidence
+89%
+
+Original Goal
+Reduce the application's memory usage.
+
+Current Goal
+Optimize startup initialization.
+
+Summary
+The current work has gradually shifted toward startup performance rather than runtime memory reduction.
+
+Evidence
+✓ Goal partially overlaps
+✓ Constraints remain satisfied
+⚠ Edited files primarily affect startup logic
+⚠ Current implementation no longer targets memory allocation
+⚠ Dependency changes favor performance over memory optimization
+
+Risk
+Additional work is unlikely to improve runtime memory usage.
+
+Recommendation
+Pause and confirm whether startup optimization was intentional before continuing.
+```
+
+## 🏗️ Architecture
+
+```
+intent-drift/
+├── src/
+│   └── intent_alignment/
+│       ├── __init__.py
+│       ├── engine.py              # Main engine class
+│       ├── models.py              # Data models (Pydantic/dataclasses)
+│       ├── parser.py              # Context parsing utilities
+│       ├── evidence/              # Evidence provider implementations
+│       │   ├── __init__.py
+│       │   ├── base.py            # Abstract EvidenceProvider
+│       │   ├── goal_provider.py
+│       │   ├── constraint_provider.py
+│       │   ├── scope_provider.py
+│       │   ├── file_graph_provider.py
+│       │   ├── dependency_provider.py
+│       │   ├── architecture_provider.py
+│       │   ├── plan_provider.py
+│       │   └── execution_provider.py
+│       ├── scoring.py             # Evidence scoring and aggregation
+│       ├── report.py              # Report generation
+│       └── api.py                 # Public API interface
+├── tests/
+│   ├── unit/
+│   └── integration/
+├── examples/
+├── docs/
+├── pyproject.toml
+└── LICENSE
+```
+
+## 🧪 Testing
+
+Run the test suite:
+
+```bash
+pytest tests/
+```
+
+## 📚 Documentation
+
+See the [docs/](docs/) directory for:
+- [Architecture Overview](docs/architecture.md)
+- [Evidence Providers](docs/evidence_providers.md)
+- [Public API Reference](docs/api.md)
+- [Extending the Engine](docs/extending.md)
+- [Contributing Guidelines](CONTRIBUTING.md)
+
+## 🤝 Contributing
+
+Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+Inspired by the challenges of intent drift in AI-assisted development and the need for transparent, explainable alignment checking mechanisms.

intent_drift-0.1.0/pyproject.toml

@@ -0,0 +1,141 @@
+[build-system]
+requires = ["setuptools>=77.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "intent-drift"
+version = "0.1.0"
+description = "A production-quality library for detecting intent drift in AI-assisted development"
+readme = "README.md"
+authors = [
+    {name = "Shaurya Gangrade", email = "shauryagangrade11@gmail.com"}
+]
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "intent-drift",
+    "ai-agents",
+    "alignment",
+    "llm",
+    "quality-assurance",
+    "evaluation",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence"
+]
+requires-python = ">=3.10"
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "black>=23.0.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0.0",
+    "pre-commit>=3.0.0",
+]
+docs = [
+    "sphinx>=6.0.0",
+    "sphinx-rtd-theme>=1.3.0",
+    "myst-parser>=1.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/shauryagangrade/intent-drift"
+Repository = "https://github.com/shauryagangrade/intent-drift"
+Issues = "https://github.com/shauryagangrade/intent-drift/issues"
+Documentation = "https://github.com/shauryagangrade/intent-drift#readme"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = "-v --tb=short"
+
+[tool.black]
+line-length = 100
+target-version = ['py310', 'py311', 'py312']
+include = '\.pyi?$'
+extend-exclude = '''
+/(
+  # directories
+  \.git
+  | \.hg
+  | \.mypy_cache
+  | \.tox
+  | \.venv
+  | _build
+  | buck-out
+  | build
+  | dist
+)/
+'''
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E",  # pycodestyle errors
+    "W",  # pycodestyle warnings
+    "F",  # pyflakes
+    "I",  # isort
+    "B",  # flake8-bugbear
+    "C4", # flake8-comprehensions
+    "UP", # pyupgrade
+]
+ignore = [
+    "E501",  # line too long, handled by black
+    "B008",  # do not perform function calls in argument defaults
+]
+exclude = [
+    ".git",
+    ".mypy_cache",
+    ".tox",
+    ".venv",
+    "_build",
+    "buck-out",
+    "build",
+    "dist",
+]
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_untyped_decorators = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+show_error_codes = true
+
+[tool.coverage.run]
+source = ["src/intent_alignment"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:"
+]

intent_drift-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

intent_drift-0.1.0/src/intent_alignment/__init__.py

@@ -0,0 +1,16 @@
+from . import api as api
+from . import evidence as evidence_providers
+from .engine import IntentAlignmentEngine
+from .models import AlignmentContext, AlignmentReport, Evidence, ScoreComponent
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "IntentAlignmentEngine",
+    "AlignmentContext",
+    "AlignmentReport",
+    "Evidence",
+    "ScoreComponent",
+    "evidence_providers",
+    "api",
+]

intent_drift-0.1.0/src/intent_alignment/api.py

@@ -0,0 +1,4 @@
+from .engine import IntentAlignmentEngine
+from .models import AlignmentReport
+
+__all__ = ["AlignmentReport", "IntentAlignmentEngine"]

intent_drift-0.1.0/src/intent_alignment/engine.py

@@ -0,0 +1,121 @@
+from typing import Any
+
+from .evidence import EvidenceProvider
+from .models import AlignmentContext, AlignmentReport
+
+
+class IntentAlignmentEngine:
+    """Main engine for intent alignment analysis."""
+
+    def __init__(self):
+        """Initialize the engine with default evidence providers."""
+        self.providers: list[EvidenceProvider] = []
+        self._register_default_providers()
+
+    def _register_default_providers(self) -> None:
+        """Register the default set of evidence providers."""
+        # Import providers here to avoid circular imports
+        from .evidence.providers import (
+            ArchitectureProvider,
+            ConstraintProvider,
+            DependencyProvider,
+            ExecutionProvider,
+            FileGraphProvider,
+            GoalProvider,
+            ProblematicFindingsProvider,
+            RequirementCoverageProvider,
+            ScopeProvider,
+        )
+
+        self.providers = [
+            GoalProvider(),
+            ConstraintProvider(),
+            ScopeProvider(),
+            ArchitectureProvider(),
+            ExecutionProvider(),
+            FileGraphProvider(),
+            DependencyProvider(),
+            RequirementCoverageProvider(),
+            ProblematicFindingsProvider(),
+        ]
+
+    def add_provider(self, provider: EvidenceProvider) -> None:
+        """Register an evidence provider to use during evaluation."""
+        self.providers.append(provider)
+
+    def evaluate(self, context: AlignmentContext) -> AlignmentReport:
+        """
+        Analyze the alignment between original goal and current implementation.
+
+        Args:
+            context: Alignment context containing goal, plan, and execution data.
+                Accepts either an :class:`AlignmentContext` or a plain dict with
+                the same three keys. Providers always receive a plain dict view.
+
+        Returns:
+            Alignment report with assessment results
+        """
+        # Accept a plain dict for convenience (e.g. example scripts and tests
+        # that construct context inline) and normalize to AlignmentContext.
+        context_dict: dict[str, Any]
+        if isinstance(context, AlignmentContext):
+            context_dict = {
+                "original_goal": context.original_goal,
+                "current_plan": context.current_plan,
+                "execution_context": context.execution_context,
+            }
+        elif isinstance(context, dict):
+            context_dict = {
+                "original_goal": context.get("original_goal", {}),
+                "current_plan": context.get("current_plan", {}),
+                "execution_context": context.get("execution_context", {}),
+            }
+        else:
+            raise TypeError(
+                "evaluate() expects an AlignmentContext or a dict with "
+                "'original_goal', 'current_plan', 'execution_context' keys."
+            )
+
+        # Collect evidence from all registered providers
+        all_evidence = []
+        for provider in self.providers:
+            all_evidence.extend(provider.collect(context_dict))
+
+        # Import scoring functions
+        from .scoring import compute_weighted_score
+        from .utils import (
+            compute_confidence,
+            determine_status,
+            generate_recommendation,
+            generate_risk_assessment,
+            generate_summary,
+        )
+
+        # Compute weighted score and alignment breakdown
+        weighted_score, component_scores = compute_weighted_score(all_evidence, self.providers)
+
+        # Calculate confidence based on evidence consistency and confidence scores
+        confidence = compute_confidence(all_evidence)
+
+        # Determine status based on alignment score
+        status = determine_status(weighted_score)
+
+        # Generate report components
+        summary = generate_summary(component_scores, weighted_score)
+        risk = generate_risk_assessment(all_evidence, component_scores)
+        recommendation = generate_recommendation(component_scores, weighted_score)
+
+        # Create the alignment report
+        report = AlignmentReport(
+            overall_alignment=weighted_score,
+            confidence=confidence,
+            status=status,
+            breakdown=component_scores,
+            summary=summary,
+            evidence=all_evidence,
+            risk=risk,
+            recommendation=recommendation,
+            timeline=[],  # Timeline would be populated with historical data in a real implementation
+        )
+
+        return report

intent_drift-0.1.0/src/intent_alignment/evidence/__init__.py

@@ -0,0 +1,27 @@
+"""Evidence providers package - exports all available providers."""
+
+from ..models import Evidence
+from .base import EvidenceProvider
+from .providers.architecture_provider import ArchitectureProvider
+from .providers.constraint_provider import ConstraintProvider
+from .providers.dependency_provider import DependencyProvider
+from .providers.execution_provider import ExecutionProvider
+from .providers.file_graph_provider import FileGraphProvider
+from .providers.goal_provider import GoalProvider
+from .providers.problematic_findings_provider import ProblematicFindingsProvider
+from .providers.requirement_coverage_provider import RequirementCoverageProvider
+from .providers.scope_provider import ScopeProvider
+
+__all__ = [
+    "EvidenceProvider",
+    "Evidence",
+    "GoalProvider",
+    "ConstraintProvider",
+    "ScopeProvider",
+    "ArchitectureProvider",
+    "ExecutionProvider",
+    "FileGraphProvider",
+    "DependencyProvider",
+    "RequirementCoverageProvider",
+    "ProblematicFindingsProvider",
+]