html-reader-llm 0.0.1__tar.gz → 0.0.2__tar.gz

html_reader_llm-0.0.2/.env.example

@@ -0,0 +1,12 @@
+# htmlreader environment variables
+
+# LLM API configuration
+HTMLREADER_LLM_BASE_URL=
+HTMLREADER_LLM_API_KEY=
+HTMLREADER_LLM_MODEL=
+
+# Optional overrides
+# HTMLREADER_LLM_MAX_TOKENS=512000
+# HTMLREADER_HTTP_TIMEOUT=15
+# HTMLREADER_CHROME_TIMEOUT=30
+# HTMLREADER_CHROME_PATH=

html_reader_llm-0.0.2/.gitignore

@@ -0,0 +1,230 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# claude
+.claude/specs/
+.claude/
+
+# zcode
+.zcode/
+
+# env files
+.env
+
+# temporary files
+.cache/
+.temp/

html_reader_llm-0.0.2/.python-version

@@ -0,0 +1 @@
+3.12

html_reader_llm-0.0.2/AGENTS.md

@@ -0,0 +1,102 @@
+# 项目上下文 (AI Agent 指令)
+
+## 基本信息
+
+- **项目**：htmlreader — 智能 HTML 解析与提取库
+- **阶段**：Phase 1（核心功能开发）
+- **技术栈**：Python 3.12+ / uv / httpx2 / selectolax
+- **语言**：中文优先
+
+## 常用命令
+
+```bash
+uv venv && uv sync       # 安装依赖
+uv run htmlreader        # CLI
+uv build                 # 构建
+```
+
+## 架构
+
+```
+输入 URL/HTML
+  │
+  ├─ 自定义简化流程（后续参考草稿+开源代码）─→ minify-html ─→ LLM 分析结构
+  │
+  ├─ 普通请求 vs 浏览器渲染 ─→ 差异度计算 + 文本统计
+  │
+  ├─ httpx2 请求 ─→ LLM（页面分类 / CSS 选择器规则生成）
+  │                 └─ tranfilatura 辅助元数据提取
+  │
+  └─ 自定义 CSS 提取语法 ─→ 低代码提取工作流
+```
+
+## 设计决策（探索阶段）
+
+### HTML 简化
+- minify-html 是喂给 LLM 之前的最后一步压缩
+- 中间有自定义简化步骤，后续提供草稿代码 + 大量开源代码学习后确定
+
+### 浏览器渲染判断
+- 不用框架，用 Chrome 原生 `--dump-dom` 管道获取渲染后 HTML
+- 第一版让用户填入 Chrome 路径（或 auto 自动查找）
+- 关键参数：
+  - `--virtual-time-budget=` 预估等待 JS 异步加载
+  - `--disable-gpu`
+  - `--run-all-compositor-stages-before-draw`
+  - `--user-agent="指定的 UA"`
+  - `--headless`
+  - `--timeout=毫秒数`
+  - `--blink-settings=imagesEnabled=false` 禁用图片减少流量
+  - `--user-data-dir=` 缓存用户数据，减少重复加载
+- 纯管道模式，不走 CDP 协议（后续可扩展）
+- 渲染后 HTML 与 httpx2 结果对比，统计文本差异度
+
+### CSS 提取语法（草稿）
+- 三个核心字段：
+  - `selector`：CSS 选择器
+  - `value_mode`：取值方式
+    - `$html`：取元素内部完整 HTML
+    - `$text`：取纯文本（去标签）
+    - `@attribute`：取指定属性值（如 `@href`、`@src`）
+- 交互形式（YAML / 链式 API / LLM 生成）后续再定
+
+## 核心需求
+
+### 1. HTML 简化（供 LLM 分析）
+- 将原始 HTML 转换为适合 LLM 理解的简化格式
+- 保留结构语义，去除噪声（样式、脚本、无用属性）
+
+### 2. 渲染方式判断
+- 对同一 URL，分别用普通 HTTP 请求和浏览器渲染获取结果
+- 计算差异度（DOM 结构、文本量）
+- 统计文本长度，判断是否需要浏览器渲染
+- 输出决策：`use_browser: bool`
+
+### 3. LLM 驱动的智能分析
+- 使用 httpx2 发送 HTTP 请求与 LLM 通信
+- **页面分类**：识别 `list`（列表页）/ `detail`（详情页）
+- **CSS 选择器规则生成**：
+  - list 页：提取列表规则
+  - detail 页：提取正文 + 元数据规则
+- **tranfilatura 协作**：提取元数据作为 LLM 上下文，提高选择器准确度
+
+### 4. CSS 提取语法工作流
+- 自定义一套文本化的 CSS 提取规则语法
+- 低代码方式描述网页内容提取逻辑
+- 支持组合、嵌套、条件选择
+- 规则可序列化、可存储、可复用
+
+## 依赖说明
+
+| 依赖 | 用途 |
+|---|---|
+| `httpx2` | 异步 HTTP 客户端，用于下载页面及 LLM API 通信 |
+| `selectolax` | 高性能 HTML 解析（基于 Modest/Lexbor） |
+| `minify-html` | HTML 极致压缩，缩短 LLM 提示词长度 |
+
+## 关键概念
+
+- **页面分类**：`list`（列表/索引页）vs `detail`（内容/详情页）
+- **差异度**：普通请求与浏览器渲染结果的 DOM/文本相似度
+- **提取规则**：文本化 CSS 选择器组合，描述从 HTML 中提取目标数据的逻辑
+- **简化格式**：去除样式噪声后的 HTML，保留结构语义供 LLM 理解

