jevhttp 0.1.0__tar.gz

jevhttp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 XUEHANG AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jevhttp-0.1.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: jevhttp
+Version: 0.1.0
+Summary: Synchronous HTTP client and structured web decision toolkit for OpenAI-compatible models
+Author-email: XUEHANGAI <xuehang.ai@outlook.com>
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai>=3.16.2
+Requires-Dist: pydantic>=2.7
+Requires-Dist: requests>=2.34.2
+Dynamic: license-file
+
+# jevhttp
+
+[English README](README.en.md)
+
+`jevhttp` 是一个本地模型优先的同步HTTP与结构化决策工具包。
+
+它把网页请求、网页元数据抽取和OpenAI-compatible模型决策组合成一个轻量Python接口。
+
+主要用于本地模型推理，同时兼容在线OpenAI-compatible推理服务。
+
+## 为什么使用 jevhttp
+
+传统网页采集通常需要分别处理HTTP请求、HTML解析、链接发现和业务分类。
+
+`jevhttp`将这些步骤组合起来，让网页分类、相关性判断和后续动作成为可校验的结构化结果，而不是自由文本。
+
+```text
+HTTP请求 → Page网页对象 → 精简State → 结构化决策 → 业务结果
+```
+
+模型不会直接访问网页。程序负责获取和清洗网页，模型只处理用户明确提供的State。
+
+## 安装
+
+项目发布到PyPI后，可以直接安装：
+
+```bash
+pip install jevhttp
+```
+
+从源码使用uv管理环境：
+
+```bash
+uv sync
+```
+
+## 快速开始
+
+```python
+from jevhttp import JevHttp
+
+client = JevHttp(
+    base_url='http://127.0.0.1:8000/v1',
+    api_key='EMPTY',
+    model='openbmb/MiniCPM5-2B',
+)
+
+page = client.get('https://example.com')
+state = [
+    {
+        '网址': page.final_url,
+        '标题': page.title,
+        '描述': page.description,
+        '状态码': page.status_code,
+    }
+]
+
+result = client.system_one(
+    state=state,
+    decisions={
+        '页面类型': client.choice(['文章页', '列表页', '其他']),
+        '是否相关': client.boolean('这个网页与当前任务相关吗？'),
+        '相关性': client.score('请评估网页相关性', min=0, max=10),
+    },
+)
+
+print(result['页面类型'])
+print(result['是否相关'])
+print(result['相关性'])
+print(result.decision_time)
+```
+
+`base_url`只用于模型API，不影响`client.get()`访问的网页地址。
+
+## 主要特性
+
+- 基于`requests.Session`的同步HTTP请求、连接复用、超时和有限重试
+- `Page`和`Link`网页对象，提供标题、描述、标题列表、正文、链接和HTTP响应信息
+- 自动把相对链接转换为绝对URL，并移除fragment和常见追踪参数
+- `system_one()`一次请求执行一个或多个结构化决策
+- 内置`Choice`、`Boolean`和`Score`决策类型
+- 中文优先的模型提示词和分类结果校验
+- 支持中文分类兜底项，避免小模型偶发同义词导致批处理终止
+- 支持Pydantic结构化抽取：`client.extract(state, Model)`
+- 支持带域名、深度、页数、robots.txt和内网地址保护的同步爬虫
+- 每次决策提供原始JSON、模型名称、Token使用量和决策耗时
+- 通过OpenAI-compatible接口兼容本地vLLM和远程模型服务
+
+## 适合做什么
+
+`jevhttp`适合需要“先获取网页，再进行结构化判断”的任务，例如：
+
+- 学校、机构、企业网站的页面类型识别
+- 新闻、文章、目录和详情页分类
+- 网页相关性筛选和采集入口发现
+- 本地小模型驱动的大规模网页预处理和批量决策
+- 将网页状态抽取为业务Pydantic模型
+- 对特定域名进行受限、可恢复的同步采集
+
+它不是浏览器自动化框架，也不负责JavaScript渲染、验证码绕过、代理池、数据库、向量数据库或分布式任务调度。
+
+## 性能验证
+
+以下数据来自本地vLLM部署`openbmb/MiniCPM5-2B`的批量网页决策验证，使用8个并发工作线程。实际速度会受到GPU、网络和网页响应时间影响。
+
+### 分阶段耗时
+
+| 阶段 | 任务 | 并发数 | 平均耗时 | 中位数 | P95 | 备注 |
+| --- | --- | ---: | ---: | ---: | ---: | --- |
+| HTTP | 请求网页并解析HTML | 8 | 2.875秒 | 2.752秒 | 4.071秒 | 包含网络耗时 |
+| Choice | 单项页面类型分类 | 1 | 0.376秒 | - | - | 本地小模型单次测试 |
+| Boolean | 单项布尔判断 | 1 | 0.362秒 | - | - | 本地小模型单次测试 |
+| Score | 单项相关性评分 | 1 | 0.398秒 | - | - | 本地小模型单次测试 |
+| Choice | 批量页面类型分类 | 8 | 0.125秒 | 0.108秒 | 0.238秒 | 9998次成功分类 |
+| 全流程 | 请求、解析、决策和落盘 | 8 | 约0.463秒/页 | - | - | 10000页约77分钟 |
+
+### 页面处理结果
+
+| 指标 | 数值 |
+| --- | ---: |
+| 处理页面数 | 10000 |
+| 成功分类页面 | 9998 |
+| 异常页面 | 2 |
+| 成功率 | 99.98% |
+| 唯一URL数量 | 10000 |
+| 主要详情页分类 | 8983 |
+| 主要列表页分类 | 1015 |
+
+测试代码位于`test/`目录，包含HTTP解析、Choice、Boolean、Score、多决策、性能基准和实时JSONL采集测试。
+
+## 版本范围
+
+当前版本优先保证同步调用和可预测行为，暂不包含：
+
+- asyncio和异步API
+- 浏览器渲染
+- Playwright和Selenium
+- 数据库和ORM
+- 向量数据库和RAG
+- 代理池、验证码绕过和分布式队列
+
+## 生态
+
+- [awesome-jev](https://github.com/kraayenjon/awesome-jev)
+- [Made with jev](https://madewithjev.com/)
+- [xuehang.ai](https://xuehang.ai/)
+
+## 许可证
+
+本项目采用[MIT License](LICENSE)。
+
+Copyright © 2026 [XUEHANG AI](https://xuehang.ai/)。

jevhttp-0.1.0/README.md

@@ -0,0 +1,152 @@
+# jevhttp
+
+[English README](README.en.md)
+
+`jevhttp` 是一个本地模型优先的同步HTTP与结构化决策工具包。
+
+它把网页请求、网页元数据抽取和OpenAI-compatible模型决策组合成一个轻量Python接口。
+
+主要用于本地模型推理，同时兼容在线OpenAI-compatible推理服务。
+
+## 为什么使用 jevhttp
+
+传统网页采集通常需要分别处理HTTP请求、HTML解析、链接发现和业务分类。
+
+`jevhttp`将这些步骤组合起来，让网页分类、相关性判断和后续动作成为可校验的结构化结果，而不是自由文本。
+
+```text
+HTTP请求 → Page网页对象 → 精简State → 结构化决策 → 业务结果
+```
+
+模型不会直接访问网页。程序负责获取和清洗网页，模型只处理用户明确提供的State。
+
+## 安装
+
+项目发布到PyPI后，可以直接安装：
+
+```bash
+pip install jevhttp
+```
+
+从源码使用uv管理环境：
+
+```bash
+uv sync
+```
+
+## 快速开始
+
+```python
+from jevhttp import JevHttp
+
+client = JevHttp(
+    base_url='http://127.0.0.1:8000/v1',
+    api_key='EMPTY',
+    model='openbmb/MiniCPM5-2B',
+)
+
+page = client.get('https://example.com')
+state = [
+    {
+        '网址': page.final_url,
+        '标题': page.title,
+        '描述': page.description,
+        '状态码': page.status_code,
+    }
+]
+
+result = client.system_one(
+    state=state,
+    decisions={
+        '页面类型': client.choice(['文章页', '列表页', '其他']),
+        '是否相关': client.boolean('这个网页与当前任务相关吗？'),
+        '相关性': client.score('请评估网页相关性', min=0, max=10),
+    },
+)
+
+print(result['页面类型'])
+print(result['是否相关'])
+print(result['相关性'])
+print(result.decision_time)
+```
+
+`base_url`只用于模型API，不影响`client.get()`访问的网页地址。
+
+## 主要特性
+
+- 基于`requests.Session`的同步HTTP请求、连接复用、超时和有限重试
+- `Page`和`Link`网页对象，提供标题、描述、标题列表、正文、链接和HTTP响应信息
+- 自动把相对链接转换为绝对URL，并移除fragment和常见追踪参数
+- `system_one()`一次请求执行一个或多个结构化决策
+- 内置`Choice`、`Boolean`和`Score`决策类型
+- 中文优先的模型提示词和分类结果校验
+- 支持中文分类兜底项，避免小模型偶发同义词导致批处理终止
+- 支持Pydantic结构化抽取：`client.extract(state, Model)`
+- 支持带域名、深度、页数、robots.txt和内网地址保护的同步爬虫
+- 每次决策提供原始JSON、模型名称、Token使用量和决策耗时
+- 通过OpenAI-compatible接口兼容本地vLLM和远程模型服务
+
+## 适合做什么
+
+`jevhttp`适合需要“先获取网页，再进行结构化判断”的任务，例如：
+
+- 学校、机构、企业网站的页面类型识别
+- 新闻、文章、目录和详情页分类
+- 网页相关性筛选和采集入口发现
+- 本地小模型驱动的大规模网页预处理和批量决策
+- 将网页状态抽取为业务Pydantic模型
+- 对特定域名进行受限、可恢复的同步采集
+
+它不是浏览器自动化框架，也不负责JavaScript渲染、验证码绕过、代理池、数据库、向量数据库或分布式任务调度。
+
+## 性能验证
+
+以下数据来自本地vLLM部署`openbmb/MiniCPM5-2B`的批量网页决策验证，使用8个并发工作线程。实际速度会受到GPU、网络和网页响应时间影响。
+
+### 分阶段耗时
+
+| 阶段 | 任务 | 并发数 | 平均耗时 | 中位数 | P95 | 备注 |
+| --- | --- | ---: | ---: | ---: | ---: | --- |
+| HTTP | 请求网页并解析HTML | 8 | 2.875秒 | 2.752秒 | 4.071秒 | 包含网络耗时 |
+| Choice | 单项页面类型分类 | 1 | 0.376秒 | - | - | 本地小模型单次测试 |
+| Boolean | 单项布尔判断 | 1 | 0.362秒 | - | - | 本地小模型单次测试 |
+| Score | 单项相关性评分 | 1 | 0.398秒 | - | - | 本地小模型单次测试 |
+| Choice | 批量页面类型分类 | 8 | 0.125秒 | 0.108秒 | 0.238秒 | 9998次成功分类 |
+| 全流程 | 请求、解析、决策和落盘 | 8 | 约0.463秒/页 | - | - | 10000页约77分钟 |
+
+### 页面处理结果
+
+| 指标 | 数值 |
+| --- | ---: |
+| 处理页面数 | 10000 |
+| 成功分类页面 | 9998 |
+| 异常页面 | 2 |
+| 成功率 | 99.98% |
+| 唯一URL数量 | 10000 |
+| 主要详情页分类 | 8983 |
+| 主要列表页分类 | 1015 |
+
+测试代码位于`test/`目录，包含HTTP解析、Choice、Boolean、Score、多决策、性能基准和实时JSONL采集测试。
+
+## 版本范围
+
+当前版本优先保证同步调用和可预测行为，暂不包含：
+
+- asyncio和异步API
+- 浏览器渲染
+- Playwright和Selenium
+- 数据库和ORM
+- 向量数据库和RAG
+- 代理池、验证码绕过和分布式队列
+
+## 生态
+
+- [awesome-jev](https://github.com/kraayenjon/awesome-jev)
+- [Made with jev](https://madewithjev.com/)
+- [xuehang.ai](https://xuehang.ai/)
+
+## 许可证
+
+本项目采用[MIT License](LICENSE)。
+
+Copyright © 2026 [XUEHANG AI](https://xuehang.ai/)。

jevhttp-0.1.0/jevhttp/__init__.py

@@ -0,0 +1,34 @@
+"""导出jevhttp公共接口"""
+
+from .client import DecisionResult, JevHttp
+from .crawler import CrawlConfig, CrawlItem, Crawler
+from .decisions import Boolean, Choice, Decision, Score
+from .errors import (
+    AIResponseError,
+    AITransportError,
+    DecisionParseError,
+    DecisionValueError,
+    HTTPRequestError,
+    JevHttpError,
+)
+from .page import Link, Page
+
+__all__ = [
+    'JevHttp',
+    'Page',
+    'Link',
+    'Decision',
+    'Choice',
+    'Boolean',
+    'Score',
+    'DecisionResult',
+    'Crawler',
+    'CrawlConfig',
+    'CrawlItem',
+    'JevHttpError',
+    'HTTPRequestError',
+    'AITransportError',
+    'AIResponseError',
+    'DecisionParseError',
+    'DecisionValueError',
+]

jevhttp-0.1.0/jevhttp/client.py

@@ -0,0 +1,314 @@
+"""实现网页请求、结构化决策和模型结构化抽取"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from dataclasses import dataclass
+from typing import Any, Mapping, Type
+
+import requests
+from openai import OpenAI
+
+from .decisions import Boolean, Choice, Decision, Score
+from .errors import (
+    AIResponseError,
+    AITransportError,
+    DecisionParseError,
+    DecisionValueError,
+    HTTPRequestError,
+)
+from .page import Page
+
+
+@dataclass
+class DecisionResult:
+    """保存结构化决策结果和模型调试信息"""
+
+    values: dict[str, Any]
+    raw: Any = None
+    model: str | None = None
+    usage: Any = None
+    decision_time: float | None = None
+    state_truncated: bool = False
+
+    @property
+    def latency(self) -> float | None:
+        """返回本次模型决策耗时，单位为秒"""
+        return self.decision_time
+
+    def __getattr__(self, name: str) -> Any:
+        """支持通过属性名读取决策结果"""
+        try:
+            return self.values[name]
+        except KeyError as exc:
+            raise AttributeError(name) from exc
+
+    def __getitem__(self, name: str) -> Any:
+        """支持通过键读取决策结果"""
+        return self.values[name]
+
+
+class JevHttp:
+    """提供同步网页请求和OpenAI-compatible结构化决策"""
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        model: str,
+        timeout: float = 30,
+        max_retries: int = 2,
+        temperature: float = 0,
+        max_tokens: int | None = None,
+        extra_body: dict | None = None,
+        headers: Mapping[str, str] | None = None,
+    ):
+        """初始化客户端及其网页、模型请求配置"""
+        self.base_url = base_url
+        self.api_key = api_key
+        self.model = model
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.temperature = temperature
+        self.max_tokens = max_tokens
+        self.extra_body = extra_body or {}
+        self.session = requests.Session()
+        self.session.headers.update({'User-Agent': 'jevhttp/0.1'})
+        if headers:
+            self.session.headers.update(headers)
+        self._ai = OpenAI(
+            base_url=base_url,
+            api_key=api_key,
+            timeout=timeout,
+            max_retries=0,
+        )
+
+    @classmethod
+    def from_env(cls, **kwargs) -> 'JevHttp':
+        """从环境变量创建客户端"""
+        return cls(
+            os.environ['JEVHTTP_BASE_URL'],
+            os.environ['JEVHTTP_API_KEY'],
+            os.environ['JEVHTTP_MODEL'],
+            **kwargs,
+        )
+
+    def choice(
+        self,
+        choices,
+        question: str = '',
+        fallback: str | None = None,
+    ) -> Choice:
+        """创建中文枚举决策"""
+        choices = tuple(str(choice) for choice in choices)
+        if not choices:
+            raise ValueError('choices不能为空')
+        if fallback is not None and fallback not in choices:
+            raise ValueError('fallback必须是choices中的一项')
+        return Choice('choice', question, choices, fallback)
+
+    def boolean(self, question: str = '') -> Boolean:
+        """创建布尔决策"""
+        return Boolean('boolean', question)
+
+    noul = boolean
+
+    def score(
+        self,
+        question: str = '',
+        min: float = 0,
+        max: float = 1,
+    ) -> Score:
+        """创建指定范围内的数值决策"""
+        if min > max:
+            raise ValueError('min不能大于max')
+        return Score('score', question, min, max)
+
+    def _request(self, method: str, url: str, **kwargs):
+        """发送网页请求并执行有限重试"""
+        last_error = None
+        timeout = kwargs.pop('timeout', self.timeout)
+        retry_post = kwargs.pop('retry_post', False)
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = self.session.request(
+                    method,
+                    url,
+                    timeout=timeout,
+                    **kwargs,
+                )
+                if response.status_code == 429 or response.status_code >= 500:
+                    response.raise_for_status()
+                return response
+            except requests.RequestException as exc:
+                last_error = exc
+                should_stop = attempt >= self.max_retries
+                should_stop = should_stop or (
+                    method.upper() == 'POST' and not retry_post
+                )
+                if should_stop:
+                    break
+                time.sleep(min(2**attempt * 0.25, 2))
+        raise HTTPRequestError(
+            f'HTTP请求失败: method={method}, url={url}, error={last_error}'
+        ) from last_error
+
+    def get(self, url: str, **kwargs) -> Page:
+        """获取网页并返回解析后的``Page``对象"""
+        return self._page_request('GET', url, **kwargs)
+
+    def post(self, url: str, data=None, **kwargs) -> Page:
+        """提交表单并返回解析后的``Page``对象"""
+        return self._page_request('POST', url, data=data, **kwargs)
+
+    def _page_request(self, method: str, url: str, depth: int = 0, **kwargs):
+        """发送请求并将响应转换为``Page``"""
+        response = self._request(method, url, **kwargs)
+        return Page.from_response(response, depth=depth)
+
+    @staticmethod
+    def _state_json(state, max_chars: int = 8000) -> tuple[str, bool]:
+        """序列化并限制送入模型的状态长度"""
+        value = state.to_state() if isinstance(state, Page) else state
+        encoded = json.dumps(
+            value,
+            ensure_ascii=False,
+            separators=(',', ':'),
+            default=str,
+        )
+        return encoded[:max_chars], len(encoded) > max_chars
+
+    def _chat_json(self, system: str, user: str, schema: dict):
+        """调用模型并优先请求JSON Schema输出"""
+        request_body = {
+            'model': self.model,
+            'temperature': self.temperature,
+            'messages': [
+                {'role': 'system', 'content': system},
+                {'role': 'user', 'content': user},
+            ],
+            'response_format': {
+                'type': 'json_schema',
+                'json_schema': {
+                    'name': 'jevhttp_result',
+                    'strict': True,
+                    'schema': schema,
+                },
+            },
+        }
+        if self.max_tokens is not None:
+            request_body['max_tokens'] = self.max_tokens
+        request_body.update(self.extra_body)
+        try:
+            response = self._ai.chat.completions.create(**request_body)
+            content = response.choices[0].message.content if response.choices else None
+        except Exception as first_error:
+            content = None
+        if not content:
+            request_body['response_format'] = {'type': 'json_object'}
+            try:
+                response = self._ai.chat.completions.create(**request_body)
+            except Exception as second_error:
+                raise AITransportError(
+                    f'模型请求失败: {second_error}'
+                ) from locals().get('first_error')
+        if not response.choices:
+            raise AIResponseError('模型响应没有choices')
+        content = response.choices[0].message.content
+        if not content:
+            finish_reason = getattr(response.choices[0], 'finish_reason', None)
+            raise AIResponseError(
+                f'模型响应没有文本内容，finish_reason={finish_reason!r}'
+            )
+        return response, content
+
+    def system_one(
+        self,
+        state,
+        decisions: Mapping[str, Decision],
+        max_chars: int = 8000,
+    ) -> DecisionResult:
+        """使用一次中文提示词完成多个结构化决策"""
+        if not decisions:
+            raise ValueError('decisions不能为空')
+        state_text, state_truncated = self._state_json(state, max_chars)
+        schema = {
+            'type': 'object',
+            'properties': {
+                name: decision.schema()
+                for name, decision in decisions.items()
+            },
+            'required': list(decisions),
+            'additionalProperties': False,
+        }
+        system = (
+            '你是一个严谨的中文结构化信息判断模型。'
+            '请只返回符合JSON Schema的JSON对象。'
+            '所有Choice分类必须原样使用候选项中的中文文本，禁止输出英文、翻译结果或新分类。'
+            '只能依据提供的网页状态判断，不要补充网页中不存在的事实。'
+        )
+        decision_text = '\n'.join(
+            f'{name}: {decision.question or "请根据网页状态判断"}'
+            for name, decision in decisions.items()
+        )
+        user = (
+            f'网页状态(JSON):\n{state_text}\n\n'
+            f'待判断项目:\n{decision_text}'
+        )
+        started = time.perf_counter()
+        response, content = self._chat_json(system, user, schema)
+        try:
+            values = json.loads(content)
+        except json.JSONDecodeError as exc:
+            raise DecisionParseError(
+                f'模型返回内容不是有效JSON: {content[:300]!r}'
+            ) from exc
+        if not isinstance(values, dict):
+            raise DecisionParseError('模型结果必须是JSON对象')
+        validated = {}
+        for name, decision in decisions.items():
+            try:
+                validated[name] = decision.validate(values[name])
+            except (KeyError, TypeError, ValueError) as exc:
+                raise DecisionValueError(
+                    f'决策{name!r}的结果未通过校验: {exc}'
+                ) from exc
+        return DecisionResult(
+            validated,
+            raw=content,
+            model=getattr(response, 'model', self.model),
+            usage=getattr(response, 'usage', None),
+            decision_time=time.perf_counter() - started,
+            state_truncated=state_truncated,
+        )
+
+    def extract(
+        self,
+        state,
+        model: Type,
+        max_chars: int = 8000,
+        instruction: str = '',
+    ):
+        """使用中文提示词将状态抽取为Pydantic模型"""
+        if not hasattr(model, 'model_json_schema'):
+            raise TypeError('model必须是Pydantic模型类')
+        state_text, _ = self._state_json(state, max_chars)
+        system = (
+            '你是一个严谨的中文结构化信息抽取模型。'
+            '请只返回符合JSON Schema的JSON对象，不要输出解释。'
+            '只能依据输入内容抽取，无法确认的字段按Schema允许的空值处理。'
+        )
+        user = f'网页状态(JSON):\n{state_text}\n\n补充要求:\n{instruction}'
+        _, content = self._chat_json(system, user, model.model_json_schema())
+        try:
+            return model.model_validate_json(content)
+        except Exception as exc:
+            raise DecisionValueError(f'抽取结果未通过Pydantic校验: {exc}') from exc
+
+    def crawl(self, seed_url: str, goal: str, **kwargs):
+        """创建同步广度优先网页爬虫"""
+        from .crawler import Crawler
+
+        return Crawler(self).crawl(seed_url, goal, **kwargs)