caesar-search 0.1.0__tar.gz

caesar_search-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --frozen
+      - run: uv run ruff check .
+      - run: uv run ruff format --check src tests
+      - run: uv run mypy
+      - run: uv run pytest
+      - name: Generated models are in sync with the vendored spec
+        run: |
+          uv run datamodel-codegen
+          git diff --exit-code src/caesar_search/models/_models.py
+
+  gitleaks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - run: |
+          docker run --rm -v "$PWD:/repo" ghcr.io/gitleaks/gitleaks:latest \
+            git --redact --no-banner /repo

caesar_search-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,31 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch: {}
+
+permissions:
+  contents: write
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    # Must match the trusted-publisher environment configured on PyPI.
+    environment: pypi
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --frozen
+      - run: uv run pytest
+      - run: uv build
+      - name: Publish to PyPI (trusted publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1
+      - name: Create GitHub release
+        if: startsWith(github.ref, 'refs/tags/')
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh release create "${GITHUB_REF_NAME}" --generate-notes || true

caesar_search-0.1.0/.github/workflows/spec-sync.yml

@@ -0,0 +1,124 @@
+name: spec-sync
+
+# Polls the live public OpenAPI spec, regenerates the models when it changes,
+# classifies the change with oasdiff, and auto-releases non-breaking updates.
+# Breaking changes open a PR that waits for review. Also replays the live
+# contract flow nightly so server-side drift is caught even without spec
+# changes. No monorepo credentials required: the spec travels over the public
+# spec URL.
+
+on:
+  schedule:
+    - cron: "23 */6 * * *"
+  workflow_dispatch: {}
+
+env:
+  SPEC_URL: https://search-api-staging-779189860552.europe-west1.run.app/openapi/public.json
+
+permissions:
+  contents: write
+  pull-requests: write
+  actions: write
+
+jobs:
+  contract:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --frozen
+      - name: Replay search -> read -> feedback against staging
+        env:
+          CAESAR_CONTRACT: "1"
+        run: uv run pytest tests/contract -v
+
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v5
+      - name: Fetch live spec and detect drift
+        id: drift
+        run: |
+          curl -fsS "$SPEC_URL" -o /tmp/live-spec.json
+          jq -S . /tmp/live-spec.json > /tmp/live-normalized.json
+          jq -S . spec/openapi-public.json > /tmp/vendored-normalized.json
+          if cmp -s /tmp/live-normalized.json /tmp/vendored-normalized.json; then
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          fi
+      - name: Classify the change
+        id: classify
+        if: steps.drift.outputs.changed == 'true'
+        run: |
+          docker run --rm -v /tmp:/tmp -v "$PWD/spec:/spec" ghcr.io/oasdiff/oasdiff \
+            breaking /spec/openapi-public.json /tmp/live-spec.json > /tmp/breaking.txt || true
+          if [ -s /tmp/breaking.txt ]; then
+            echo "breaking=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "breaking=false" >> "$GITHUB_OUTPUT"
+          fi
+          {
+            echo "summary<<EOF"
+            docker run --rm -v /tmp:/tmp -v "$PWD/spec:/spec" ghcr.io/oasdiff/oasdiff \
+              changelog /spec/openapi-public.json /tmp/live-spec.json || true
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+      - name: Regenerate and test
+        if: steps.drift.outputs.changed == 'true'
+        run: |
+          cp /tmp/live-spec.json spec/openapi-public.json
+          uv sync --frozen
+          uv run datamodel-codegen
+          uv run ruff check .
+          uv run mypy
+          uv run pytest
+      - name: Auto-release (non-breaking)
+        if: steps.drift.outputs.changed == 'true' && steps.classify.outputs.breaking == 'false'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          git config user.name "caesar-spec-sync"
+          git config user.email "releases@caesar.xyz"
+          VERSION=$(uv run python -c "
+          import re
+          content = open('pyproject.toml').read()
+          current = re.search(r'version = \"(\d+)\.(\d+)\.(\d+)\"', content)
+          major, minor, patch = map(int, current.groups())
+          print(f'{major}.{minor}.{patch + 1}')
+          ")
+          uv run python - "$VERSION" <<'PYEOF'
+          import re, sys
+          version = sys.argv[1]
+          for path in ("pyproject.toml", "src/caesar_search/_version.py"):
+              content = open(path).read()
+              content = re.sub(r'version = "\d+\.\d+\.\d+"', f'version = "{version}"', content)
+              content = re.sub(r'__version__ = "\d+\.\d+\.\d+"', f'__version__ = "{version}"', content)
+              open(path, "w").write(content)
+          PYEOF
+          uv lock
+          git add -A
+          git commit -m "chore: regenerate from updated public spec (v${VERSION})"
+          git tag "v${VERSION}"
+          git push origin main "v${VERSION}"
+          # Tags pushed with GITHUB_TOKEN do not trigger workflows; dispatch
+          # the release workflow explicitly (workflow_dispatch is exempt).
+          gh workflow run release.yml --ref "v${VERSION}"
+      - name: Open review PR (breaking)
+        if: steps.drift.outputs.changed == 'true' && steps.classify.outputs.breaking == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SUMMARY: ${{ steps.classify.outputs.summary }}
+        run: |
+          git config user.name "caesar-spec-sync"
+          git config user.email "releases@caesar.xyz"
+          BRANCH="spec-sync/breaking-$(date -u +%Y%m%d%H%M)"
+          git checkout -b "$BRANCH"
+          git add -A
+          git commit -m "feat!: regenerate from updated public spec (breaking)"
+          git push origin "$BRANCH"
+          gh pr create --title "Breaking spec change: review required" \
+            --body "$(printf 'oasdiff classified this spec update as breaking.\n\n```\n%s\n```\n\nMerge and tag a minor release after review.' "$SUMMARY")" \
+            --label breaking || gh pr create --title "Breaking spec change: review required" \
+            --body "oasdiff classified this spec update as breaking. Merge and tag a minor release after review."

caesar_search-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/

caesar_search-0.1.0/.gitleaks.toml

@@ -0,0 +1,2 @@
+[extend]
+useDefault = true

caesar_search-0.1.0/AGENTS.md

@@ -0,0 +1,28 @@
+# AGENTS.md
+
+Guidance for AI agents using and maintaining `caesar-search` (Python).
+
+## Using the SDK
+
+- The loop: `search()` → pick `doc_id` → `read()` → optionally `feedback()`. Thread provenance handles (`doc_id`, `search_id`) between calls.
+- `read()` accepts a doc_id or URL positionally. A truncated read sets `content.truncated`; continue with `start_char=content.start_char + content.char_count` — do not retry with a bigger `max_chars`.
+- `search(verbosity=...)` controls payload shape: `ids_only` (handles only), `compact`, `standard` (default), `full` (adds provenance). `max_chars_total=` sets a hard response budget.
+- Set `CAESAR_API_KEY`; never hardcode keys. Exceptions: catch `AuthenticationError`/`RateLimitError`/`APIStatusError`.
+
+## Common mistakes
+
+| Mistake | Correction |
+|---|---|
+| `client.search(query="...", limit=5)` | The parameter is `max_results` |
+| `client.document(...)` / `client.get_document(...)` | The method is `read()` |
+| Retrying truncated reads with bigger `max_chars` | Use `start_char` continuation |
+| Expecting camelCase fields | Models are snake_case, matching the API |
+| Hand-editing `models/_models.py` | Generated from `spec/openapi-public.json`; run the generator instead |
+
+## Maintaining this repo
+
+- `spec/openapi-public.json` is the vendored contract; `uv run datamodel-codegen` regenerates `src/caesar_search/models/_models.py`. CI fails if the generated file is dirty against the spec.
+- The spec-sync workflow polls the live public spec, regenerates, classifies the diff with oasdiff, and auto-releases non-breaking changes; breaking changes open a PR for review.
+- `uv run pytest` (hermetic, httpx MockTransport) must pass; contract tests are gated behind `CAESAR_CONTRACT=1`.
+- `uv run mypy` strict on the veneer; `uv run ruff check`.
+- Never name upstream search/inference providers in code, docs, or errors.

caesar_search-0.1.0/CHANGELOG.md

@@ -0,0 +1,3 @@
+# Changelog
+
+Releases are documented on the [GitHub releases page](https://github.com/caesar-data/caesar-search-python/releases).

caesar_search-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

caesar_search-0.1.0/LICENSE

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

caesar_search-0.1.0/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: caesar-search
+Version: 0.1.0
+Summary: Official Python SDK for the Caesar search API — web search with provenance, built for agents.
+Project-URL: Homepage, https://github.com/caesar-data/caesar-search-python
+Project-URL: Repository, https://github.com/caesar-data/caesar-search-python
+Project-URL: Issues, https://github.com/caesar-data/caesar-search-python/issues
+Project-URL: Changelog, https://github.com/caesar-data/caesar-search-python/releases
+Author: Caesar
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,caesar,search,web-search
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Description-Content-Type: text/markdown
+
+# caesar-search (Python)
+
+Official Python SDK for the Caesar search API — web search with provenance, built for agents.
+
+## Quickstart
+
+```python
+# pip install caesar-search    (or: uv add caesar-search)
+from caesar_search import Caesar
+
+client = Caesar()  # reads CAESAR_API_KEY; anonymous tier works without a key
+results = client.search("rust async runtime comparison", max_results=5)
+doc = client.read(results.results[0].doc_id, query="which runtime is fastest")
+client.feedback("result_helpful", search_id=results.search_id, doc_id=doc.doc.doc_id)
+```
+
+## Clients
+
+- `Caesar` — synchronous; `AsyncCaesar` — same surface with `async`/`await`. Both support context managers.
+- Methods: `search()`, `read()` (doc_id **or** URL; `start_char=` continues truncated reads), `feedback()`.
+- Responses are typed pydantic v2 models generated from the public OpenAPI spec; provenance fields (`doc_id`, `search_id`, `capture_id`, canonical/source URLs, crawl dates) are preserved verbatim.
+- `client.with_raw_response.search(...)` returns the raw `httpx.Response`.
+- Retries: 429/5xx with capped exponential backoff honoring `Retry-After` (`max_retries=` to tune, `0` to disable).
+- Config: `api_key=` / `CAESAR_API_KEY`; `base_url=` / `CAESAR_BASE_URL`.
+
+## Errors
+
+`CaesarError` → `APIConnectionError` / `APITimeoutError` and `APIStatusError` (with `.status_code`, `.code`, `.message`, `.request_id`) → `AuthenticationError` (401/403), `RateLimitError` (429).
+
+## License
+
+[MIT](LICENSE)

caesar_search-0.1.0/README.md

@@ -0,0 +1,32 @@
+# caesar-search (Python)
+
+Official Python SDK for the Caesar search API — web search with provenance, built for agents.
+
+## Quickstart
+
+```python
+# pip install caesar-search    (or: uv add caesar-search)
+from caesar_search import Caesar
+
+client = Caesar()  # reads CAESAR_API_KEY; anonymous tier works without a key
+results = client.search("rust async runtime comparison", max_results=5)
+doc = client.read(results.results[0].doc_id, query="which runtime is fastest")
+client.feedback("result_helpful", search_id=results.search_id, doc_id=doc.doc.doc_id)
+```
+
+## Clients
+
+- `Caesar` — synchronous; `AsyncCaesar` — same surface with `async`/`await`. Both support context managers.
+- Methods: `search()`, `read()` (doc_id **or** URL; `start_char=` continues truncated reads), `feedback()`.
+- Responses are typed pydantic v2 models generated from the public OpenAPI spec; provenance fields (`doc_id`, `search_id`, `capture_id`, canonical/source URLs, crawl dates) are preserved verbatim.
+- `client.with_raw_response.search(...)` returns the raw `httpx.Response`.
+- Retries: 429/5xx with capped exponential backoff honoring `Retry-After` (`max_retries=` to tune, `0` to disable).
+- Config: `api_key=` / `CAESAR_API_KEY`; `base_url=` / `CAESAR_BASE_URL`.
+
+## Errors
+
+`CaesarError` → `APIConnectionError` / `APITimeoutError` and `APIStatusError` (with `.status_code`, `.code`, `.message`, `.request_id`) → `AuthenticationError` (401/403), `RateLimitError` (429).
+
+## License
+
+[MIT](LICENSE)

caesar_search-0.1.0/SECURITY.md

@@ -0,0 +1,4 @@
+# Security
+
+Report vulnerabilities privately via GitHub security advisories on this repository.
+The SDK never logs API keys.

caesar_search-0.1.0/context7.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://context7.com/schema/context7.json",
+  "projectTitle": "caesar-search Python SDK",
+  "description": "Official Python SDK for the Caesar search API: web search with provenance for agents",
+  "folders": [],
+  "excludeFolders": ["spec", ".venv"],
+  "rules": [
+    "Instantiate Caesar() or AsyncCaesar(); CAESAR_API_KEY is read from the environment",
+    "Methods are search(), read(), feedback(); the search size parameter is max_results",
+    "Continue truncated reads with start_char instead of increasing max_chars",
+    "Catch AuthenticationError, RateLimitError, APIStatusError from caesar_search",
+    "Models are generated pydantic v2; fields are snake_case"
+  ]
+}

caesar_search-0.1.0/pyproject.toml

@@ -0,0 +1,82 @@
+[project]
+name = "caesar-search"
+version = "0.1.0"
+description = "Official Python SDK for the Caesar search API — web search with provenance, built for agents."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Caesar" }]
+keywords = ["search", "web-search", "agents", "caesar"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.27",
+  "pydantic>=2.7",
+]
+
+[project.urls]
+Homepage = "https://github.com/caesar-data/caesar-search-python"
+Repository = "https://github.com/caesar-data/caesar-search-python"
+Issues = "https://github.com/caesar-data/caesar-search-python/issues"
+Changelog = "https://github.com/caesar-data/caesar-search-python/releases"
+
+[dependency-groups]
+dev = [
+  "pytest>=8",
+  "pytest-asyncio>=0.24",
+  "mypy>=1.13",
+  "ruff>=0.8",
+  "datamodel-code-generator[http]>=0.63",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/caesar_search"]
+
+[tool.ruff]
+line-length = 110
+target-version = "py310"
+# Generated code is owned by the generator, not the formatter.
+exclude = ["src/caesar_search/models/_models.py"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+strict = true
+files = ["src/caesar_search", "tests"]
+exclude = ["src/caesar_search/models/_models\\.py"]
+
+[[tool.mypy.overrides]]
+module = "caesar_search.models._models"
+ignore_errors = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.datamodel-codegen]
+input = "spec/openapi-public.json"
+input-file-type = "openapi"
+output = "src/caesar_search/models/_models.py"
+output-model-type = "pydantic_v2.BaseModel"
+target-python-version = "3.10"
+use-schema-description = true
+use-field-description = true
+field-constraints = true
+use-double-quotes = true
+disable-timestamp = true
+allow-extra-fields = true
+formatters = ["black", "isort"]