praesidium 0.1.0__tar.gz

praesidium-0.1.0/.env

@@ -0,0 +1,3 @@
+GROQ_API_KEY='test_key_12345'
+# Optional override, defaults to openai/gpt-oss-120b:
+# GROQ_MODEL=openai/gpt-oss-20b

praesidium-0.1.0/.env.example

@@ -0,0 +1,3 @@
+GROQ_API_KEY=gsk_...
+# Optional override, defaults to openai/gpt-oss-120b:
+# GROQ_MODEL=openai/gpt-oss-20b

praesidium-0.1.0/.idea/.gitignore

@@ -0,0 +1,10 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Ignored default folder with query files
+/queries/
+# Datasource local storage ignored files
+/dataSources/
+/dataSources.local.xml
+# Editor-based HTTP Client requests
+/httpRequests/

praesidium-0.1.0/.idea/OIST-ACM-AOC-CodeCrafters.iml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="PYTHON_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$">
+      <excludeFolder url="file://$MODULE_DIR$/.venv" />
+    </content>
+    <orderEntry type="jdk" jdkName="uv (OIST-ACM-AOC-CodeCrafters) (2)" jdkType="Python SDK" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

praesidium-0.1.0/.idea/copilot.data.migration.ask2agent.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="Ask2AgentMigrationStateService">
+    <option name="migrationStatus" value="COMPLETED" />
+  </component>
+</project>

praesidium-0.1.0/.idea/inspectionProfiles/Project_Default.xml

@@ -0,0 +1,81 @@
+<component name="InspectionProjectProfileManager">
+  <profile version="1.0">
+    <option name="myName" value="Project Default" />
+    <inspection_tool class="IncorrectHttpHeaderInspection" enabled="true" level="WARNING" enabled_by_default="true">
+      <option name="customHeaders">
+        <set>
+          <option value="file=@sample.pdf" />
+        </set>
+      </option>
+    </inspection_tool>
+    <inspection_tool class="PyCompatibilityInspection" enabled="true" level="WARNING" enabled_by_default="true">
+      <option name="ourVersions">
+        <value>
+          <list size="1">
+            <item index="0" class="java.lang.String" itemvalue="3.13" />
+          </list>
+        </value>
+      </option>
+    </inspection_tool>
+    <inspection_tool class="PyInterpreterInspection" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="PyPackageRequirementsInspection" enabled="false" level="WARNING" enabled_by_default="false">
+      <option name="ignoredPackages">
+        <list>
+          <option value="annotated-types" />
+          <option value="anyio" />
+          <option value="asgiref" />
+          <option value="cffi" />
+          <option value="cryptography" />
+          <option value="distro" />
+          <option value="dj-database-url" />
+          <option value="dj-rest-auth" />
+          <option value="Django" />
+          <option value="django-allauth" />
+          <option value="django-filter" />
+          <option value="django-stubs" />
+          <option value="django-stubs-ext" />
+          <option value="djangorestframework" />
+          <option value="djangorestframework-stubs" />
+          <option value="djangorestframework_simplejwt" />
+          <option value="google-auth" />
+          <option value="google-genai" />
+          <option value="gunicorn" />
+          <option value="h11" />
+          <option value="httpcore" />
+          <option value="httpx" />
+          <option value="psycopg2-binary" />
+          <option value="pyasn1" />
+          <option value="pyasn1_modules" />
+          <option value="pycparser" />
+          <option value="pydantic" />
+          <option value="pydantic_core" />
+          <option value="PyJWT" />
+          <option value="python-dotenv" />
+          <option value="rsa" />
+          <option value="sniffio" />
+          <option value="sqlparse" />
+          <option value="types-PyYAML" />
+          <option value="typing-inspection" />
+          <option value="websockets" />
+          <option value="django-cors-headers" />
+        </list>
+      </option>
+    </inspection_tool>
+    <inspection_tool class="PyPep8NamingInspection" enabled="true" level="WEAK WARNING" enabled_by_default="true">
+      <option name="ignoredErrors">
+        <list>
+          <option value="N813" />
+          <option value="N803" />
+          <option value="N806" />
+        </list>
+      </option>
+    </inspection_tool>
+    <inspection_tool class="PyStubPackagesAdvertiser" enabled="true" level="WARNING" enabled_by_default="true">
+      <option name="ignoredPackages">
+        <list>
+          <option value="pandas" />
+        </list>
+      </option>
+    </inspection_tool>
+  </profile>
+</component>

