vcase-auto-context 0.1.0__tar.gz

vcase_auto_context-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: vcase-auto-context
+Version: 0.1.0
+Summary: Version-Constrained API Specification Engine (VCASE)
+Author-email: Developer <developer@example.com>
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: uvicorn[standard]>=0.30.6
+Requires-Dist: httpx>=0.27.2
+Requires-Dist: pydantic>=2.9.2
+Requires-Dist: pydantic-settings>=2.5.2
+Requires-Dist: cachetools>=5.5.0
+Requires-Dist: python-dotenv>=1.0.1
+
+# Version-Constrained API Specification Engine
+
+A deterministic, version-aware knowledge streaming infrastructure for Large Language Models (LLMs). 
+
+## Why does this exist?
+When LLMs generate code, they frequently rely on outdated training data or hallucinate API signatures for newer libraries. Traditional Retrieval-Augmented Generation (RAG) is often static and misses critical version-specific nuances or architectural constraints.
+
+This engine replaces static RAG with a **five-layer defense system**. It dynamically extracts exact project dependencies, resolves them to specific versions, and streams deterministic API contracts and interaction rules directly into the LLM's system prompt.
+
+## Core Features
+- **Zero-Hallucination API Contracts:** Injects exact function signatures based on the specific version of the library you are using.
+- **Architectural Guardrails:** Enforces complex interaction patterns (e.g., "Temporal workflows cannot be executed directly inside FastAPI route handlers").
+- **Language Agnostic Architecture:** Built on a provider interface allowing expansion beyond Python to Node, Rust, Go, etc.
+
+## Resolution Architecture
+
+The engine uses a strict **Tiered Fallback Strategy** to guarantee dependency accuracy before building the specification:
+
+1. **Tier 1: Lock Files (Highest Priority)**
+   * Parses deterministic manifests (e.g., `poetry.lock`) to extract exact, pinned versions.
+2. **Tier 2: Declaration Files**
+   * Parses abstract declarations (e.g., `pyproject.toml`, `requirements.txt`).
+   * Connects to ecosystem registries (like PyPI) to resolve loose constraints (like `^1.2.0`) to the latest compatible version.
+3. **Tier 3: Containerized Introspection (Future)**
+   * Sandboxed subprocess execution (`pip freeze`, `npm ls`) for deeply nested or hidden dependencies.
+
+## Component Flow
+
+1. **`TechnologyDetector`**: Scans the repository or user prompt against a curated list of ~180 production-grade technologies to identify the stack.
+2. **`DependencyResolver`**: Orchestrates the tiered fallback logic across all available Ecosystem Providers.
+3. **`EcosystemProvider`** (e.g., `PythonProvider`): Parses the specific manifest syntax of the language.
+4. **`PypiClient`**: Makes async, defensive network requests to fetch current metadata and documentation sources.
+5. **`SpecBuilder`**: Assembles the final, non-negotiable System Prompt block, formatting parameters, return types, and deprecation warnings.
+
+## Usage / Integration
+
+Currently, the engine provides internal APIs to assemble the System Prompt constraints. 
+
+```python
+# Example Internal Flow (Pseudocode)
+from src.service.resolver import DependencyResolver
+from src.service.spec_builder import SpecBuilder
+
+# 1. Resolve exact versions used in the project
+resolver = DependencyResolver(providers=[PythonProvider(...)])
+resolved_deps = await resolver.resolve(Path("./my_project"))
+
+# 2. Fetch the metadata/signatures internally 
+# ...
+
+# 3. Build the strict constraints for the LLM
+builder = SpecBuilder()
+system_instruction = builder.build_system_prompt(api_indexes, patterns)
+
+print(system_instruction) 
+# Outputs: 
+# ## litellm 1.40.0
+# - completion(model: str, messages: list) -> ModelResponse
+# ⚠ PATTERN: fastapi + temporalio
+# Rule [NO_WORKFLOW_IN_HANDLER]: Workflows must run in workers.
+```
+
+## Contributing
+When adding a new Ecosystem Provider (e.g., NodeProvider), you must adhere to the asynchronous contract defined in src/providers/base.py. All registry interactions must be defensive and non-blocking.

