vouch 0.2.0__tar.gz

vouch-0.2.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,36 @@
+---
+name: Bug report
+about: Something isn't working as expected
+title: "[bug] "
+labels: bug
+---
+
+**What happened?**
+A clear and concise description.
+
+**Reproducer**
+
+```python
+from vouch import SearchEngine, Site
+engine = SearchEngine(llm="ollama/qwen2.5:7b")
+engine.add(Site("..."))
+result = engine.search("...")
+```
+
+**Expected vs actual**
+
+- Expected: ...
+- Actual: ...
+
+**Environment**
+
+- OS: <Windows / macOS / Linux>
+- Python: <output of `python --version`>
+- vouch: <output of `vouch --version`>
+- Extras installed: <`browser`, `stealth`, `monitor`, etc.>
+
+**Logs / traceback**
+
+```
+<paste here>
+```

vouch-0.2.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,15 @@
+---
+name: Feature request
+about: Suggest an idea or improvement
+title: "[feature] "
+labels: enhancement
+---
+
+**Use case**
+Describe what you're trying to accomplish.
+
+**Proposed API**
+What would the public API look like? Example code is gold.
+
+**Alternatives considered**
+Anything you've already ruled out, and why.

vouch-0.2.0/.github/ISSUE_TEMPLATE/new_profile.md

@@ -0,0 +1,33 @@
+---
+name: New site profile
+about: Submit a curated profile for a popular site
+title: "[profile] add <domain>"
+labels: profile
+---
+
+**Domain**
+e.g. `example.com`
+
+**Why curate this site?**
+What category, language, audience? Why should vouch's users know about it?
+
+**Suggested profile YAML**
+
+```yaml
+- url: example.com
+  category: ...
+  description: >
+    ...
+  tags: [..., ...]
+  search_url_template: "/search?q={query}"
+```
+
+**Notes on extraction**
+
+- Does it block default UA? (yes/no)
+- Server-rendered or JS-only?
+- Any anti-bot WAF (Cloudflare, DataDome, …)?
+
+**Sample search you tested**
+
+`<query that works>` →  expect to find  `<sample result title>`

vouch-0.2.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,23 @@
+## Summary
+
+What does this PR change and why?
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Breaking API change
+- [ ] New site profile (`vouch/profiles/builtin.yaml`)
+- [ ] Docs / examples / tests only
+
+## Test plan
+
+- [ ] Existing test suite passes (`pytest -q`)
+- [ ] Lint passes (`ruff check . && ruff format --check .`)
+- [ ] New tests added for the change (where appropriate)
+
+## Checklist
+
+- [ ] CHANGELOG updated under `[Unreleased]`
+- [ ] Public API additions exported from `vouch/__init__.py`
+- [ ] Docstrings on new public functions

vouch-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,67 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint (ruff)
+        run: |
+          ruff check vouch tests
+          ruff format --check vouch tests
+
+      - name: Test
+        run: pytest --cov=vouch --cov-report=xml -q
+
+      - name: Upload coverage
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+        uses: codecov/codecov-action@v4
+        with:
+          file: coverage.xml
+          fail_ci_if_error: false
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - name: Verify wheel installs cleanly
+        run: |
+          pip install dist/vouch-*.whl
+          python -c "import vouch; print('OK', vouch.__version__)"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

vouch-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,34 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write
+  id-token: write  # for trusted publishing
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # Configure trusted publishing on PyPI:
+        # https://docs.pypi.org/trusted-publishers/
+
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: dist/*

vouch-0.2.0/.gitignore

@@ -0,0 +1,84 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# 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
+*.manifest
+*.spec
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+
+# Editor
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# curio runtime data
+.curio/
+*.db
+*.db-journal
+*.sqlite
+*.sqlite3
+
+# test scratch dirs and logs
+test-cache*/
+test-*-output*.log
+smoke-output.log
+*.log
+
+# Playwright
+playwright-report/
+test-results/
+
+# Type checkers
+.mypy_cache/
+.pytype/
+.ruff_cache/
+
+# Jupyter
+.ipynb_checkpoints
+*.ipynb

vouch-0.2.0/CHANGELOG.md