praesidium-0.1.0/.idea/inspectionProfiles/profiles_settings.xml

@@ -0,0 +1,6 @@
+<component name="InspectionProjectProfileManager">
+  <settings>
+    <option name="USE_PROJECT_PROFILE" value="false" />
+    <version value="1.0" />
+  </settings>
+</component>

praesidium-0.1.0/.idea/misc.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="Black">
+    <option name="sdkName" value="uv (OIST-ACM-AOC-CodeCrafters) (2)" />
+  </component>
+  <component name="ProjectRootManager" version="2" project-jdk-name="uv (OIST-ACM-AOC-CodeCrafters) (2)" project-jdk-type="Python SDK" />
+</project>

praesidium-0.1.0/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/OIST-ACM-AOC-CodeCrafters.iml" filepath="$PROJECT_DIR$/.idea/OIST-ACM-AOC-CodeCrafters.iml" />
+    </modules>
+  </component>
+</project>

praesidium-0.1.0/.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="$PROJECT_DIR$" vcs="Git" />
+  </component>
+</project>

praesidium-0.1.0/.idea/workspace.xml

@@ -0,0 +1,190 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="AutoImportSettings">
+    <option name="autoReloadType" value="SELECTIVE" />
+  </component>
+  <component name="ChangeListManager">
+    <list default="true" id="1155a69b-3971-4839-9d64-cc45e3d5adad" name="Changes" comment="Added scaffolding">
+      <change afterPath="$PROJECT_DIR$/.idea/.gitignore" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/.idea/OIST-ACM-AOC-CodeCrafters.iml" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/.idea/copilot.data.migration.ask2agent.xml" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/.idea/inspectionProfiles/Project_Default.xml" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/.idea/inspectionProfiles/profiles_settings.xml" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/.idea/misc.xml" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/.idea/modules.xml" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/.idea/vcs.xml" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/tests/test_pipeline_integration.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/.env.example" beforeDir="false" afterPath="$PROJECT_DIR$/.env.example" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/README.md" beforeDir="false" afterPath="$PROJECT_DIR$/README.md" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/pyproject.toml" beforeDir="false" afterPath="$PROJECT_DIR$/pyproject.toml" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/scripts/smoke_test.py" beforeDir="false" afterPath="$PROJECT_DIR$/scripts/smoke_test.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/dynamic_harness.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/dynamic_harness.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/hypothesis.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/hypothesis.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/nodes.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/nodes.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/tests/test_dynamic_harness.py" beforeDir="false" afterPath="$PROJECT_DIR$/tests/test_dynamic_harness.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/tests/test_graph_builder.py" beforeDir="false" afterPath="$PROJECT_DIR$/tests/test_graph_builder.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/uv.lock" beforeDir="false" afterPath="$PROJECT_DIR$/uv.lock" afterDir="false" />
+    </list>
+    <option name="SHOW_DIALOG" value="false" />
+    <option name="HIGHLIGHT_CONFLICTS" value="true" />
+    <option name="HIGHLIGHT_NON_ACTIVE_CHANGELIST" value="false" />
+    <option name="LAST_RESOLUTION" value="IGNORE" />
+  </component>
+  <component name="CopilotPersistence">
+    <persistenceIdMap>
+      <entry key="_C:/Users/acer/PycharmProjects/OIST-ACM-AOC-CodeCrafters" value="3GKN3bDyvyIJc6rnK0knBQ8Xu6j" />
+    </persistenceIdMap>
+  </component>
+  <component name="EmbeddingIndexingInfo">
+    <option name="cachedIndexableFilesCount" value="9" />
+    <option name="fileBasedEmbeddingIndicesEnabled" value="true" />
+  </component>
+  <component name="FileTemplateManagerImpl">
+    <option name="RECENT_TEMPLATES">
+      <list>
+        <option value="Python Script" />
+      </list>
+    </option>
+  </component>
+  <component name="Git.Settings">
+    <option name="RECENT_GIT_ROOT_PATH" value="$PROJECT_DIR$" />
+  </component>
+  <component name="GithubDefaultAccount">
+    <option name="defaultAccountId" value="e896eba7-bbd3-45ba-8410-e73e589fe335" />
+  </component>
+  <component name="McpProjectServerCommands">
+    <commands />
+    <urls />
+  </component>
+  <component name="ProjectColorInfo"><![CDATA[{
+  "associatedIndex": 2
+}]]></component>
+  <component name="ProjectId" id="3GKN3bDyvyIJc6rnK0knBQ8Xu6j" />
+  <component name="ProjectViewState">
+    <option name="hideEmptyMiddlePackages" value="true" />
+    <option name="showLibraryContents" value="true" />
+  </component>
+  <component name="PropertiesComponent"><![CDATA[{
+  "keyToString": {
+    "ModuleVcsDetector.initialDetectionPerformed": "true",
+    "Python tests.Python tests for tests.test_dynamic_harness.test_patch_logs_invocation_when_reached.executor": "Run",
+    "Python.smoke_test.executor": "Run",
+    "RunOnceActivity.MCP Project settings loaded": "true",
+    "RunOnceActivity.ShowReadmeOnStart": "true",
+    "RunOnceActivity.TerminalTabsStorage.copyFrom.TerminalArrangementManager.252": "true",
+    "RunOnceActivity.git.unshallow": "true",
+    "RunOnceActivity.typescript.service.memoryLimit.init": "true",
+    "SHARE_PROJECT_CONFIGURATION_FILES": "true",
+    "ai.playground.ignore.import.keys.banner.in.settings": "true",
+    "git-widget-placeholder": "master",
+    "last_opened_file_path": "C:/Users/acer/PycharmProjects/OIST-ACM-AOC-CodeCrafters/src",
+    "node.js.detected.package.eslint": "true",
+    "node.js.detected.package.tslint": "true",
+    "node.js.selected.package.eslint": "(autodetect)",
+    "node.js.selected.package.tslint": "(autodetect)",
+    "nodejs_package_manager_path": "npm",
+    "settings.editor.selected.configurable": "com.jetbrains.python.configuration.PyActiveSdkModuleConfigurable",
+    "vue.rearranger.settings.migration": "true"
+  }
+}]]></component>
+  <component name="RecentsManager">
+    <key name="CopyFile.RECENT_KEYS">
+      <recent name="C:\Users\acer\PycharmProjects\OIST-ACM-AOC-CodeCrafters\src" />
+      <recent name="C:\Users\acer\PycharmProjects\OIST-ACM-AOC-CodeCrafters" />
+      <recent name="C:\Users\acer\PycharmProjects\OIST-ACM-AOC-CodeCrafters\scripts" />
+      <recent name="C:\Users\acer\PycharmProjects\OIST-ACM-AOC-CodeCrafters\tests" />
+    </key>
+    <key name="MoveFile.RECENT_KEYS">
+      <recent name="C:\Users\acer\PycharmProjects\OIST-ACM-AOC-CodeCrafters\src" />
+    </key>
+  </component>
+  <component name="RunManager">
+    <configuration name="Python tests for tests.test_dynamic_harness.test_patch_logs_invocation_when_reached" type="tests" factoryName="Autodetect" temporary="true" nameIsGenerated="true">
+      <module name="OIST-ACM-AOC-CodeCrafters" />
+      <option name="ENV_FILES" value="" />
+      <option name="INTERPRETER_OPTIONS" value="" />
+      <option name="PARENT_ENVS" value="true" />
+      <option name="SDK_HOME" value="" />
+      <option name="WORKING_DIRECTORY" value="$PROJECT_DIR$" />
+      <option name="IS_MODULE_SDK" value="true" />
+      <option name="ADD_CONTENT_ROOTS" value="true" />
+      <option name="ADD_SOURCE_ROOTS" value="true" />
+      <EXTENSION ID="PythonCoverageRunConfigurationExtension" runner="coverage.py" />
+      <option name="RUN_TOOL" value="" />
+      <option name="_new_additionalArguments" value="&quot;&quot;" />
+      <option name="_new_target" value="&quot;tests.test_dynamic_harness.test_patch_logs_invocation_when_reached&quot;" />
+      <option name="_new_targetType" value="&quot;PYTHON&quot;" />
+      <method v="2" />
+    </configuration>
+    <recent_temporary>
+      <list>
+        <item itemvalue="Python tests.Python tests for tests.test_dynamic_harness.test_patch_logs_invocation_when_reached" />
+      </list>
+    </recent_temporary>
+  </component>
+  <component name="SharedIndexes">
+    <attachedChunks>
+      <set>
+        <option value="bundled-js-predefined-d6986cc7102b-9b0f141eb926-JavaScript-PY-253.31033.139" />
+        <option value="bundled-python-sdk-2653e85de345-6d6dccd035ac-com.jetbrains.pycharm.pro.sharedIndexes.bundled-PY-253.31033.139" />
+      </set>
+    </attachedChunks>
+  </component>
+  <component name="TaskManager">
+    <task active="true" id="Default" summary="Default task">
+      <changelist id="1155a69b-3971-4839-9d64-cc45e3d5adad" name="Changes" comment="" />
+      <created>1783716103926</created>
+      <option name="number" value="Default" />
+      <option name="presentableId" value="Default" />
+      <updated>1783716103926</updated>
+      <workItem from="1783716105610" duration="6629000" />
+    </task>
+    <task id="LOCAL-00001" summary="Initial commit">
+      <option name="closed" value="true" />
+      <created>1783716243199</created>
+      <option name="number" value="00001" />
+      <option name="presentableId" value="LOCAL-00001" />
+      <option name="project" value="LOCAL" />
+      <updated>1783716243199</updated>
+    </task>
+    <task id="LOCAL-00002" summary="Added dependencies">
+      <option name="closed" value="true" />
+      <created>1783716359805</created>
+      <option name="number" value="00002" />
+      <option name="presentableId" value="LOCAL-00002" />
+      <option name="project" value="LOCAL" />
+      <updated>1783716359805</updated>
+    </task>
+    <task id="LOCAL-00003" summary="Added scaffolding">
+      <option name="closed" value="true" />
+      <created>1783717758111</created>
+      <option name="number" value="00003" />
+      <option name="presentableId" value="LOCAL-00003" />
+      <option name="project" value="LOCAL" />
+      <updated>1783717758111</updated>
+    </task>
+    <option name="localTasksCounter" value="4" />
+    <servers />
+  </component>
+  <component name="TypeScriptGeneratedFilesManager">
+    <option name="version" value="3" />
+  </component>
+  <component name="VcsManagerConfiguration">
+    <MESSAGE value="Initial commit" />
+    <MESSAGE value="Added dependencies" />
+    <MESSAGE value="Added scaffolding" />
+    <option name="LAST_COMMIT_MESSAGE" value="Added scaffolding" />
+  </component>
+  <component name="com.intellij.coverage.CoverageDataManagerImpl">
+    <SUITE FILE_PATH="coverage/OIST_ACM_AOC_CodeCrafters$.coverage" NAME=" Coverage Results" MODIFIED="1783720083456" SOURCE_PROVIDER="com.intellij.coverage.DefaultCoverageFileProvider" RUNNER="coverage.py" COVERAGE_BY_TEST_ENABLED="false" COVERAGE_TRACING_ENABLED="false" WORKING_DIRECTORY="$PROJECT_DIR$" />
+    <SUITE FILE_PATH="coverage/OIST_ACM_AOC_CodeCrafters$smoke_test.coverage" NAME="smoke_test Coverage Results" MODIFIED="1783719757542" SOURCE_PROVIDER="com.intellij.coverage.DefaultCoverageFileProvider" RUNNER="coverage.py" COVERAGE_BY_TEST_ENABLED="false" COVERAGE_TRACING_ENABLED="false" WORKING_DIRECTORY="$PROJECT_DIR$/scripts" />
+  </component>
+  <component name="github-copilot-workspace">
+    <instructionFileLocations>
+      <option value=".github/instructions" />
+    </instructionFileLocations>
+    <promptFileLocations>
+      <option value=".github/prompts" />
+    </promptFileLocations>
+  </component>
+</project>