vcase_auto_context-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=61.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vcase-auto-context"
+version = "0.1.0"
+authors = [
+    { name = "Developer", email = "developer@example.com" }
+]
+description = "Version-Constrained API Specification Engine (VCASE)"
+readme = "readme.md"
+requires-python = ">=3.8"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.30.6",
+    "httpx>=0.27.2",
+    "pydantic>=2.9.2",
+    "pydantic-settings>=2.5.2",
+    "cachetools>=5.5.0",
+    "python-dotenv>=1.0.1",
+]
+
+[project.scripts]
+vcase = "vcase.cli:main"
+
+[tool.setuptools]
+packages = ["vcase", "vcase.api", "vcase.providers", "vcase.routers", "vcase.service", "vcase.validator", "vcase.validator.adapters", "vcase.validator.core", "vcase.validator.specs"]
+
+[tool.setuptools.package-data]
+vcase = ["validator/specs/*.json"]

vcase_auto_context-0.1.0/readme.md

@@ -0,0 +1,64 @@
+# Version-Constrained API Specification Engine
+
+A deterministic, version-aware knowledge streaming infrastructure for Large Language Models (LLMs). 
+
+## Why does this exist?
+When LLMs generate code, they frequently rely on outdated training data or hallucinate API signatures for newer libraries. Traditional Retrieval-Augmented Generation (RAG) is often static and misses critical version-specific nuances or architectural constraints.
+
+This engine replaces static RAG with a **five-layer defense system**. It dynamically extracts exact project dependencies, resolves them to specific versions, and streams deterministic API contracts and interaction rules directly into the LLM's system prompt.
+
+## Core Features
+- **Zero-Hallucination API Contracts:** Injects exact function signatures based on the specific version of the library you are using.
+- **Architectural Guardrails:** Enforces complex interaction patterns (e.g., "Temporal workflows cannot be executed directly inside FastAPI route handlers").
+- **Language Agnostic Architecture:** Built on a provider interface allowing expansion beyond Python to Node, Rust, Go, etc.
+
+## Resolution Architecture
+
+The engine uses a strict **Tiered Fallback Strategy** to guarantee dependency accuracy before building the specification:
+
+1. **Tier 1: Lock Files (Highest Priority)**
+   * Parses deterministic manifests (e.g., `poetry.lock`) to extract exact, pinned versions.
+2. **Tier 2: Declaration Files**
+   * Parses abstract declarations (e.g., `pyproject.toml`, `requirements.txt`).
+   * Connects to ecosystem registries (like PyPI) to resolve loose constraints (like `^1.2.0`) to the latest compatible version.
+3. **Tier 3: Containerized Introspection (Future)**
+   * Sandboxed subprocess execution (`pip freeze`, `npm ls`) for deeply nested or hidden dependencies.
+
+## Component Flow
+
+1. **`TechnologyDetector`**: Scans the repository or user prompt against a curated list of ~180 production-grade technologies to identify the stack.
+2. **`DependencyResolver`**: Orchestrates the tiered fallback logic across all available Ecosystem Providers.
+3. **`EcosystemProvider`** (e.g., `PythonProvider`): Parses the specific manifest syntax of the language.
+4. **`PypiClient`**: Makes async, defensive network requests to fetch current metadata and documentation sources.
+5. **`SpecBuilder`**: Assembles the final, non-negotiable System Prompt block, formatting parameters, return types, and deprecation warnings.
+
+## Usage / Integration
+
+Currently, the engine provides internal APIs to assemble the System Prompt constraints. 
+
+```python
+# Example Internal Flow (Pseudocode)
+from src.service.resolver import DependencyResolver
+from src.service.spec_builder import SpecBuilder
+
+# 1. Resolve exact versions used in the project
+resolver = DependencyResolver(providers=[PythonProvider(...)])
+resolved_deps = await resolver.resolve(Path("./my_project"))
+
+# 2. Fetch the metadata/signatures internally 
+# ...
+
+# 3. Build the strict constraints for the LLM
+builder = SpecBuilder()
+system_instruction = builder.build_system_prompt(api_indexes, patterns)
+
+print(system_instruction) 
+# Outputs: 
+# ## litellm 1.40.0
+# - completion(model: str, messages: list) -> ModelResponse
+# ⚠ PATTERN: fastapi + temporalio
+# Rule [NO_WORKFLOW_IN_HANDLER]: Workflows must run in workers.
+```
+
+## Contributing
+When adding a new Ecosystem Provider (e.g., NodeProvider), you must adhere to the asynchronous contract defined in src/providers/base.py. All registry interactions must be defensive and non-blocking.

vcase_auto_context-0.1.0/setup.cfg

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

