secaudit 0.1.0 → 0.1.1

package/README.md

@@ -38,13 +38,43 @@ npm run dev -- analyze-10k --ticker MSFT --year 2023 --source url \
 The system interprets natural language. Required steps may be skipped — the ledger exposes this gap.
 
 ```bash
-# Intent-based — may skip validation
+# Heuristic intent routing — keyword-based, no API key needed
 npm run dev -- intent "analyze apple 10-k for 2023 and summarize risks"
 
 # Override ticker/year if intent parsing misses
 npm run dev -- intent "summarize tesla financial risks" --ticker TSLA --year 2023
 ```
 
+### LLM Intent Mode (Real GPT Routing)
+
+For a realistic demonstration, you can route intent through OpenAI GPT-4o-mini. The LLM receives the list of workflow steps and decides which ones to run — no hints to skip.
+
+```bash
+# LLM decides which steps to execute
+npm run dev -- intent "summarize apple 2023 risk factors" --llm
+
+# Use a different model
+npm run dev -- intent "summarize apple 2023 risk factors" --llm --model gpt-4o
+```
+
+This requires an `OPENAI_API_KEY`. See [Environment Setup](#environment-setup) below.
+
+## Environment Setup
+
+Copy the example file and add your key:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env`:
+
+```
+OPENAI_API_KEY=sk-your-key-here
+```
+
+The OpenAI key is **optional**. It is only needed for `--llm` mode. Command mode and heuristic intent mode work without any API keys — SEC EDGAR is a free public API that requires no authentication.
+
 ## CLI Reference
 
 ```
@@ -63,6 +93,12 @@ Options (analyze-10k):
   --no-strict               Lower confidence thresholds
   --no-cache                Skip document cache
   --invocation-id <string>  Explicit invocation ID
+
+Options (intent):
+  --llm                     Route intent through OpenAI GPT (requires OPENAI_API_KEY)
+  --model <model>           OpenAI model (default: gpt-4o-mini)
+  --ticker <string>         Optional ticker override
+  --year <number>           Optional year override
 ```
 
 ## Workflow: `analyze_10k_v1`
@@ -116,7 +152,8 @@ src/
     workflow.ts             Step definitions for analyze_10k_v1
     types.ts                Core type definitions
   intent-router/
-    router.ts               Keyword-based intent classifier
+    router.ts               Keyword-based intent classifier (no API key)
+    llm-router.ts           OpenAI GPT intent router (optional, --llm flag)
     patterns.ts             Ticker/year extraction patterns
   tools/
     fetcher.ts              SEC EDGAR fetch + caching
@@ -145,6 +182,6 @@ npm test             # Run tests
 
 ## Data Source
 
-Uses the [SEC EDGAR API](https://www.sec.gov/developer) to fetch public 10-K filings. All requests comply with SEC rate limits (<10 req/sec) and include a User-Agent header.
+Uses the [SEC EDGAR](https://www.sec.gov/developer) public API to fetch 10-K filings. No API key or authentication is required — EDGAR is a free, open government data source. All requests comply with SEC rate limits (<10 req/sec) and include a required User-Agent header with a contact email.
 
 Fetched documents are cached in `.cache/` for offline use.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "secaudit",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Deterministic 10-K filing analyzer — command-driven vs intent-based invocation. Proves that intent-based invocation is probabilistic; command-driven invocation is deterministic and auditable.",
   "type": "module",
   "bin": {