praesidium-0.1.0/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: praesidium
+Version: 0.1.0
+Summary: Praesidium — dynamic CVE reachability confirmation engine
+Project-URL: Homepage, https://github.com/TheCodeKage/praesidium
+Project-URL: Repository, https://github.com/TheCodeKage/praesidium
+Project-URL: Issues, https://github.com/TheCodeKage/praesidium/issues
+Author-email: Naman Agrawal <nam.agr96@gmail.com>
+License: MIT
+Keywords: cve,reachability,security,static-analysis,vulnerability
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.13
+Requires-Dist: click>=8.1.0
+Requires-Dist: groq>=0.13.0
+Requires-Dist: langgraph>=0.2.0
+Requires-Dist: pydantic>=2.9.0
+Requires-Dist: python-dotenv>=1.0.1
+Provides-Extra: dev
+Requires-Dist: flask>=3.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Praesidium
+
+**Praesidium** is a dynamic CVE reachability confirmation engine that combines static analysis with LLM-powered hypothesis generation to determine if vulnerabilities are actually exploitable in your codebase.
+
+## Features
+
+- 🔍 **Static Call Graph Analysis** - Traces code paths from entry points to vulnerable functions
+- 🤖 **LLM-Powered Hypothesis Generation** - Uses Groq's GPT models to generate realistic exploit attempts
+- 🎯 **Dynamic Confirmation** - Monkeypatches vulnerable functions to confirm actual reachability
+- 📊 **Multi-CVE Support** - Analyze multiple CVEs against your codebase in one command
+- 🔑 **Easy Configuration** - Simple CLI for API key management
+- 📈 **FastAPI/Flask Support** - Works with popular Python web frameworks
+
+## Setup
+
+```bash
+uv sync --extra dev
+cp .env.example .env   # fill in GROQ_API_KEY (get one at console.groq.com)
+```
+
+## Run tests
+
+```bash
+uv run pytest -v
+```
+
+`test_graph_builder.py` and `test_dynamic_harness.py` run against the dummy
+fixture app in `tests/fixtures/dummy_target_app/` and need no API key —
+these are your fast inner-loop tests while building Hour 0:30–3:30.
+
+## Run the full pipeline (needs Groq API key)
+
+```bash
+uv run python scripts/smoke_test.py
+```
+
+Runs both a reachable and a not-reachable case against the dummy fixture,
+printing the full trace. This is your first real integration check before
+Checkpoint 1 with Engineer B — swap the dummy fixture for the real target
+app + real CVE once B has it ready.
+
+## CLI Usage
+
+### Installation
+
+```bash
+# Install from this directory
+uv pip install -e .
+
+# Or install from PyPI (once published)
+pip install praesidium
+```
+
+### Quick Start
+
+#### 1. Configure API Key
+
+```bash
+# Set your Groq API key (get one at console.groq.com)
+uv run praesidium config set-key gsk_your_api_key_here
+
+# Verify configuration
+uv run praesidium config show
+```
+
+#### 2. Analyze Multiple CVEs
+
+Create a JSON file with your CVE configurations:
+
+```json
+[
+  {
+    "cve_id": "CVE-2023-12345",
+    "flagged_function": "save_file",
+    "flagged_module": "app.services.upload",
+    "flagged_file": "app/services/upload.py",
+    "entry_points": ["app.routes.upload_endpoint"],
+    "advisory_summary": "Path traversal vulnerability",
+    "function_signature": "def save_file(filename, contents)"
+  },
+  {
+    "cve_id": "CVE-2023-67890",
+    "flagged_function": "process_data",
+    "flagged_module": "app.services.data",
+    "flagged_file": "app/services/data.py",
+    "entry_points": ["app.routes.data_endpoint"],
+    "advisory_summary": "SQL injection vulnerability"
+  }
+]
+```
+
+Run the analysis:
+
+```bash
+# Analyze current directory
+uv run praesidium run --cves cves.json
+
+# Analyze specific directory
+uv run praesidium run --cves cves.json --target /path/to/app
+
+# Get summary only
+uv run praesidium run --cves cves.json --summary
+
+# Output as JSON
+uv run praesidium run --cves cves.json --output json > results.json
+```
+
+#### 3. Check Single CVE
+
+For single CVE analysis:
+
+```bash
+# Generate sample config
+uv run praesidium init-config cve.json
+
+# Edit the config, then run
+uv run praesidium check /path/to/app --cve-config cve.json
+```
+
+Or use command-line options:
+
+```bash
+uv run praesidium check /path/to/app \
+  --cve-id CVE-2023-12345 \
+  --flagged-function save_file \
+  --flagged-module app.services.upload \
+  --flagged-file app/services/upload.py \
+  --entry-points app.routes.upload_endpoint \
+  --advisory-summary "Path traversal vulnerability"
+```
+
+### Available Commands
+
+- `praesidium config set-key <API_KEY>` - Configure Groq API key
+- `praesidium config show` - Display current configuration
+- `praesidium run --cves <FILE>` - Analyze multiple CVEs from JSON file
+- `praesidium check <PATH>` - Check single CVE against target app
+- `praesidium init-config <FILE>` - Generate sample CVE config file
+
+## Python API (the interface contract)
+
+```python
+from src import CVETarget, run_pipeline
+
+target = CVETarget(
+    cve_id="CVE-2024-XXXXX",
+    flagged_function="...",
+    flagged_module="...",
+    flagged_file="...",
+    entry_points=["..."],
+    advisory_summary="...",
+    function_signature="...",
+)
+
+result = run_pipeline(target, target_app_root="/path/to/target/app")
+# result: EngineOutput(cve_id, label, trace, static_path, hypothesis_attempts)
+```
+
+`CVETarget` and `EngineOutput` in `schemas.py` are the two shapes from
+build-plan.md Section 2 — sync any changes to these with Engineer B
+immediately, don't let them drift silently.
+
+## LLM provider
+
+Hypothesis generation (`hypothesis.py`) calls Groq's OpenAI-compatible chat
+completions endpoint, using `openai/gpt-oss-120b` by default (Groq's
+current recommended production model for reasoning workloads — the earlier
+`llama-3.3-70b-versatile` was deprecated). Override with `GROQ_MODEL` in
+`.env` if you want to try `openai/gpt-oss-20b` for lower latency during
+iteration. Groq's speed matters here specifically because Stage 2 can fire
+up to 3 calls per CVE (1 initial + 2 retries) inside a live demo.
+
+## Publishing to PyPI
+
+To publish Praesidium to PyPI:
+
+```bash
+# 1. Update version in pyproject.toml
+
+# 2. Build the package
+uv build
+
+# 3. Test on TestPyPI first (recommended)
+uv pip install twine
+uv run twine upload --repository testpypi dist/*
+
+# 4. Test install from TestPyPI
+pip install --index-url https://test.pypi.org/simple/ praesidium
+
+# 5. If everything works, publish to PyPI
+uv run twine upload dist/*
+```
+
+**Note:** You'll need PyPI accounts and API tokens. See [PyPI documentation](https://packaging.python.org/tutorials/packaging-projects/) for details.
+
+## Known scope boundaries (by design, not oversight)
+
+- Static graph resolution is name-based, not points-to analysis — decorators
+  and dynamic dispatch can produce false negatives at Stage 1. This is why
+  Stage 2 exists; don't try to fix it in `graph_builder.py`.
+- Retry cap is hard-set to 2 attempts (`nodes.py::MAX_RETRIES`) to keep demo
+  runtime bounded. Don't raise it without checking demo timing.
+- `EntryPointDriver` supports `callable` and `flask_route` shapes only. If
+  B's fixture needs CLI-arg driving, extend `dynamic_harness.py`.