vcase_auto_context-0.1.0/tests/test_api_validator.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+import pytest
+
+from vcase.service.api_validator import ApiValidator
+from vcase.providers.base import ApiIndex, ApiSignature, ApiParameter
+
+
+class TestApiValidator:
+
+    def test_passes_when_all_calls_exist_in_index(self) -> None:
+        validator = ApiValidator()
+        code = "import litellm\nlitellm.completion(model='gpt-4o', messages=[])"
+        api_indexes = [
+            ApiIndex(
+                package="litellm",
+                version="1.40.0",
+                signatures=(
+                    ApiSignature(
+                        qualified_name="litellm.completion",
+                        parameters=(
+                            ApiParameter(name="model", type_hint="str", required=True, description=""),
+                            ApiParameter(name="messages", type_hint="list", required=True, description="")
+                        ),
+                        return_type="ModelResponse",
+                        available_since="",
+                        deprecated=False
+                    ),
+                )
+            )
+        ]
+        result = validator.validate(code, api_indexes)
+        assert result.passed is True
+        assert len(result.violations) == 0
+
+    def test_flags_call_not_present_in_api_index(self) -> None:
+        validator = ApiValidator()
+        code = "import litellm\nlitellm.non_existent(model='gpt-5-mini')"
+        api_indexes = [
+            ApiIndex(
+                package="litellm",
+                version="1.40.0",
+                signatures=()
+            )
+        ]
+        result = validator.validate(code, api_indexes)
+        assert result.passed is False
+        assert any(v.rule_name == "api-unknown" for v in result.violations)
+
+    def test_flags_deprecated_api_usage(self) -> None:
+        validator = ApiValidator()
+        code = "import litellm\nlitellm.completion(model='gpt-4o')"
+        api_indexes = [
+            ApiIndex(
+                package="litellm",
+                version="1.40.0",
+                signatures=(
+                    ApiSignature(
+                        qualified_name="litellm.completion",
+                        parameters=(ApiParameter(name="model", type_hint="str", required=True, description=""),),
+                        return_type="ModelResponse",
+                        available_since="",
+                        deprecated=True,
+                        deprecation_note="Use acompletion instead."
+                    ),
+                )
+            )
+        ]
+        result = validator.validate(code, api_indexes)
+        assert result.passed is True
+        assert any(v.rule_name == "api-deprecated" for v in result.violations)
+
+    def test_returns_empty_violations_for_empty_code(self) -> None:
+        validator = ApiValidator()
+        result = validator.validate("", [])
+        assert result.passed is True
+        assert len(result.violations) == 0
+
+    def test_passes_with_arbitrary_kwargs_when_signature_has_kwargs(self) -> None:
+        validator = ApiValidator()
+        code = "import litellm\nlitellm.completion(model='gpt-4o', messages=[], custom_kwarg=123)"
+        api_indexes = [
+            ApiIndex(
+                package="litellm",
+                version="1.40.0",
+                signatures=(
+                    ApiSignature(
+                        qualified_name="litellm.completion",
+                        parameters=(
+                            ApiParameter(name="model", type_hint="str", required=True, description=""),
+                            ApiParameter(name="**kwargs", type_hint="Any", required=False, description=""),
+                        ),
+                        return_type="ModelResponse",
+                        available_since="",
+                        deprecated=False
+                    ),
+                )
+            )
+        ]
+        result = validator.validate(code, api_indexes)
+        assert result.passed is True
+        assert len(result.violations) == 0
+
+    def test_passes_with_markdown_code_fences(self) -> None:
+        validator = ApiValidator()
+        code = "```python\nimport litellm\nlitellm.completion(model='gpt-4o')\n```"
+        api_indexes = [
+            ApiIndex(
+                package="litellm",
+                version="1.40.0",
+                signatures=(
+                    ApiSignature(
+                        qualified_name="litellm.completion",
+                        parameters=(
+                            ApiParameter(name="model", type_hint="str", required=True, description=""),
+                        ),
+                        return_type="ModelResponse",
+                        available_since="",
+                        deprecated=False
+                    ),
+                )
+            )
+        ]
+        result = validator.validate(code, api_indexes)
+        assert result.passed is True
+        assert len(result.violations) == 0

