lyingdocs 0.1.3__tar.gz → 0.1.4__tar.gz

{lyingdocs-0.1.3 → lyingdocs-0.1.4}/PKG-INFO

@@ -1,10 +1,11 @@
 Metadata-Version: 2.4
 Name: lyingdocs
-Version: 0.1.3
+Version: 0.1.4
 Summary: Autonomous documentation-code misalignment detection using LLM agents
 License-Expression: MIT
 License-File: LICENSE
 Requires-Python: >=3.11
+Requires-Dist: anthropic>=0.40
 Requires-Dist: openai>=1.0
 Requires-Dist: python-dotenv>=1.0
 Provides-Extra: dev
@@ -157,6 +158,18 @@ This performs a full audit of your repository and produces a report describing w
 
 ---
 
+## Documentation
+
+| | |
+| --- | --- |
+| [Configuration](docs/configuration.md) | Config file schema, environment variables, layer resolution |
+| [Argus Backends](docs/backends.md) | Setup for `local`, `codex`, and `claude_code` |
+| [CLI Reference](docs/cli.md) | All flags, commands, and output artifacts |
+| [GitHub Actions](docs/guides/github-actions.md) | CI integration, authentication, triggers, and approval gates |
+| [GitHub Issues](docs/guides/github-issues.md) | Using `--gen-issue` to draft and post issues |
+
+---
+
 ## Example use cases
 
 Use LyingDocs when you want to answer questions like:
@@ -183,218 +196,24 @@ These categories represent different ways repository trust breaks down.
 
 ---
 
