jouyaar 0.1.0__tar.gz

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

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  release:
+    types: [published]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --extra dev
+      - run: uv run ruff check src tests
+      - run: uv run pytest -q
+
+  publish:
+    # Publish to PyPI on a GitHub Release, via Trusted Publishing (no token needed).
+    needs: test
+    if: github.event_name == 'release'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

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

@@ -0,0 +1,21 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Python Semantic Versioning
+        uses: mostafaghadimi/python-semantic-versioning@v2.8.1
+        with:
+          gh_token: ${{ secrets.GITHUB_TOKEN }}

jouyaar-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.env

jouyaar-0.1.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# CHANGELOG
+
+
+## v0.1.0 (2026-08-26)
+
+### Ci
+
+- Add release workflow
+  ([`e9ef9ac`](https://github.com/jouyaar/jouyaar-python-sdk/commit/e9ef9ac28fc8748a2411681926bfda0eef290ecb))
+
+### Features
+
+- Initial release — Jooyar Python SDK v0.1.0
+  ([`26a7ba2`](https://github.com/jouyaar/jouyaar-python-sdk/commit/26a7ba296d7551324ac8d9080b4c2766c3231844))

jouyaar-0.1.0/LICENSE

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

jouyaar-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.5
+Name: jouyaar
+Version: 0.1.0
+Summary: Official Python SDK for the Jooyar (جویار) agentic search API
+Project-URL: Homepage, https://developers.jouyaar.ir
+Project-URL: Documentation, https://developers.jouyaar.ir
+Author: Jooyar
+License: MIT
+License-File: LICENSE
+Keywords: api,iran,jooyar,jouyaar,sdk,search
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Jooyar Python SDK
+
+Official Python client for the **Jooyar (جویار)** agentic search API — compare flights, lodging,
+bus, train, retail, and internet plans across Iranian providers from one call.
+
+```bash
+pip install jouyaar
+```
+
+## Quickstart
+
+```python
+from jouyaar import Jooyaar
+
+client = Jooyaar(api_key="sk_live_…")   # or set JOUYAAR_API_KEY
+
+# Structured search — deterministic, LLM-free, cheapest:
+res = client.search(
+    category="flight",
+    params={"origin": "THR", "destination": "MHD", "departure_date": "1404-06-10", "passengers": 1},
+    sort="price",
+)
+for q in res.quotes:
+    print(q.provider, f"{q.price_toman:,} تومان", q.plan_name)
+
+# Natural-language search — the API extracts the parameters for you:
+res = client.search(category="flight", prompt="ارزان‌ترین پرواز تهران به مشهد فردا صبح")
+```
+
+Get a key at **[developers.jouyaar.ir](https://developers.jouyaar.ir)**.
+
+## Two ways to search
+
+| Mode | How | When |
+|---|---|---|
+| `params=` | structured fields (see `client.categories()`) | you already know the fields — deterministic, no LLM, cheapest |
+| `prompt=` | free-text intent | let the API parse a natural-language request |
+
+Pass exactly one. `client.categories()` lists every category and its required/optional fields.
+
+## Async
+
+```python
+import asyncio
+from jouyaar import AsyncJooyaar
+
+async def main():
+    async with AsyncJooyaar() as client:
+        res = await client.search(category="lodging",
+                                  params={"city": "تهران", "checkin": "1404-06-10", "checkout": "1404-06-12"})
+        print(len(res.quotes), "results")
+
+asyncio.run(main())
+```
+
+## Errors
+
+All failures raise a `JooyaarError` subclass carrying the server `code` and `request_id`:
+
+```python
+import time
+from jouyaar import Jooyaar, RateLimitError, QuotaExceededError, AuthenticationError
+
+client = Jooyaar()
+try:
+    res = client.search(category="flight", prompt="…")
+except RateLimitError as e:
+    time.sleep(e.retry_after or 1)      # per-minute limit — back off and retry
+except QuotaExceededError:
+    ...                                  # monthly quota spent — upgrade the plan
+except AuthenticationError:
+    ...                                  # bad/revoked key
+```
+
+`RateLimitError` (429, per-minute) and 5xx responses are **retried automatically** with backoff
+(honoring `Retry-After`); 4xx are not. Tune with `Jooyaar(max_retries=..., timeout=...)`.
+
+## Configuration
+
+| Argument | Env var | Default |
+|---|---|---|
+| `api_key` | `JOUYAAR_API_KEY` | — (required) |
+| `base_url` | `JOUYAAR_BASE_URL` | `https://api.jouyaar.ir` |
+| `timeout` | — | `30.0` |
+| `max_retries` | — | `2` |
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+uv run ruff check src tests
+```
+
+MIT licensed.

jouyaar-0.1.0/README.md

@@ -0,0 +1,95 @@
+# Jooyar Python SDK
+
+Official Python client for the **Jooyar (جویار)** agentic search API — compare flights, lodging,
+bus, train, retail, and internet plans across Iranian providers from one call.
+
+```bash
+pip install jouyaar
+```
+
+## Quickstart
+
+```python
+from jouyaar import Jooyaar
+
+client = Jooyaar(api_key="sk_live_…")   # or set JOUYAAR_API_KEY
+
+# Structured search — deterministic, LLM-free, cheapest:
+res = client.search(
+    category="flight",
+    params={"origin": "THR", "destination": "MHD", "departure_date": "1404-06-10", "passengers": 1},
+    sort="price",
+)
+for q in res.quotes:
+    print(q.provider, f"{q.price_toman:,} تومان", q.plan_name)
+
+# Natural-language search — the API extracts the parameters for you:
+res = client.search(category="flight", prompt="ارزان‌ترین پرواز تهران به مشهد فردا صبح")
+```
+
+Get a key at **[developers.jouyaar.ir](https://developers.jouyaar.ir)**.
+
+## Two ways to search
+
+| Mode | How | When |
+|---|---|---|
+| `params=` | structured fields (see `client.categories()`) | you already know the fields — deterministic, no LLM, cheapest |
+| `prompt=` | free-text intent | let the API parse a natural-language request |
+
+Pass exactly one. `client.categories()` lists every category and its required/optional fields.
+
+## Async
+
+```python
+import asyncio
+from jouyaar import AsyncJooyaar
+
+async def main():
+    async with AsyncJooyaar() as client:
+        res = await client.search(category="lodging",
+                                  params={"city": "تهران", "checkin": "1404-06-10", "checkout": "1404-06-12"})
+        print(len(res.quotes), "results")
+
+asyncio.run(main())
+```
+
+## Errors
+
+All failures raise a `JooyaarError` subclass carrying the server `code` and `request_id`:
+
+```python
+import time
+from jouyaar import Jooyaar, RateLimitError, QuotaExceededError, AuthenticationError
+
+client = Jooyaar()
+try:
+    res = client.search(category="flight", prompt="…")
+except RateLimitError as e:
+    time.sleep(e.retry_after or 1)      # per-minute limit — back off and retry
+except QuotaExceededError:
+    ...                                  # monthly quota spent — upgrade the plan
+except AuthenticationError:
+    ...                                  # bad/revoked key
+```
+
+`RateLimitError` (429, per-minute) and 5xx responses are **retried automatically** with backoff
+(honoring `Retry-After`); 4xx are not. Tune with `Jooyaar(max_retries=..., timeout=...)`.
+
+## Configuration
+
+| Argument | Env var | Default |
+|---|---|---|
+| `api_key` | `JOUYAAR_API_KEY` | — (required) |
+| `base_url` | `JOUYAAR_BASE_URL` | `https://api.jouyaar.ir` |
+| `timeout` | — | `30.0` |
+| `max_retries` | — | `2` |
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+uv run ruff check src tests
+```
+
+MIT licensed.

jouyaar-0.1.0/examples/quickstart.py

@@ -0,0 +1,35 @@
+"""Quickstart — set JOUYAAR_API_KEY (and JOUYAAR_BASE_URL for a non-prod host), then run:
+
+    uv run --with . python examples/quickstart.py
+"""
+
+from jouyaar import Jooyaar, RateLimitError
+
+
+def main() -> None:
+    with Jooyaar() as client:  # reads JOUYAAR_API_KEY
+        print("Plan/usage:", client.usage())
+
+        print("\nCategories:")
+        for cat in client.categories():
+            required = [f.name for f in cat.fields if f.required]
+            print(f"  - {cat.name} ({cat.fa_title}) required={required}")
+
+        # Structured (LLM-free) search — cheapest, deterministic.
+        try:
+            res = client.search(
+                category="flight",
+                params={"origin": "THR", "destination": "MHD", "departure_date": "1404-06-10", "passengers": 1},
+                sort="price",
+            )
+        except RateLimitError as e:
+            print(f"rate limited; retry after {e.retry_after}s")
+            return
+
+        print(f"\nSearch ok={res.ok} — {len(res.quotes)} quotes")
+        for q in res.quotes[:5]:
+            print(f"  {q.provider:12} {q.price_toman:>12,} تومان  {q.plan_name}")
+
+
+if __name__ == "__main__":
+    main()

jouyaar-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "jouyaar"
+version = "0.1.0"
+description = "Official Python SDK for the Jooyar (جویار) agentic search API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Jooyar" }]
+keywords = ["jooyar", "jouyaar", "search", "api", "sdk", "iran"]
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.7",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+    "ruff>=0.9",
+]
+
+[project.urls]
+Homepage = "https://developers.jouyaar.ir"
+Documentation = "https://developers.jouyaar.ir"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/jouyaar"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["F", "E", "W", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.ruff.lint.per-file-ignores]
+# Test fixtures carry long inline JSON literals; readability beats wrapping them.
+"tests/*" = ["E501"]

jouyaar-0.1.0/src/jouyaar/__init__.py

@@ -0,0 +1,51 @@
+"""Jooyar (جویار) — official Python SDK for the agentic search API.
+
+    from jouyaar import Jooyaar
+    client = Jooyaar(api_key="sk_live_…")   # or set JOUYAAR_API_KEY
+    res = client.search(category="flight", prompt="پرواز تهران به مشهد فردا صبح")
+    for q in res.quotes:
+        print(q.provider, q.price_toman)
+"""
+
+from ._version import __version__
+from .client import AsyncJooyaar, Jooyaar
+from .errors import (
+    APIConnectionError,
+    APIStatusError,
+    AuthenticationError,
+    InvalidRequestError,
+    JooyaarError,
+    QuotaExceededError,
+    RateLimitError,
+)
+from .models import (
+    Category,
+    FieldInfo,
+    ProviderMeta,
+    Quote,
+    SearchResponse,
+    SearchResult,
+    Seller,
+    Usage,
+)
+
+__all__ = [
+    "APIConnectionError",
+    "APIStatusError",
+    "AsyncJooyaar",
+    "AuthenticationError",
+    "Category",
+    "FieldInfo",
+    "InvalidRequestError",
+    "Jooyaar",
+    "JooyaarError",
+    "ProviderMeta",
+    "QuotaExceededError",
+    "Quote",
+    "RateLimitError",
+    "SearchResponse",
+    "SearchResult",
+    "Seller",
+    "Usage",
+    "__version__",
+]

jouyaar-0.1.0/src/jouyaar/_core.py

@@ -0,0 +1,92 @@
+"""Shared, transport-agnostic helpers for the sync and async clients.
+
+Keeps request construction, error mapping, and retry policy in one place so the two clients only
+differ in how they run the HTTP call.
+"""
+
+from typing import Any, Optional
+
+import httpx
+
+from ._version import __version__
+from .errors import (
+    APIStatusError,
+    AuthenticationError,
+    InvalidRequestError,
+    JooyaarError,
+    QuotaExceededError,
+    RateLimitError,
+)
+
+DEFAULT_BASE_URL = "https://api.jouyaar.ir"
+USER_AGENT = f"jouyaar-python/{__version__}"
+
+
+def build_headers(api_key: str) -> dict:
+    return {
+        "Authorization": f"Bearer {api_key}",
+        "User-Agent": USER_AGENT,
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+    }
+
+
+def _error_from_body(status: int, body: Any, headers: httpx.Headers) -> JooyaarError:
+    """Map an API error envelope (``{"error": {...}}``) to the right exception class."""
+    err = body.get("error", {}) if isinstance(body, dict) else {}
+    code = err.get("code")
+    message = err.get("message") or err.get("detail") or f"HTTP {status}"
+    request_id = err.get("request_id") or headers.get("x-request-id")
+    common = {"status_code": status, "code": code, "request_id": request_id}
+
+    if status == 401:
+        return AuthenticationError(message, **common)
+    if status == 429:
+        if code == "quota_exceeded":
+            return QuotaExceededError(message, **common)
+        ra = headers.get("retry-after")
+        retry_after = int(ra) if ra and ra.isdigit() else None
+        return RateLimitError(message, retry_after=retry_after, **common)
+    if status in (400, 422):
+        return InvalidRequestError(message, **common)
+    return APIStatusError(message, **common)
+
+
+def parse_response(resp: httpx.Response) -> Any:
+    """Return parsed JSON for a 2xx response, or raise the mapped error."""
+    try:
+        body = resp.json()
+    except Exception:  # non-JSON body (proxy error page, etc.)
+        body = None
+    if resp.is_success:
+        return body
+    raise _error_from_body(resp.status_code, body, resp.headers)
+
+
+def should_retry(status: Optional[int]) -> bool:
+    """Retry transient failures: rate limits and 5xx. Never retry 4xx (except 429)."""
+    return status is not None and (status == 429 or status >= 500)
+
+
+def retry_delay(attempt: int, resp: Optional[httpx.Response]) -> float:
+    """Backoff seconds for a retry: honor ``Retry-After`` if present, else exponential."""
+    if resp is not None:
+        ra = resp.headers.get("retry-after")
+        if ra and ra.isdigit():
+            return float(int(ra))
+    return min(2.0**attempt, 10.0)  # 1, 2, 4, … capped at 10s
+
+
+def build_search_body(
+    category: str, prompt: Optional[str], params: Optional[dict], sort: Optional[str]
+) -> dict:
+    if (prompt is None) == (params is None):
+        raise ValueError("Provide exactly one of `prompt` or `params`.")
+    body: dict = {"category": category}
+    if prompt is not None:
+        body["prompt"] = prompt
+    if params is not None:
+        body["params"] = params
+    if sort is not None:
+        body["sort"] = sort
+    return body

jouyaar-0.1.0/src/jouyaar/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"