vcase_auto_context-0.1.0/tests/test_architecture_validator.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import pytest
+
+from vcase.service.architecture_validator import ArchitectureValidator
+from vcase.providers.base import InteractionConstraint, TechnologyPattern
+
+
+class TestArchitectureValidator:
+
+    def test_flags_temporal_workflow_called_inside_fastapi_handler(self) -> None:
+        validator = ArchitectureValidator()
+        code = """
+import fastapi
+import workflow
+
+app = fastapi.FastAPI()
+
+@app.post("/workflow")
+async def run():
+    await workflow.run()
+"""
+        constraint = InteractionConstraint(
+            rule_name="NO_WORKFLOW_IN_FASTAPI_ROUTE",
+            allowed_in=(),
+            disallowed_in=("app.post", "app.get"),
+            description="Temporal workflows cannot run directly in FastAPI route handlers."
+        )
+        result = validator.validate(code, [], [constraint])
+        assert result.passed is False
+        assert any(v.rule_name == "NO_WORKFLOW_IN_FASTAPI_ROUTE" for v in result.violations)
+
+    def test_flags_langfuse_used_as_sequential_log_instead_of_callback(self) -> None:
+        validator = ArchitectureValidator()
+        code = """
+import langfuse
+import litellm
+
+# Sequential log call
+langfuse.log()
+"""
+        constraint = InteractionConstraint(
+            rule_name="NO_SEQUENTIAL_LANGFUSE_LOG",
+            allowed_in=(),
+            disallowed_in=("sequential_flow",),
+            description="Langfuse integration with LiteLLM should use callbacks."
+        )
+        result = validator.validate(code, [], [constraint])
+        assert result.passed is False
+        assert any(v.rule_name == "NO_SEQUENTIAL_LANGFUSE_LOG" for v in result.violations)
+
+    def test_flags_sqlalchemy_session_instantiated_inside_handler(self) -> None:
+        validator = ArchitectureValidator()
+        code = """
+import fastapi
+app = fastapi.FastAPI()
+
+@app.post("/items")
+def create_item():
+    db = Session()
+"""
+        constraint = InteractionConstraint(
+            rule_name="NO_MANUAL_DB_SESSION_IN_HANDLER",
+            allowed_in=(),
+            disallowed_in=("handler_body",),
+            description="Do not manually create DB session inside handlers."
+        )
+        result = validator.validate(code, [], [constraint])
+        assert result.passed is False
+        assert any(v.rule_name == "NO_MANUAL_DB_SESSION_IN_HANDLER" for v in result.violations)
+
+    def test_passes_valid_temporal_client_usage_outside_handler(self) -> None:
+        validator = ArchitectureValidator()
+        code = """
+import temporalio
+import workflow
+
+async def run_worker():
+    await workflow.run()
+"""
+        constraint = InteractionConstraint(
+            rule_name="NO_WORKFLOW_IN_FASTAPI_ROUTE",
+            allowed_in=(),
+            disallowed_in=("app.post", "app.get"),
+            description="Temporal workflows cannot run directly in FastAPI route handlers."
+        )
+        result = validator.validate(code, [], [constraint])
+        assert result.passed is True
+        assert len(result.violations) == 0
+
+    def test_passes_when_no_constraints_apply_to_detected_stack(self) -> None:
+        validator = ArchitectureValidator()
+        code = "print('hello')"
+        result = validator.validate(code, [], [])
+        assert result.passed is True
+        assert len(result.violations) == 0

vcase_auto_context-0.1.0/tests/test_ast_parser.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+import pytest
+
+from vcase.service.ast_parser import AstParser
+
+
+class TestAstParser:
+
+    def test_parses_vararg_and_kwarg_correctly(self) -> None:
+        parser = AstParser()
+        code = """
+def test_func(a, b=1, *args, c=2, **kwargs):
+    pass
+"""
+        with tempfile.NamedTemporaryFile(suffix=".py", delete=False, mode="w", encoding="utf-8") as f:
+            f.write(code)
+            tmp_path = Path(f.name)
+
+        try:
+            api_index = parser.parse_file(package_name="testpkg", package_version="1.0.0", filepath=tmp_path)
+            assert api_index.package == "testpkg"
+            assert api_index.version == "1.0.0"
+            assert len(api_index.signatures) == 1
+            sig = api_index.signatures[0]
+            assert sig.qualified_name.endswith(".test_func")
+            
+            param_names = [p.name for p in sig.parameters]
+            assert "a" in param_names
+            assert "*args" in param_names
+            assert "c" in param_names
+            assert "**kwargs" in param_names
+        finally:
+            try:
+                tmp_path.unlink()
+            except Exception:
+                pass