{html_reader_llm-0.0.1 → html_reader_llm-0.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: html-reader-llm
-Version: 0.0.1
+Version: 0.0.2
 Summary: HTML simplification and intelligent extraction for LLM
 Author-email: Clericpy <clericpy@gmail.com>
 Requires-Python: >=3.12

html_reader_llm-0.0.2/openspec/changes/chrome-path-detection/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-01

html_reader_llm-0.0.2/openspec/changes/chrome-path-detection/design.md

@@ -0,0 +1,60 @@
+## Context
+
+The browser rendering feature needs a Chrome/Edge path. Users may not know where their browser is installed, so automatic detection is essential. The provided draft code in the conversation demonstrates the core approach: platform-specific path lists + verification.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Standalone `browser.py` module, zero external dependencies (stdlib only)
+- Three usage modes: list all paths, auto-select first, validate user path
+- ENV override via `HTMLREADER_CHROME_PATH`
+- Cross-platform: Windows, Linux, macOS
+
+**Non-Goals:**
+- Browser version comparison or feature detection
+- CDP protocol connection (deferred to browser rendering stage)
+- Browser installation/download
+- Firefox or other browsers (Chrome/Edge only)
+
+## Decisions
+
+### 1. Detection strategy: file existence + --version verification
+
+**Decision:** On Windows, check known paths via `os.path.isfile()`. On Linux/macOS, check PATH-based commands via `[cmd, "--version"]` subprocess call (timeout 2s). Match output prefix to confirm it's actually Chrome/Edge (not another binary with the same name).
+
+**Rationale:** File existence is fast and reliable for fixed Windows paths. `--version` verification prevents false positives on Linux where a script might be named `google-chrome` but not actually be Chrome.
+
+**Alternative considered:** Only check file existence on all platforms. Rejected — Linux/macOS binaries on PATH need verification to avoid false matches.
+
+### 2. Path list deduplication + mtime sorting
+
+**Decision:** Collect all found paths into a set (dedup), resolve to absolute, sort by `os.path.getmtime()` descending (newest first).
+
+**Rationale:** Users with multiple Chrome versions (stable/beta/dev) want the newest. Set dedup handles cases where the same binary is found via multiple detection methods.
+
+### 3. Module structure
+
+**Decision:** Single file `src/htmlreader/browser.py` with these public functions:
+- `detect_browser_paths() -> list[str]` — list all found paths
+- `get_browser_path() -> str | None` — auto-select first, or None
+- `validate_browser_path(path: str) -> str` — validate user path, raise if invalid
+
+**Rationale:** Three clear functions for three usage modes. The `get_browser_path()` function checks ENV first, then falls back to auto-detect.
+
+### 4. Error handling
+
+**Decision:** Custom `BrowserNotFoundError` exception (not `ChromeNotFoundError` — we also detect Edge).
+
+**Rationale:** The name should reflect what we're actually looking for (browsers, not just Chrome).
+
+### 5. ENV integration
+
+**Decision:** `get_browser_path()` checks `HTMLREADER_CHROME_PATH` first. If set, validate it and return. If not set, fall back to auto-detect.
+
+**Rationale:** ENV override lets users pin a specific browser without code changes. Consistent with the `HTMLREADER_*` convention from settings.py.
+
+## Risks / Trade-offs
+
+- **[False negatives on unusual install paths]** → Mitigated by supporting both fixed paths and PATH-based detection
+- **[Subprocess timeout on slow systems]** → 2s timeout is generous; if it times out, that binary is skipped
+- **[mtime doesn't always correlate with "best" browser]** → Acceptable heuristic for first version; users can override via ENV or explicit path

html_reader_llm-0.0.2/openspec/changes/chrome-path-detection/proposal.md

@@ -0,0 +1,25 @@
+## Why
+
+The browser rendering feature requires a Chrome/Edge browser path. Users can provide an explicit path, but most will prefer automatic detection. The system needs to discover installed Chrome/Edge executables on the current platform, validate user-provided paths, and expose the detection as a standalone module that other features can import.
+
+## What Changes
+
+- **New module**: `src/htmlreader/browser.py` — Chrome/Edge path detection
+- **Auto-detect**: Platform-aware search (Windows/Linux/macOS) for Chrome and Edge executables
+- **Three modes**: list all found paths, auto-select first match, validate user-provided path
+- **ENV support**: `HTMLREADER_CHROME_PATH` overrides auto-detection
+- **Test file**: `tests/test_browser.py` — detection + validation tests
+
+## Capabilities
+
+### New Capabilities
+- `chrome-path-detection`: Platform-aware Chrome/Edge path discovery, validation, and selection
+
+### Modified Capabilities
+<!-- None -->
+
+## Impact
+
+- New files: `src/htmlreader/browser.py`, `tests/test_browser.py`
+- Modified: `src/htmlreader/__init__.py` (public API export)
+- No new dependencies (stdlib only: `os`, `platform`, `subprocess`, `shutil`)

html_reader_llm-0.0.2/openspec/changes/chrome-path-detection/specs/chrome-path-detection/spec.md

@@ -0,0 +1,93 @@
+## Purpose
+
+Provides platform-aware Chrome/Edge browser path discovery, validation, and selection for the browser rendering feature.
+
+## ADDED Requirements
+
+### Requirement: Platform-aware browser detection
+The system SHALL detect installed Chrome and Edge executables on the current platform (Windows, Linux, macOS). On Windows, it SHALL check known installation paths and use `os.path.isfile()` to verify existence. On Linux, it SHALL check PATH-based commands via `--version` output. On macOS, it SHALL check known application bundle paths.
+
+#### Scenario: Windows Chrome found
+- **WHEN** Chrome is installed at a known Windows path
+- **THEN** that path appears in the detected paths list
+
+#### Scenario: Linux Chrome found
+- **WHEN** `google-chrome-stable` is available on PATH
+- **THEN** its absolute path appears in the detected paths list
+
+#### Scenario: macOS Chrome found
+- **WHEN** Chrome is installed at `/Applications/Google Chrome.app/...`
+- **THEN** that path appears in the detected paths list
+
+#### Scenario: No browser found
+- **WHEN** no Chrome or Edge installation is detected
+- **THEN** an empty list is returned
+
+---
+
+### Requirement: Path list with ordering
+The system SHALL return all detected browser paths sorted by modification time (newest first). Each path SHALL be an absolute, resolved path.
+
+#### Scenario: Multiple browsers found
+- **WHEN** both Chrome and Edge are installed
+- **THEN** both paths are returned, sorted by mtime descending
+
+#### Scenario: Paths are absolute
+- **WHEN** a browser is found via a relative PATH command on Linux
+- **THEN** the returned path is resolved to absolute
+
+---
+
+### Requirement: Auto-select first path
+The system SHALL provide a function that returns the first detected browser path (newest by mtime), or `None` if no browser is found.
+
+#### Scenario: Auto-select with browsers present
+- **WHEN** multiple browsers are installed
+- **THEN** the function returns the path with the most recent modification time
+
+#### Scenario: Auto-select with no browsers
+- **WHEN** no browser is found
+- **THEN** the function returns `None`
+
+---
+
+### Requirement: User path validation
+The system SHALL validate a user-provided browser path. It SHALL check that the file exists and is a valid executable. If invalid, it SHALL raise a clear error.
+
+#### Scenario: Valid user path
+- **WHEN** user provides a path that exists on disk
+- **THEN** the path is returned as-is (resolved to absolute)
+
+#### Scenario: Invalid user path
+- **WHEN** user provides a path that does not exist
+- **THEN** a `BrowserNotFoundError` is raised with a descriptive message
+
+---
+
+### Requirement: ENV override
+The system SHALL respect `HTMLREADER_CHROME_PATH` environment variable. When set, it overrides auto-detection and is used directly (after validation).
+
+#### Scenario: ENV path set and valid
+- **WHEN** `HTMLREADER_CHROME_PATH=/usr/bin/google-chrome` is set and the file exists
+- **THEN** that path is returned without scanning
+
+#### Scenario: ENV path set but invalid
+- **WHEN** `HTMLREADER_CHROME_PATH=/nonexistent` is set
+- **THEN** a `BrowserNotFoundError` is raised
+
+---
+
+### Requirement: Edge browser support
+The system SHALL detect Microsoft Edge in addition to Google Chrome, on all supported platforms.
+
+#### Scenario: Edge on Windows
+- **WHEN** Edge is installed at `C:/Program Files/Microsoft/Edge/Application/msedge.exe`
+- **THEN** that path is detected
+
+#### Scenario: Edge on Linux
+- **WHEN** `microsoft-edge-stable` is available on PATH
+- **THEN** its path is detected
+
+#### Scenario: Edge on macOS
+- **WHEN** Edge is installed at `/Applications/Microsoft Edge.app/...`
+- **THEN** that path is detected

html_reader_llm-0.0.2/openspec/changes/chrome-path-detection/tasks.md

@@ -0,0 +1,25 @@
+## 1. Module setup
+
+- [ ] 1.1 Create `src/htmlreader/browser.py` with platform path constants (WIN32_PATHS, LINUX_PATHS, DARWIN_PATHS)
+- [ ] 1.2 Define `BrowserNotFoundError` exception
+
+## 2. Detection functions
+
+- [ ] 2.1 Implement `_iter_browser_paths()` — platform-aware iterator yielding found paths
+- [ ] 2.2 Implement `detect_browser_paths() -> list[str]` — dedup, resolve to absolute, sort by mtime descending
+- [ ] 2.3 Implement `get_browser_path() -> str | None` — check ENV first, then auto-select first detected
+- [ ] 2.4 Implement `validate_browser_path(path: str) -> str` — validate user path, raise BrowserNotFoundError if invalid
+
+## 3. Public API
+
+- [ ] 3.1 Export `BrowserNotFoundError`, `detect_browser_paths`, `get_browser_path`, `validate_browser_path` from `src/htmlreader/__init__.py`
+
+## 4. Tests
+
+- [ ] 4.1 Test detect_browser_paths returns list on current platform
+- [ ] 4.2 Test get_browser_path returns path or None (no crash)
+- [ ] 4.3 Test validate_browser_path with valid path
+- [ ] 4.4 Test validate_browser_path with invalid path raises BrowserNotFoundError
+- [ ] 4.5 Test ENV override: HTMLREADER_CHROME_PATH set to valid path
+- [ ] 4.6 Test ENV override: HTMLREADER_CHROME_PATH set to invalid path raises error
+- [ ] 4.7 Test platform constants are non-empty for each OS

html_reader_llm-0.0.2/openspec/changes/dotenv-config/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-02

html_reader_llm-0.0.2/openspec/changes/llm-analysis/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-02

html_reader_llm-0.0.2/openspec/changes/llm-analysis/design.md

@@ -0,0 +1,108 @@
+## Context
+
+The project has HTML simplification (`simplify.py`), render detection (`render_detect.py`), and browser path detection (`browser.py`). The next layer is LLM intelligence: send simplified HTML to an LLM, get back page classification and CSS selector rules.
+
+## Goals / Non-Goals
+
+**Goals:**
+- OpenAI-compatible API via httpx2
+- trafilatura metadata as LLM prompt context
+- Page classification (list/detail)
+- CSS selector rule generation for both page types
+- Prompt budget management (<50% of context window)
+- CLI `analyze` command
+
+**Non-Goals:**
+- Streaming responses
+- Multi-turn conversation
+- Rule execution (just generation)
+- Rule storage/persistence
+- Multiple LLM provider fallback
+
+## Decisions
+
+### 1. HTTP client for LLM: httpx2
+
+**Decision:** Use httpx2 for LLM API communication.
+
+**Rationale:** Already a project dependency. Supports async (future), proper timeout, and JSON handling.
+
+### 2. API format: OpenAI chat completions
+
+**Decision:** Use `/v1/chat/completions` with `response_format: { type: "json_object" }`.
+
+**Rationale:** Widely compatible with most LLM providers. JSON mode ensures structured output.
+
+### 3. Prompt structure
+
+**Decision:** Three-part prompt:
+1. System prompt: role definition + output format instructions
+2. trafilatura metadata: extracted fields as context
+3. Simplified HTML: the page content
+
+```python
+system = """You are an HTML analysis expert. Analyze the given HTML and return JSON with:
+- page_type: "list" or "detail"
+- metadata: {title, author, date, ...} from trafilatura
+- rules: CSS selector extraction rules
+  - list: [{name, is_main, selectors: {title, link, pubtime}}]
+  - detail: {title, author, date, description, image, categories, tags, content}
+"""
+
+user = f"""Metadata (from trafilatura):
+{metadata_json}
+
+HTML:
+{simplified_html}
+"""
+```
+
+### 4. Prompt budget: 50% of max_tokens
+
+**Decision:** Estimate token count as `len(text) / 3` (rough CJK/English average). If HTML exceeds 50% of max_tokens, truncate from the middle, keeping head and tail.
+
+**Rationale:** Middle truncation preserves page structure (header/nav at top, footer at bottom) while cutting the bulk content.
+
+### 5. trafilatura integration: extract before simplify
+
+**Decision:** Run trafilatura on the **raw** HTML (before simplification), because trafilatura's parsers expect full HTML with metadata tags. The simplified HTML goes to LLM.
+
+**Order:** raw HTML → trafilatura (metadata) + simplify (HTML) → LLM prompt
+
+### 6. Result structure: TypedDict
+
+```python
+class ListRule(TypedDict):
+    name: str           # "main", "sidebar", etc.
+    is_main: bool
+    selectors: dict[str, str]  # title, link, pubtime CSS selectors
+
+class DetailRules(TypedDict):
+    # Each field is Optional CSS selector string
+    title: str | None
+    author: str | None
+    date: str | None
+    description: str | None
+    image: str | None
+    categories: str | None
+    tags: str | None
+    content: str | None
+
+class AnalysisResult(TypedDict):
+    page_type: str           # "list" or "detail"
+    metadata: dict           # trafilatura metadata
+    list_rules: list[ListRule] | None
+    detail_rules: DetailRules | None
+    raw_llm_response: str
+```
+
+### 7. Error handling
+
+**Decision:** If LLM returns invalid JSON, log warning and return result with `raw_llm_response` filled but rules as None. If LLM request fails, raise with clear error message.
+
+## Risks / Trade-offs
+
+- **[Token estimation inaccuracy]** → `len/3` is rough; may over-truncate or under-truncate. Mitigated by logging actual token usage from API response.
+- **[trafilatura metadata quality]** → Some sites have poor metadata. LLM can still work without it, just less accurate.
+- **[LLM hallucination in selectors]** → Generated selectors may not exist in the HTML. Downstream validation needed (not in this change).
+- **[Cost]** → Each analysis is one LLM call. Budget management prevents runaway costs.