@@ -0,0 +1,131 @@
+# Changelog
+
+All notable changes to **vouch** are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
+this project follows [Semantic Versioning](https://semver.org/).
+
+## [0.2.0] — 2026-05-10
+
+### Renamed
+
+- **Package renamed from ``curio`` to ``vouch``** to avoid conflict with the
+  existing ``curio`` async library on PyPI. The old ``CurioError`` exception
+  is kept as a back-compat alias of ``VouchError`` and will be removed in
+  v1.0. Update your imports::
+
+      # before
+      from curio import SearchEngine
+      # after
+      from vouch import SearchEngine
+
+### Added (continued)
+
+- **Browser pool** — one long-lived Chromium process per engine, shared
+  across every search. Eliminates the per-call launch overhead (~3-8 s warm,
+  worse cold) and the Windows stability issues from forking many Chromium
+  instances. Opt-in via ``use_browser_pool=True`` (default on); set False to
+  fall back to the v0.1 "fresh browser per search" path. Engine adds
+  ``close()`` / context-manager protocol for explicit teardown.
+- **Plugin model via entry_points** — three discovery groups:
+    - ``vouch.adapters`` — per-host SiteAdapter implementations
+      (``arxiv.org`` exact, ``*.gov.br`` suffix, or ``*`` fallback).
+    - ``vouch.routers`` — alternative router strategies.
+    - ``vouch.profiles`` — community ProfileRegistry bundles.
+  Third parties can ``pip install vouch-adapter-arxiv`` and the next
+  ``SearchEngine`` picks it up. See ``docs/plugins.md`` for the contract.
+  CLI: ``vouch plugins list``.
+- **Profile auto-update** — ``vouch profiles update`` fetches the latest
+  community registry from a configurable URL (default
+  ``github.com/evertonsjjj/vouch-profiles``), validates the YAML, and merges
+  it on top of the bundled ``builtin.yaml``. Honors HTTP caching
+  (ETag / If-Modified-Since) and falls back gracefully to the bundled
+  profiles on any network failure.
+- **Tesseract OCR fallback** for text CAPTCHAs (``vouch[ocr]``). Classical
+  CPU OCR — ~50-200 ms per image, $0, no GPU, no model download. The
+  ``CaptchaSolver`` now chains automatically: Tesseract first → vision LLM
+  on low confidence → return best result. Image-grid CAPTCHAs still need a
+  vision LLM (``ollama/qwen2.5vl:7b`` recommended). ``CaptchaResult`` gains
+  a ``solver`` field showing which backend produced the answer.
+
+### Added
+
+- **CSS selector pinning** — the result-extraction LLM now examines DOM context
+  (ancestor tag chain, sibling tags, full HTML of one candidate card) and emits
+  reusable CSS selector tuples (`container`, `title`, `url`, `snippet`, `date`,
+  `author`). Subsequent calls replay via `lxml.cssselect` — deterministic,
+  no LLM call. Cached in `selectors.db`.
+- **Auto-escalation chain** — adapter ladder (`http` → `browser` → `stealth`).
+  Each search records `working_tier` and `failed_tiers` per site; the next
+  call starts at the cheapest tier known to work for that domain. When the
+  current tier returns chunks but they look like nav/megamenu, the engine
+  keeps escalating instead of accepting the junk.
+- **Auto-DNS resolution** — `engine.add(Site("foo.es"), ...)` with
+  `auto_resolve_dns=True` probes a short list of canonical hostname variants
+  (`www.`, `sede.`, `agencia.`, `<root>.gob.es`, `<root>.gov.br`, …) and
+  picks the one that responds. Fixes `agenciatributaria.es` →
+  `sede.agenciatributaria.gob.es` automatically.
+- **Smarter quality detector** — `looks_low_quality()` now flags megamenu
+  patterns, recursive search-page links, "no results" / "nenhum resultado" /
+  "no se encontraron" sentinels in HTML, and short categorical titles.
+- **Probe crawl on add()** — opt-in `auto_probe_on_add=True` runs a tiny
+  probe query the moment a site is added so the engine learns its
+  working_tier and selectors before any real user query.
+- **Profile registry** — bundled `vouch/profiles/builtin.yaml` ships with
+  curated profiles for 24 popular sites (arxiv, github, huggingface, pypi,
+  npmjs, crates, MDN, Wikipedia ×3, gov.uk, irs.gov, sede.agenciatributaria,
+  jusbrasil, planalto, BBC, Folha, El País, Stack Overflow, Reddit, …).
+  New CLI commands: `vouch profiles list/show/import`.
+- **Accept-Language header** — query language detected (PT/ES/EN/FR/IT/DE)
+  and matching `Accept-Language` is sent on HTTP fetches. Reduces redirects
+  to wrong-language site versions.
+- **Result formatting helpers** — `SearchResult.to_markdown()`,
+  `to_json()`, `to_dict()` for clean rendering in chat / docs / files.
+- **Async API** — `engine.asearch(query, ...)` returns a `SearchResult`
+  awaitable, friendly for agent frameworks.
+- **`SearchResult.quality_warning`** — populated when extracted chunks pass
+  the heuristic but `looks_low_quality()` flags them, so callers know
+  *something* but it's probably nav/shell.
+- **Browser stability on Windows** — process-wide
+  `threading.Semaphore(_MAX_PARALLEL_BROWSERS=1)` gates concurrent Chromium
+  launches; cleanup is now exception-safe.
+- **57 unit tests** covering catalog, router, engine, cache, extraction,
+  CSS selectors, quality detector, language detection, DNS resolver, models.
+
+### Changed
+
+- `Site.__init__` now accepts a positional URL (`Site("cvm.gov.br")`),
+  matching the README's documented API.
+- `build_adapter` prefers `HTTPAdapter` whenever a `search_url_template` is
+  set (10× faster) — falls back to `BrowserAdapter` otherwise.
+- `BrowserAdapter` waits for `networkidle` after `domcontentloaded` so
+  XHR-rendered results pages are captured.
+- `_adapter_ladder` skips the `stealth` tier automatically when `patchright`
+  isn't installed — avoids re-running the plain BrowserAdapter twice.
+- Heuristic extractor's host filter is now subdomain-aware
+  (`developer.mozilla.org` rejects links to `www.mozilla.org`).
+- Selector cache is always truthy (`__bool__ → True`); fixes a fresh-cache
+  bug where `if self.cache and selectors:` evaluated False on empty cache.
+
+### Bug fixes
+
+- CLI `--version` no longer requires a subcommand to short-circuit.
+- `to_chunks` (HTTPAdapter path) now calls the same nav-anchor filter as
+  the BrowserAdapter path; `_split_into_result_chunks` removed.
+
+## [0.1.0] — initial release
+
+- Three-level API (one-shot `search()`, `SearchEngine`, YAML catalog).
+- Sync engine, parallel-site fetcher, LLM router with strategies
+  (`llm`, `embedding`, `tags`, `all`).
+- HTTP and Browser (Playwright) adapters; Patchright stealth optional.
+- LLM-powered search-bar discovery + selector cache.
+- LLM result-extraction fallback with URL-pattern cache.
+- Catalog (SQLite) + Site model.
+- CLI (`search`, `catalog`, `serve`, `mcp`).
+- FastAPI dashboard.
+- CrewAI / LangChain / PydanticAI / MCP integrations.
+- Optional vision-LLM CAPTCHA solver, APScheduler change monitor.
+
+[0.2.0]: https://github.com/evertonsjjj/vouch/releases/tag/v0.2.0
+[0.1.0]: https://github.com/evertonsjjj/vouch/releases/tag/v0.1.0

vouch-0.2.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,33 @@
+# Contributor Covenant Code of Conduct
+
+## Our pledge
+
+We pledge to make participation in the vouch community a harassment-free
+experience for everyone, regardless of age, body size, visible or invisible
+disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Standards
+
+Examples of positive behavior:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+
+Unacceptable behavior:
+
+- Sexualized language or imagery
+- Trolling, insulting, or derogatory comments
+- Public or private harassment
+- Publishing others' private information without explicit permission
+
+## Enforcement
+
+Instances of abusive behavior may be reported to the project maintainers
+at the repository's `SECURITY.md`-listed contact. All complaints will be
+reviewed and investigated promptly and fairly.
+
+This code of conduct is adapted from the
+[Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

vouch-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing to vouch
+
+Thanks for considering a contribution. vouch is an early-stage project — issues, PRs, and ideas are all welcome.
+
+## Development setup
+
+```bash
+git clone https://github.com/evertonsjjj/vouch
+cd vouch
+python -m venv .venv
+source .venv/bin/activate          # Windows: .venv\Scripts\activate
+pip install -e ".[dev,all]"
+playwright install chromium
+pytest
+```
+
+## Project layout
+
+See the [Architecture](README.md#architecture) section of the README. Each major component is a `Protocol` you can replace — keep that contract in mind when adding features.
+
+## Style
+
+- `ruff` for linting and formatting (`ruff check . && ruff format .`).
+- `mypy` for type-checking the core modules.
+- Docstrings on public API. No comment spam internally.
+- Tests for every new public function or protocol implementation.
+
+## Commit / PR conventions
+
+- One logical change per PR.
+- Reference an issue when one exists.
+- Run `pytest` and `ruff check .` before pushing.
+- Keep `README.md` in sync when public API changes.
+
+## Areas we want help with
+
+- New `SiteAdapter` implementations (per-site optimizations).
+- New `Router` strategies.
+- Integrations with other agent frameworks.
+- Translations (English / Português / Español).
+- Real-world catalogs as YAML examples (regulatory, academic, news).
+
+## Code of conduct
+
+Be kind. Be specific. Assume good faith. Reviewers and contributors give their time freely — make their job easier with clear context.

vouch-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 curio contributors
+
+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.