vcase_auto_context-0.1.0/tests/test_detector.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from vcase.service.detector import TechnologyDetector
+from vcase.providers.python_provider import PythonProvider
+from vcase.providers.node_provider import NodeProvider
+
+
+class TestTechnologyDetector:
+
+    def test_detects_python_ecosystem_from_lock_file(self, fixture_repo_path: Path) -> None:
+        (fixture_repo_path / "poetry.lock").write_text("", encoding="utf-8")
+        provider = PythonProvider(pypi_client=None, api_index_cache=None)
+        detector = TechnologyDetector([provider])
+        assert provider in detector.detect_ecosystems(fixture_repo_path)
+
+    def test_detects_node_ecosystem_from_package_json(self, fixture_repo_path: Path) -> None:
+        (fixture_repo_path / "package.json").write_text("{}", encoding="utf-8")
+        provider = NodeProvider(npm_client=None)
+        detector = TechnologyDetector([provider])
+        assert provider in detector.detect_ecosystems(fixture_repo_path)
+
+    def test_returns_empty_list_when_no_known_ecosystem_found(self, fixture_repo_path: Path) -> None:
+        detector = TechnologyDetector([])
+        assert detector.detect_ecosystems(fixture_repo_path) == []
+
+    def test_extracts_technology_names_from_prompt(self) -> None:
+        detector = TechnologyDetector([])
+        prompt = "Create a FastAPI app that queries celery tasks and uses redis."
+        techs = detector.detect_technologies_in_prompt(prompt)
+        assert "fastapi" in techs
+        assert "celery" in techs
+        assert "redis" in techs
+
+    def test_handles_prompt_with_no_known_technologies(self) -> None:
+        detector = TechnologyDetector([])
+        prompt = "Hello, write a hello world function."
+        assert detector.detect_technologies_in_prompt(prompt) == []

vcase_auto_context-0.1.0/tests/test_engine_python.py

@@ -0,0 +1,46 @@
+import asyncio
+import logging
+import sys
+import os
+from pathlib import Path
+import httpx
+
+# Fix the path before importing our internal modules
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+import pytest
+# 1. Import exactly the names we gave our classes
+from vcase.api.pypi_client import PypiClient
+from vcase.providers.python_provider import PythonProvider
+from vcase.service.resolver import DependencyResolver
+
+@pytest.mark.asyncio
+async def test_engine_python():
+    logging.basicConfig(level=logging.INFO)
+    
+    # 2. Assign the client to a variable!
+    # (If you don't, you can't close it later!)
+    http_client=httpx.AsyncClient()
+    api_client = PypiClient(client=http_client)
+    
+    # 3. Pass the client variable into the provider
+    provider = PythonProvider(api_client)
+    
+    # 4. Our class was named DependencyResolver, and it takes providers in its initialization
+    resolver = DependencyResolver(providers=[provider])
+    
+    repo_path = Path(__file__).parent
+    
+    # 5. Call the actual method we built: "resolve"
+    print("Executing resolution pipeline...")
+    resolved_deps = await resolver.resolve(repo_path)
+    
+    # 6. We need to print them to prove it worked!
+    for dep in resolved_deps:
+         print(f"{dep.name}: {dep.version} ({dep.resolution_tier.name})")
+         
+    # 7. Now we safely close the variable we created in step 2
+    await http_client.aclose()
+
+if __name__ == "__main__":
+    asyncio.run(test_engine_python())