-## Configuration
-
-LyingDocs loads configuration from multiple sources, with later sources overriding earlier ones:
-
-1. **Built-in defaults** (OpenAI API, gpt-5.4)
-2. **Config file** — `lyingdocs.toml` in project root, or `~/.config/lyingdocs/config.toml`
-3. **Environment variables** / `.env`
-4. **CLI arguments**
-
-Hermes and Argus are configured independently, so you can use:
-
-* a cheaper planning model for Hermes
-* a stronger coding / investigation model for Argus
-* different providers or endpoints for each agent
-
-### Config file example
-
-Example configs live in [tests/configs](https://github.com/KMing-L/lying-docs/tree/main/tests/configs).
-
-```toml
-[hermes]
-model = "gpt-5.4"
-base_url = "https://api.openai.com/v1"
-# api_key_env = "OPENAI_API_KEY"  # optional — defaults to OPENAI_API_KEY
-
-[argus]
-backend = "local"           # "codex" | "claude_code" | "local"
-model = "gpt-5.4"
-base_url = "https://api.openai.com/v1"
-# api_key_env = "OPENAI_API_KEY"
-
-# Only read when argus.backend = "codex"
-[argus.codex]
-provider = "openai"
-wire_api = "responses"
-# path = "/usr/local/bin/codex"   # optional: explicit codex binary path
-
-# Only read when argus.backend = "claude_code"
-[argus.claude_code]
-# path = "/usr/local/bin/claude"  # optional: explicit claude binary path
-
-# Only read when argus.backend = "local"
-[argus.local]
-max_iterations = 25         # per-task agent loop cap
-max_read_bytes = 200000     # per read_file call
-
-[limits]
-max_dispatches = 20         # max Argus dispatches per Hermes run
-max_iterations = 50         # max Hermes loop iterations
-argus_task_timeout = 1200   # seconds per Argus task (codex / claude_code backends)
-token_budget = 524288       # Hermes context budget before compression
-```
-
-### Environment variables
-
-| Variable                 | Description                                    |
-| ------------------------ | ---------------------------------------------- |
-| `OPENAI_API_KEY`         | Required unless overridden via `api_key_env`   |
-| `HERMES_MODEL`           | Hermes model name                              |
-| `HERMES_BASE_URL`        | Hermes API base URL                            |
-| `ARGUS_BACKEND`          | `codex`, `claude_code`, or `local`             |
-| `ARGUS_MODEL`            | Argus model name                               |
-| `ARGUS_BASE_URL`         | Argus API base URL                             |
-| `ARGUS_CODEX_PROVIDER`   | Codex backend provider                         |
-| `ARGUS_CODEX_WIRE_API`   | Codex backend wire API (`responses` or `chat`) |
-| `ARGUS_CODEX_PATH`       | Explicit path to `codex`                       |
-| `ARGUS_CLAUDE_CODE_PATH` | Explicit path to `claude`                      |
-| `ARGUS_TASK_TIMEOUT`     | Timeout per Argus task in seconds              |
-| `TOKEN_BUDGET`           | Hermes context budget before compression       |
-
----
-
-## Argus backends
-
-Argus is the deep code analysis side of the system.
-
-### `local`
-
-No external CLI required.
-Uses a built-in agent loop with filesystem tools and an OpenAI-compatible API.
-
-Good default for getting started.
-
-```toml
-[argus]
-backend = "local"
-model = "gpt-5.4"
-base_url = "https://api.openai.com/v1"
-```
-
-### `codex`
-
-Uses [OpenAI Codex CLI](https://github.com/openai/codex).
-
-```bash
-npm install -g @openai/codex
-```
-
-```toml
-[argus]
-backend = "codex"
-
-[argus.codex]
-provider = "openai"
-wire_api = "responses"
-```
-
-Resolution order:
-
-1. explicit path from config
-2. system `PATH`
-3. local `node_modules/.bin/codex`
-
-### `claude_code`
-
-Uses [Claude Code](https://docs.anthropic.com/claude/docs/claude-code).
-
-```toml
-[argus]
-backend = "claude_code"
-model = "claude-sonnet-4-6"
-
-[argus.claude_code]
-# path = "/usr/local/bin/claude"
-```
-
-Invoked as:
-
-```bash
-claude -p <prompt> --model <argus_model> --output-format text
-```
-
-with `cwd` set to your code root.
-
----
-
-## CLI reference
-
-```bash
-# Full analysis
-lyingdocs analyze --doc-path docs/ --code-path . -o output/audit
-
-# Choose Argus backend
-lyingdocs analyze --doc-path docs/ --code-path . --argus-backend=local
+## GitHub Actions
 
-# Different models for Hermes and Argus
-lyingdocs analyze --doc-path docs/ --code-path . \
-  --hermes-model gpt-5.4 \
-  --argus-model gpt-5.4
-
-# Resume interrupted analysis
-lyingdocs analyze --doc-path docs/ --code-path . --resume
-
-# Use an explicit config file
-lyingdocs analyze --doc-path docs/ --code-path . --config myconfig.toml
-
-# Generate GitHub issue drafts
-lyingdocs analyze --doc-path docs/ --code-path . --gen-issue
-
-# Show version
-lyingdocs version
-```
-
-Available flags:
-
-`--hermes-model`, `--hermes-base-url`, `--argus-backend {codex,claude_code,local}`, `--argus-model`, `--argus-base-url`, `--argus-codex-provider`, `--argus-codex-wire-api`, `--max-dispatches`, `--max-iterations`, `--config`, `--resume`, `--gen-issue`
-
----
-
-## Generating GitHub issue drafts
-
-Pass `--gen-issue` to automatically draft a GitHub issue after analysis:
+LyingDocs runs natively in GitHub Actions as a trust gate for your CI pipeline.
 
 ```bash
-lyingdocs analyze --doc-path docs/ --code-path . --gen-issue
-```
-
-LyingDocs uses Hermes to synthesize findings into a single, polite GitHub issue and saves it to `issue.json` in the output directory.
-
-The file contains:
-
-* **`title`** — a short issue title
-* **`body`** — a GitHub-flavored Markdown issue body listing findings, code references, doc references, and a note acknowledging possible false positives
-
-You can post it directly with the [`gh` CLI](https://cli.github.com/):
-
-```bash
-gh issue create \
-  --title "$(jq -r '.title' output/issue.json)" \
-  --body  "$(jq -r '.body'  output/issue.json)"
+pip install lyingdocs
+lyingdocs init-ci --doc-path docs/ --backend claude_code --claude-oauth --trigger tag,manual
 ```
 
-This makes LyingDocs useful not only as an audit tool, but as a bridge into repository maintenance workflows.
-
----
-
-## GitHub Actions direction
-
-LyingDocs is moving toward a natural next step:
-
-**continuous trust enforcement inside GitHub Actions**
+This generates a workflow that:
 
-The long-term shape of the project is not “run this manually forever.”
-The long-term shape is:
+* audits docs-vs-code alignment on every tag push (or on demand)
+* posts findings as a PR comment
+* optionally requires manual approval before merging
 
-* run on pull requests
-* comment on suspicious docs/code drift
-* warn maintainers before release
-* surface trust regressions early
-* make repository truthfulness part of CI
+Supports all three backends (`local`, `codex`, `claude_code`) and both API key and OAuth token authentication for Claude Code.
 
-That is where LyingDocs becomes most valuable: not only as an analyzer, but as infrastructure.
+See the [full setup guide](docs/guides/github-actions.md) for trigger options, approval gates, and backend configuration.
 
 ---
 
@@ -402,7 +221,7 @@ That is where LyingDocs becomes most valuable: not only as an analyzer, but as i
 
 * [x] **Multi-harness support** — Argus runs on Codex, Claude Code, or a built-in local agent
 * [x] **Issue generation** — `--gen-issue` drafts GitHub issues from findings
-* [ ] **GitHub Action integration** — run LyingDocs automatically in PRs and CI to catch trust regressions as they are introduced
+* [x] **GitHub Action integration** — `lyingdocs init-ci` generates a ready-to-use workflow with configurable triggers, backend selection, PR comments, and manual approval gates
 * [ ] **One-session memory support** — Argus backends retain state across tasks for deeper multi-step investigations
 * [ ] **Deeper analysis** — multi-hop reasoning across doc hierarchies and version-aware diffing to detect when code changed but docs did not
 * [ ] **Paper mode** — treat academic papers as documentation and detect paper-to-code misalignment

{lyingdocs-0.1.3 → lyingdocs-0.1.4}/README.md

@@ -142,6 +142,18 @@ This performs a full audit of your repository and produces a report describing w
 
 ---
 
+## Documentation
+
+| | |
+| --- | --- |
+| [Configuration](docs/configuration.md) | Config file schema, environment variables, layer resolution |
+| [Argus Backends](docs/backends.md) | Setup for `local`, `codex`, and `claude_code` |
+| [CLI Reference](docs/cli.md) | All flags, commands, and output artifacts |
+| [GitHub Actions](docs/guides/github-actions.md) | CI integration, authentication, triggers, and approval gates |
+| [GitHub Issues](docs/guides/github-issues.md) | Using `--gen-issue` to draft and post issues |
+
+---
+
 ## Example use cases
 
 Use LyingDocs when you want to answer questions like:
@@ -168,218 +180,24 @@ These categories represent different ways repository trust breaks down.
 
 ---
 
-## Configuration
-
-LyingDocs loads configuration from multiple sources, with later sources overriding earlier ones:
-
-1. **Built-in defaults** (OpenAI API, gpt-5.4)
-2. **Config file** — `lyingdocs.toml` in project root, or `~/.config/lyingdocs/config.toml`
-3. **Environment variables** / `.env`
-4. **CLI arguments**
-
-Hermes and Argus are configured independently, so you can use:
-
-* a cheaper planning model for Hermes
-* a stronger coding / investigation model for Argus
-* different providers or endpoints for each agent
-
-### Config file example
-
-Example configs live in [tests/configs](https://github.com/KMing-L/lying-docs/tree/main/tests/configs).
-
-```toml
-[hermes]
-model = "gpt-5.4"
-base_url = "https://api.openai.com/v1"
-# api_key_env = "OPENAI_API_KEY"  # optional — defaults to OPENAI_API_KEY
-
-[argus]
-backend = "local"           # "codex" | "claude_code" | "local"
-model = "gpt-5.4"
-base_url = "https://api.openai.com/v1"
-# api_key_env = "OPENAI_API_KEY"
-
-# Only read when argus.backend = "codex"
-[argus.codex]
-provider = "openai"
-wire_api = "responses"
-# path = "/usr/local/bin/codex"   # optional: explicit codex binary path
-
-# Only read when argus.backend = "claude_code"
-[argus.claude_code]
-# path = "/usr/local/bin/claude"  # optional: explicit claude binary path
-
-# Only read when argus.backend = "local"
-[argus.local]
-max_iterations = 25         # per-task agent loop cap
-max_read_bytes = 200000     # per read_file call
-
-[limits]
-max_dispatches = 20         # max Argus dispatches per Hermes run
-max_iterations = 50         # max Hermes loop iterations
-argus_task_timeout = 1200   # seconds per Argus task (codex / claude_code backends)
-token_budget = 524288       # Hermes context budget before compression
-```
-
-### Environment variables
-
-| Variable                 | Description                                    |
-| ------------------------ | ---------------------------------------------- |
-| `OPENAI_API_KEY`         | Required unless overridden via `api_key_env`   |
-| `HERMES_MODEL`           | Hermes model name                              |
-| `HERMES_BASE_URL`        | Hermes API base URL                            |
-| `ARGUS_BACKEND`          | `codex`, `claude_code`, or `local`             |
-| `ARGUS_MODEL`            | Argus model name                               |
-| `ARGUS_BASE_URL`         | Argus API base URL                             |
-| `ARGUS_CODEX_PROVIDER`   | Codex backend provider                         |
-| `ARGUS_CODEX_WIRE_API`   | Codex backend wire API (`responses` or `chat`) |
-| `ARGUS_CODEX_PATH`       | Explicit path to `codex`                       |
-| `ARGUS_CLAUDE_CODE_PATH` | Explicit path to `claude`                      |
-| `ARGUS_TASK_TIMEOUT`     | Timeout per Argus task in seconds              |
-| `TOKEN_BUDGET`           | Hermes context budget before compression       |
-
----
-
-## Argus backends
-
-Argus is the deep code analysis side of the system.
-
-### `local`
-
-No external CLI required.
-Uses a built-in agent loop with filesystem tools and an OpenAI-compatible API.
-
-Good default for getting started.
-
-```toml
-[argus]
-backend = "local"
-model = "gpt-5.4"
-base_url = "https://api.openai.com/v1"
-```
-
-### `codex`
-
-Uses [OpenAI Codex CLI](https://github.com/openai/codex).
-
-```bash
-npm install -g @openai/codex
-```
-
-```toml
-[argus]
-backend = "codex"
-
-[argus.codex]
-provider = "openai"
-wire_api = "responses"
-```
-
-Resolution order:
-
-1. explicit path from config
-2. system `PATH`
-3. local `node_modules/.bin/codex`
-
-### `claude_code`
-
-Uses [Claude Code](https://docs.anthropic.com/claude/docs/claude-code).
-
-```toml
-[argus]
-backend = "claude_code"
-model = "claude-sonnet-4-6"
-
-[argus.claude_code]
-# path = "/usr/local/bin/claude"
-```
-
-Invoked as:
-
-```bash
-claude -p <prompt> --model <argus_model> --output-format text
-```
-
-with `cwd` set to your code root.
-
----
-
-## CLI reference
-
-```bash
-# Full analysis
-lyingdocs analyze --doc-path docs/ --code-path . -o output/audit
-
-# Choose Argus backend
-lyingdocs analyze --doc-path docs/ --code-path . --argus-backend=local
+## GitHub Actions
 
-# Different models for Hermes and Argus
-lyingdocs analyze --doc-path docs/ --code-path . \
-  --hermes-model gpt-5.4 \
-  --argus-model gpt-5.4
-
-# Resume interrupted analysis
-lyingdocs analyze --doc-path docs/ --code-path . --resume
-
-# Use an explicit config file
-lyingdocs analyze --doc-path docs/ --code-path . --config myconfig.toml
-
-# Generate GitHub issue drafts
-lyingdocs analyze --doc-path docs/ --code-path . --gen-issue
-
-# Show version
-lyingdocs version
-```
-
-Available flags:
-
-`--hermes-model`, `--hermes-base-url`, `--argus-backend {codex,claude_code,local}`, `--argus-model`, `--argus-base-url`, `--argus-codex-provider`, `--argus-codex-wire-api`, `--max-dispatches`, `--max-iterations`, `--config`, `--resume`, `--gen-issue`
-
----
-
-## Generating GitHub issue drafts
-
-Pass `--gen-issue` to automatically draft a GitHub issue after analysis:
+LyingDocs runs natively in GitHub Actions as a trust gate for your CI pipeline.
 
 ```bash
-lyingdocs analyze --doc-path docs/ --code-path . --gen-issue
-```
-
-LyingDocs uses Hermes to synthesize findings into a single, polite GitHub issue and saves it to `issue.json` in the output directory.
-
-The file contains:
-
-* **`title`** — a short issue title
-* **`body`** — a GitHub-flavored Markdown issue body listing findings, code references, doc references, and a note acknowledging possible false positives
-
-You can post it directly with the [`gh` CLI](https://cli.github.com/):
-
-```bash
-gh issue create \
-  --title "$(jq -r '.title' output/issue.json)" \
-  --body  "$(jq -r '.body'  output/issue.json)"
+pip install lyingdocs
+lyingdocs init-ci --doc-path docs/ --backend claude_code --claude-oauth --trigger tag,manual
 ```
 
-This makes LyingDocs useful not only as an audit tool, but as a bridge into repository maintenance workflows.
-
----
-
-## GitHub Actions direction
-
-LyingDocs is moving toward a natural next step:
-
-**continuous trust enforcement inside GitHub Actions**
+This generates a workflow that:
 
-The long-term shape of the project is not “run this manually forever.”
-The long-term shape is:
+* audits docs-vs-code alignment on every tag push (or on demand)
+* posts findings as a PR comment
+* optionally requires manual approval before merging
 
-* run on pull requests
-* comment on suspicious docs/code drift
-* warn maintainers before release
-* surface trust regressions early
-* make repository truthfulness part of CI
+Supports all three backends (`local`, `codex`, `claude_code`) and both API key and OAuth token authentication for Claude Code.
 
-That is where LyingDocs becomes most valuable: not only as an analyzer, but as infrastructure.
+See the [full setup guide](docs/guides/github-actions.md) for trigger options, approval gates, and backend configuration.
 
 ---
 
@@ -387,7 +205,7 @@ That is where LyingDocs becomes most valuable: not only as an analyzer, but as i
 
 * [x] **Multi-harness support** — Argus runs on Codex, Claude Code, or a built-in local agent
 * [x] **Issue generation** — `--gen-issue` drafts GitHub issues from findings
-* [ ] **GitHub Action integration** — run LyingDocs automatically in PRs and CI to catch trust regressions as they are introduced
+* [x] **GitHub Action integration** — `lyingdocs init-ci` generates a ready-to-use workflow with configurable triggers, backend selection, PR comments, and manual approval gates
 * [ ] **One-session memory support** — Argus backends retain state across tasks for deeper multi-step investigations
 * [ ] **Deeper analysis** — multi-hop reasoning across doc hierarchies and version-aware diffing to detect when code changed but docs did not
 * [ ] **Paper mode** — treat academic papers as documentation and detect paper-to-code misalignment

{lyingdocs-0.1.3 → lyingdocs-0.1.4}/lyingdocs/argus_local.py

@@ -9,7 +9,7 @@ import logging
 import re
 from pathlib import Path
 
-from .llm import call_llm_with_tools, make_client
+from .llm import LLMResponse, call_llm_with_tools, make_client
 
 logger = logging.getLogger("lyingdocs")
 
@@ -126,9 +126,11 @@ class LocalArgus:
     def __init__(self, config: dict, code_path: Path):
         self.config = config
         self.code_root = code_path.resolve()
+        self.provider = config.get("argus_provider", "openai")
         self.client = make_client(
             api_key=config["argus_api_key"],
             base_url=config["argus_base_url"],
+            provider=self.provider,
         )
         self.model = config["argus_model"]
         self.max_iterations = int(config.get("argus_local_max_iterations", 25))
@@ -149,7 +151,8 @@ class LocalArgus:
         for iteration in range(1, self.max_iterations + 1):
             logger.info("  Argus(local) iter %d/%d", iteration, self.max_iterations)
             response = call_llm_with_tools(
-                self.client, self.model, messages, ARGUS_LOCAL_TOOL_SCHEMAS
+                self.client, self.model, messages, ARGUS_LOCAL_TOOL_SCHEMAS,
+                provider=self.provider,
             )
             messages.append(self._response_to_message(response))
 

{lyingdocs-0.1.3 → lyingdocs-0.1.4}/lyingdocs/cli.py

@@ -159,6 +159,96 @@ examples:
     )
     analyze_parser.set_defaults(func=cmd_analyze)
 
+    # -- init-ci subcommand --
+    init_ci_parser = subparsers.add_parser(
+        "init-ci",
+        help="Generate a GitHub Actions workflow for LyingDocs CI",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""\
+examples:
+  lyingdocs init-ci --doc-path docs/ --code-path .
+  lyingdocs init-ci --doc-path docs/ --backend claude_code --trigger tag
+  lyingdocs init-ci --doc-path docs/ --trigger pr,tag --approval
+  lyingdocs init-ci --doc-path docs/ --trigger tag,manual -o .
+""",
+    )
+    init_ci_parser.add_argument(
+        "--doc-path", default="docs/",
+        help="Documentation root directory (default: docs/)",
+    )
+    init_ci_parser.add_argument(
+        "--code-path", default=".",
+        help="Code repository root (default: .)",
+    )
+    init_ci_parser.add_argument(
+        "--backend", choices=("local", "codex", "claude_code"), default="local",
+        help="Argus backend (default: local)",
+    )
+    init_ci_parser.add_argument(
+        "--trigger", default="pr,tag",
+        help=(
+            "Comma-separated triggers: pr, tag, manual, schedule "
+            "(default: pr,tag)"
+        ),
+    )
+    init_ci_parser.add_argument(
+        "--branch", default="main",
+        help="Target branch for PR trigger (default: main)",
+    )
+    init_ci_parser.add_argument(
+        "--cron", default="0 9 * * 1",
+        help="Cron expression for schedule trigger (default: '0 9 * * 1')",
+    )
+    init_ci_parser.add_argument(
+        "--approval", action="store_true",
+        help="Add a manual approval step (requires GitHub Environment setup)",
+    )
+    init_ci_parser.add_argument(
+        "--no-comment", action="store_true",
+        help="Disable automatic PR comment with findings",
+    )
+    init_ci_parser.add_argument(
+        "--claude-oauth", action="store_true",
+        help=(
+            "Use Claude OAuth token instead of API key for claude_code backend. "
+            "Pro/Max users can use subscription quota instead of per-API-call billing. "
+            "Generate token with: claude setup-token"
+        ),
+    )
+    init_ci_parser.add_argument(
+        "--gen-issue", action="store_true",
+        help="Generate GitHub issue drafts from findings",
+    )
+    init_ci_parser.add_argument(
+        "--hermes-provider", choices=("openai", "anthropic"), default=None,
+        help=(
+            "LLM provider for Hermes: openai or anthropic. "
+            "Default: anthropic when backend=claude_code, otherwise openai"
+        ),
+    )
+    init_ci_parser.add_argument(
+        "--hermes-model", default=None,
+        help="Override Hermes LLM model",
+    )
+    init_ci_parser.add_argument(
+        "--argus-model", default=None,
+        help="Override Argus LLM model",
+    )
+    init_ci_parser.add_argument(
+        "--action-ref", default="KMing-L/lyingdocs@v1",
+        help="GitHub Action reference (default: KMing-L/lyingdocs@v1)",
+    )
+    init_ci_parser.add_argument(
+        "--output", "-o", default=".",
+        help=(
+            "Output path. If a directory, writes to "
+            "<dir>/.github/workflows/lyingdocs.yml (default: .)"
+        ),
+    )
+
+    from .init_ci import cmd_init_ci
+    init_ci_parser.set_defaults(func=cmd_init_ci)
+
     # -- version subcommand --
     version_parser = subparsers.add_parser("version", help="Show version")
     version_parser.set_defaults(func=cmd_version)