vcase_auto_context-0.1.0/tests/test_llm_validator.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import os
+from unittest.mock import AsyncMock, patch
+import pytest
+import httpx
+
+from vcase.service.llm_validator import LlmValidator
+from vcase.providers.base import ApiIndex, ApiSignature, ApiParameter
+
+
+class TestLlmValidatorOpenRouter:
+
+    @pytest.mark.asyncio
+    @patch.dict(os.environ, {
+        "OPENROUTER_API_KEY": "sk-or-v1-test-key",
+        "OPENAI_API_KEY": "",
+        "GEMINI_API_KEY": ""
+    })
+    async def test_validate_calls_openrouter_correctly(self) -> None:
+        validator = LlmValidator("moonshotai/kimi-k2.6")
+        
+        # Mocking the response of httpx client post call
+        mock_response = httpx.Response(
+            status_code=200,
+            json={"choices": [{"message": {"content": "PASS"}}]}
+        )
+        
+        # We patch httpx.AsyncClient.post
+        with patch("httpx.AsyncClient.post", new_callable=AsyncMock) as mock_post:
+            mock_post.return_value = mock_response
+            
+            api_indexes = [
+                ApiIndex(
+                    package="litellm",
+                    version="1.40.0",
+                    signatures=(
+                        ApiSignature(
+                            qualified_name="litellm.completion",
+                            parameters=(
+                                ApiParameter(name="model", type_hint="str", required=True, description=""),
+                            ),
+                            return_type="ModelResponse",
+                            available_since="",
+                            deprecated=False
+                        ),
+                    )
+                )
+            ]
+            
+            result = await validator.validate(
+                generated_code="import litellm\nlitellm.completion(model='gpt-4o')",
+                api_indexes=api_indexes,
+                violation_context="[api-invalid-kwargs] test violation"
+            )
+            
+            assert result.passed is True
+            assert len(result.violations) == 0
+            
+            # Verify the call payload
+            mock_post.assert_called_once()
+            called_url = mock_post.call_args[0][0]
+            called_kwargs = mock_post.call_args[1]
+            
+            assert called_url == "https://openrouter.ai/api/v1/chat/completions"
+            assert called_kwargs["headers"]["Authorization"] == "Bearer sk-or-v1-test-key"
+            assert called_kwargs["headers"]["HTTP-Referer"] == "https://github.com/smuggypusss/Version-Constrained-API-Specification-Engine"
+            assert called_kwargs["json"]["model"] == "moonshotai/kimi-k2.6"
+            assert "You are a strict code validator" in called_kwargs["json"]["messages"][0]["content"]

vcase_auto_context-0.1.0/tests/test_resolver.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from pathlib import Path
+import pytest
+
+from vcase.service.resolver import DependencyResolver
+from vcase.providers.python_provider import PythonProvider
+from vcase.providers.base import ResolutionTier, Ecosystem
+
+
+class MockPypiClient:
+    async def get_latest_version(self, package: str) -> str:
+        if package == "langfuse":
+            return "2.5.1"
+        return "1.0.0"
+
+
+class TestDependencyResolver:
+
+    @pytest.mark.asyncio
+    async def test_resolves_from_lock_file_as_tier_one(
+        self, fixture_repo_path: Path, sample_poetry_lock_content: str
+    ) -> None:
+        (fixture_repo_path / "poetry.lock").write_text(sample_poetry_lock_content, encoding="utf-8")
+        client = MockPypiClient()
+        provider = PythonProvider(pypi_client=client, api_index_cache=None)
+        resolver = DependencyResolver(providers=[provider])
+        resolved = await resolver.resolve(fixture_repo_path)
+        assert len(resolved) == 3
+        litellm = next(d for d in resolved if d.name == "litellm")
+        assert litellm.version == "1.40.0"
+        assert litellm.resolution_tier == ResolutionTier.LOCK_FILE
+
+    @pytest.mark.asyncio
+    async def test_falls_back_to_declaration_when_lock_file_missing(
+        self, fixture_repo_path: Path, sample_requirements_txt_content: str
+    ) -> None:
+        (fixture_repo_path / "requirements.txt").write_text(sample_requirements_txt_content, encoding="utf-8")
+        client = MockPypiClient()
+        provider = PythonProvider(pypi_client=client, api_index_cache=None)
+        resolver = DependencyResolver(providers=[provider])
+        resolved = await resolver.resolve(fixture_repo_path)
+        assert len(resolved) == 3
+        langfuse = next(d for d in resolved if d.name == "langfuse")
+        assert langfuse.version == "2.5.1"
+        assert langfuse.resolution_tier == ResolutionTier.DECLARATION
+
+    @pytest.mark.asyncio
+    async def test_logs_warning_when_no_manifest_found(self, fixture_repo_path: Path) -> None:
+        provider = PythonProvider(pypi_client=None, api_index_cache=None)
+        resolver = DependencyResolver(providers=[provider])
+        resolved = await resolver.resolve(fixture_repo_path)
+        assert resolved == []
+
+    @pytest.mark.asyncio
+    async def test_normalized_output_contains_resolution_tier(
+        self, fixture_repo_path: Path, sample_poetry_lock_content: str
+    ) -> None:
+        (fixture_repo_path / "poetry.lock").write_text(sample_poetry_lock_content, encoding="utf-8")
+        client = MockPypiClient()
+        provider = PythonProvider(pypi_client=client, api_index_cache=None)
+        resolver = DependencyResolver(providers=[provider])
+        resolved = await resolver.resolve(fixture_repo_path)
+        for dep in resolved:
+            assert dep.resolution_tier in (ResolutionTier.LOCK_FILE, ResolutionTier.DECLARATION)
+            assert dep.ecosystem == Ecosystem.PYTHON