spora-sdk 2.0.0__tar.gz

spora_sdk-2.0.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: spora-sdk
+Version: 2.0.0
+Summary: Official Python SDK for the Spora agronomic intelligence API
+Home-page: https://spora.engineer
+Author: Spora
+Author-email: hello.spora@yahoo.com
+Project-URL: Documentation, https://spora.engineer/docs
+Keywords: agronomy,agriculture,api,plants,crops
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Scientific/Engineering
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Spora Python SDK
+
+Official Python client for the [Spora agronomic intelligence API](https://spora.engineer).
+
+## Installation
+
+```bash
+pip install spora-sdk
+```
+
+## Quick start
+
+```python
+from spora import Spora
+
+client = Spora(api_key="spk_live_your_key_here")
+
+# Search species
+species = client.search_species("Rosa", limit=5)
+
+# Get crop requirements
+crop = client.get_crop("solanum_lycopersicum")
+print(crop["temp_optimal_min"], crop["temp_optimal_max"])
+
+# AI question (paid key)
+answer = client.ask(
+    "When should I irrigate my tomatoes?",
+    crop="solanum_lycopersicum",
+    lat=45.4, lon=11.0,
+    tone="concise",
+)
+print(answer["response"])
+
+# Batch
+results = client.batch([
+    ("weather",      {"lat": 45.4, "lon": 11.0, "days": 3}),
+    ("should_water", {"lat": 45.4, "lon": 11.0, "crop": "vitis_vinifera"}),
+])
+```
+
+## Error handling
+
+```python
+from spora import Spora, SporaError
+
+client = Spora(api_key="spk_live_your_key_here")
+
+try:
+    result = client.ask("Best cover crop for clay soil?")
+except SporaError as e:
+    print(e.status, e.error)
+
+print(client.rate_limit.remaining, "/", client.rate_limit.limit)
+```
+
+## Links
+
+- [Documentation](https://spora.engineer/docs/sdk)
+- [API Reference](https://spora.engineer/docs)
+- [Get an API key](https://spora.engineer/request)

spora_sdk-2.0.0/README.md

@@ -0,0 +1,60 @@
+# Spora Python SDK
+
+Official Python client for the [Spora agronomic intelligence API](https://spora.engineer).
+
+## Installation
+
+```bash
+pip install spora-sdk
+```
+
+## Quick start
+
+```python
+from spora import Spora
+
+client = Spora(api_key="spk_live_your_key_here")
+
+# Search species
+species = client.search_species("Rosa", limit=5)
+
+# Get crop requirements
+crop = client.get_crop("solanum_lycopersicum")
+print(crop["temp_optimal_min"], crop["temp_optimal_max"])
+
+# AI question (paid key)
+answer = client.ask(
+    "When should I irrigate my tomatoes?",
+    crop="solanum_lycopersicum",
+    lat=45.4, lon=11.0,
+    tone="concise",
+)
+print(answer["response"])
+
+# Batch
+results = client.batch([
+    ("weather",      {"lat": 45.4, "lon": 11.0, "days": 3}),
+    ("should_water", {"lat": 45.4, "lon": 11.0, "crop": "vitis_vinifera"}),
+])
+```
+
+## Error handling
+
+```python
+from spora import Spora, SporaError
+
+client = Spora(api_key="spk_live_your_key_here")
+
+try:
+    result = client.ask("Best cover crop for clay soil?")
+except SporaError as e:
+    print(e.status, e.error)
+
+print(client.rate_limit.remaining, "/", client.rate_limit.limit)
+```
+
+## Links
+
+- [Documentation](https://spora.engineer/docs/sdk)
+- [API Reference](https://spora.engineer/docs)
+- [Get an API key](https://spora.engineer/request)

spora_sdk-2.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

spora_sdk-2.0.0/setup.py

@@ -0,0 +1,23 @@
+from setuptools import setup
+
+setup(
+    name="spora-sdk",
+    version="2.0.0",
+    description="Official Python SDK for the Spora agronomic intelligence API",
+    long_description=open("README.md").read() if __import__("os").path.exists("README.md") else "",
+    long_description_content_type="text/markdown",
+    py_modules=["spora"],
+    python_requires=">=3.9",
+    install_requires=["requests>=2.28.0"],
+    author="Spora",
+    author_email="hello.spora@yahoo.com",
+    url="https://spora.engineer",
+    project_urls={"Documentation": "https://spora.engineer/docs"},
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: MIT License",
+        "Topic :: Scientific/Engineering",
+        "Intended Audience :: Developers",
+    ],
+    keywords=["agronomy", "agriculture", "api", "plants", "crops"],
+)

spora_sdk-2.0.0/spora.py

@@ -0,0 +1,284 @@
+"""Spora Python SDK — official client for the Spora agronomic intelligence API."""
+
+from __future__ import annotations
+import time
+from typing import Any, Optional
+import requests
+
+
+class SporaError(Exception):
+    def __init__(self, status: int, error: str):
+        self.status = status
+        self.error = error
+        super().__init__(f"[{status}] {error}")
+
+
+class RateLimit:
+    def __init__(self):
+        self.limit: int = 0
+        self.remaining: int = 0
+        self.reset: int = 0
+
+
+class Spora:
+    """
+    Spora API client.
+
+    Usage:
+        from spora import Spora
+        client = Spora(api_key="spk_live_...")
+
+        # Free endpoints (no paid plan required)
+        species = client.search_species("Rosa", limit=5)
+        crop = client.get_crop("solanum_lycopersicum")
+
+        # Paid endpoints
+        result = client.ask("When should I irrigate my tomatoes in Sicily?")
+    """
+
+    BASE_URL = "https://api.spora.engineer"
+
+    def __init__(self, api_key: str, base_url: str = BASE_URL, max_retries: int = 2):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max_retries
+        self.rate_limit = RateLimit()
+        self._session = requests.Session()
+        self._session.headers.update({
+            "X-Api-Key": api_key,
+            "Content-Type": "application/json",
+        })
+
+    # ── Internal ──────────────────────────────────────────────────────────────
+
+    def _post(self, path: str, body: dict) -> Any:
+        url = f"{self.base_url}{path}"
+        for attempt in range(self.max_retries + 1):
+            r = self._session.post(url, json=body)
+            self._update_rate_limit(r)
+            if r.status_code == 429:
+                retry_after = int(r.headers.get("Retry-After", 60))
+                if attempt < self.max_retries:
+                    time.sleep(retry_after)
+                    continue
+                raise SporaError(429, "rate_limit_exceeded")
+            if r.status_code >= 400:
+                raise SporaError(r.status_code, r.json().get("error", "unknown_error"))
+            return r.json()
+        return {}
+
+    def _get(self, path: str, params: Optional[dict] = None) -> Any:
+        url = f"{self.base_url}{path}"
+        r = self._session.get(url, params={k: v for k, v in (params or {}).items() if v is not None})
+        self._update_rate_limit(r)
+        if r.status_code >= 400:
+            raise SporaError(r.status_code, r.json().get("error", "unknown_error"))
+        return r.json()
+
+    def _update_rate_limit(self, r: requests.Response):
+        self.rate_limit.limit = int(r.headers.get("X-RateLimit-Limit", 0))
+        self.rate_limit.remaining = int(r.headers.get("X-RateLimit-Remaining", 0))
+        self.rate_limit.reset = int(r.headers.get("X-RateLimit-Reset", 0))
+
+    # ── Free: Species ─────────────────────────────────────────────────────────
+
+    def search_species(self, q: str, *, limit: int = 10, fields: Optional[list[str]] = None) -> list:
+        return self._get("/species", {"q": q, "limit": limit, "fields": ",".join(fields) if fields else None})
+
+    def get_species(self, id: str, *, fields: Optional[list[str]] = None) -> dict:
+        return self._get(f"/species/{id}", {"fields": ",".join(fields) if fields else None})
+
+    def get_species_by_family(self, family: str, *, limit: int = 20) -> list:
+        return self._get("/species", {"family": family, "limit": limit})
+
+    # ── Free: Crops ───────────────────────────────────────────────────────────
+
+    def search_crops(self, q: Optional[str] = None, *, category: Optional[str] = None,
+                     limit: int = 10, fields: Optional[list[str]] = None) -> list:
+        return self._get("/crops", {"q": q, "category": category, "limit": limit,
+                                    "fields": ",".join(fields) if fields else None})
+
+    def get_crop(self, id: str, *, fields: Optional[list[str]] = None) -> dict:
+        return self._get(f"/crops/{id}", {"fields": ",".join(fields) if fields else None})
+
+    # ── Free: Flowers ─────────────────────────────────────────────────────────
+
+    def search_flowers(self, q: Optional[str] = None, *, month: Optional[int] = None,
+                       type: Optional[str] = None, pollinator: Optional[str] = None,
+                       limit: int = 30, fields: Optional[list[str]] = None) -> list:
+        return self._get("/flowers", {"q": q, "month": month, "type": type,
+                                      "pollinator": pollinator, "limit": limit,
+                                      "fields": ",".join(fields) if fields else None})
+
+    def get_flower(self, id: str) -> dict:
+        return self._get(f"/flowers/{id}")
+
+    # ── Free: Shrooms ─────────────────────────────────────────────────────────
+
+    def search_shrooms(self, q: Optional[str] = None, *, edibility: Optional[str] = None,
+                       habitat: Optional[str] = None, season: Optional[str] = None,
+                       limit: int = 20, fields: Optional[list[str]] = None) -> list:
+        return self._get("/shrooms", {"q": q, "edibility": edibility, "habitat": habitat,
+                                      "season": season, "limit": limit,
+                                      "fields": ",".join(fields) if fields else None})
+
+    def get_shroom(self, id: str) -> dict:
+        return self._get(f"/shrooms/{id}")
+
+    # ── Paid: Unified plant search ────────────────────────────────────────────
+
+    def search_plants(self, q: str, *, limit: int = 10, fields: Optional[list[str]] = None) -> list:
+        return self._get("/plants", {"q": q, "limit": limit,
+                                     "fields": ",".join(fields) if fields else None})
+
+    def get_plant(self, id: str, *, fields: Optional[list[str]] = None) -> dict:
+        return self._get(f"/plants/{id}", {"fields": ",".join(fields) if fields else None})
+
+    # ── Paid: Diseases & Pests ────────────────────────────────────────────────
+
+    def search_diseases(self, q: str, *, limit: int = 10, fields: Optional[list[str]] = None) -> list:
+        return self._get("/diseases", {"q": q, "limit": limit,
+                                       "fields": ",".join(fields) if fields else None})
+
+    def get_disease(self, id: str) -> dict:
+        return self._get(f"/diseases/{id}")
+
+    def search_pests(self, q: str, *, limit: int = 10) -> list:
+        return self._get("/pests", {"q": q, "limit": limit})
+
+    # ── Paid: Companions ──────────────────────────────────────────────────────
+
+    def search_companions(self, q: Optional[str] = None, *, utility: Optional[str] = None,
+                          layer: Optional[str] = None, nitrogen_fixing: Optional[bool] = None,
+                          limit: int = 10, fields: Optional[list[str]] = None) -> list:
+        return self._get("/companions", {"q": q, "utility": utility, "layer": layer,
+                                         "nitrogen_fixing": str(nitrogen_fixing).lower() if nitrogen_fixing is not None else None,
+                                         "limit": limit, "fields": ",".join(fields) if fields else None})
+
+    # ── Paid: Agronomic data ──────────────────────────────────────────────────
+
+    def get_nutrition(self, country: str) -> dict:
+        return self._get(f"/nutrition/{country}")
+
+    def get_irrigation(self, country: str) -> dict:
+        return self._get(f"/irrigation/{country}")
+
+    def get_harvest(self, location: str) -> dict:
+        return self._get(f"/harvest/{location}")
+
+    def get_climate_zone(self, *, lat: Optional[float] = None, lon: Optional[float] = None,
+                         country: Optional[str] = None) -> dict:
+        return self._get("/climate_zones", {"lat": lat, "lon": lon, "country": country})
+
+    # ── Paid: Weather ─────────────────────────────────────────────────────────
+
+    def weather(self, lat: float, lon: float, *, days: int = 7, hourly: bool = False) -> dict:
+        return self._post("/weather", {"lat": lat, "lon": lon, "days": days, "hourly": hourly})
+
+    def weather_history(self, lat: float, lon: float, start_date: str, end_date: str) -> dict:
+        return self._post("/weather_history", {"lat": lat, "lon": lon,
+                                               "start_date": start_date, "end_date": end_date})
+
+    def should_water(self, lat: float, lon: float, crop: str, *,
+                     soil_moisture_pct: Optional[float] = None) -> dict:
+        body: dict = {"lat": lat, "lon": lon, "crop": crop}
+        if soil_moisture_pct is not None:
+            body["soil_moisture_pct"] = soil_moisture_pct
+        return self._post("/should_water", body)
+
+    # ── Paid: AI endpoints ────────────────────────────────────────────────────
+
+    def ask(self, question: str, *, crop: Optional[str] = None,
+            lat: Optional[float] = None, lon: Optional[float] = None,
+            image_base64: Optional[str] = None,
+            tone: str = "expanded") -> dict:
+        body: dict = {"question": question, "tone": tone}
+        if crop: body["crop"] = crop
+        if lat is not None: body["lat"] = lat
+        if lon is not None: body["lon"] = lon
+        if image_base64: body["image_base64"] = image_base64
+        return self._post("/ask", body)
+
+    def identify(self, image_base64: str, *, context: Optional[str] = None) -> dict:
+        body: dict = {"image_base64": image_base64}
+        if context: body["context"] = context
+        return self._post("/identify", body)
+
+    def vision_ask(self, image_base64: str, question: str, *, context: Optional[str] = None) -> dict:
+        body: dict = {"image_base64": image_base64, "question": question}
+        if context: body["context"] = context
+        return self._post("/vision/ask", body)
+
+    def diagnose(self, *, image_base64: Optional[str] = None, crop: Optional[str] = None,
+                 symptoms: Optional[str] = None, lat: Optional[float] = None,
+                 lon: Optional[float] = None) -> dict:
+        body = {k: v for k, v in {"image_base64": image_base64, "crop": crop,
+                                   "symptoms": symptoms, "lat": lat, "lon": lon}.items() if v is not None}
+        return self._post("/diagnose", body)
+
+    def recommend_crops(self, lat: float, lon: float, *, soil_type: Optional[str] = None,
+                        water_availability: Optional[str] = None,
+                        cycle_days_max: Optional[int] = None,
+                        category: Optional[str] = None, tone: str = "expanded") -> dict:
+        body: dict = {"lat": lat, "lon": lon, "tone": tone}
+        if soil_type: body["soil_type"] = soil_type
+        if water_availability: body["water_availability"] = water_availability
+        if cycle_days_max: body["cycle_days_max"] = cycle_days_max
+        if category: body["category"] = category
+        return self._post("/recommend_crops", body)
+
+    def plan_companion(self, crop_id: str, *,
+                       goals: Optional[list[str]] = None, tone: str = "expanded") -> dict:
+        body: dict = {"crop_id": crop_id, "tone": tone}
+        if goals: body["goals"] = goals
+        return self._post("/plan_companion", body)
+
+    def scouting_report(self, lat: float, lon: float, crop: str, *,
+                        symptoms: Optional[str] = None, tone: str = "expanded") -> dict:
+        body: dict = {"lat": lat, "lon": lon, "crop": crop, "tone": tone}
+        if symptoms: body["symptoms"] = symptoms
+        return self._post("/scouting_report", body)
+
+    # ── Paid: Watch Rules ─────────────────────────────────────────────────────
+
+    def create_watch_rule(self, name: str, condition: dict, webhook_url: str,
+                          webhook_secret: str, *, description: Optional[str] = None,
+                          trigger_mode: str = "scheduled", lat: Optional[float] = None,
+                          lon: Optional[float] = None, crop: Optional[str] = None,
+                          eval_interval_minutes: int = 15,
+                          cooldown_minutes: int = 60) -> dict:
+        body: dict = {"name": name, "condition": condition, "webhook_url": webhook_url,
+                      "webhook_secret": webhook_secret, "trigger_mode": trigger_mode,
+                      "eval_interval_minutes": eval_interval_minutes,
+                      "cooldown_minutes": cooldown_minutes}
+        if description: body["description"] = description
+        if lat is not None: body["lat"] = lat
+        if lon is not None: body["lon"] = lon
+        if crop: body["crop"] = crop
+        return self._post("/watch", body)
+
+    def list_watch_rules(self) -> list:
+        return self._get("/watch")
+
+    def push_event(self, rule_id: str, payload: dict) -> dict:
+        return self._post(f"/watch/ingest/{rule_id}", payload)
+
+    # ── Paid: Approvals ───────────────────────────────────────────────────────
+
+    def request_approval(self, action: str, description: str, *,
+                         risk_level: str = "high", payload: Optional[dict] = None,
+                         callback_url: Optional[str] = None,
+                         ttl_minutes: int = 30) -> dict:
+        body: dict = {"action": action, "description": description,
+                      "risk_level": risk_level, "ttl_minutes": ttl_minutes}
+        if payload: body["payload"] = payload
+        if callback_url: body["callback_url"] = callback_url
+        return self._post("/approvals", body)
+
+    def get_approval(self, approval_id: str) -> dict:
+        return self._get(f"/approvals/{approval_id}")
+
+    # ── Batch ─────────────────────────────────────────────────────────────────
+
+    def batch(self, calls: list[tuple[str, dict]]) -> dict:
+        return self._post("/batch", {"calls": [{"method": m, "params": p} for m, p in calls]})

spora_sdk-2.0.0/spora_sdk.egg-info/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: spora-sdk
+Version: 2.0.0
+Summary: Official Python SDK for the Spora agronomic intelligence API
+Home-page: https://spora.engineer
+Author: Spora
+Author-email: hello.spora@yahoo.com
+Project-URL: Documentation, https://spora.engineer/docs
+Keywords: agronomy,agriculture,api,plants,crops
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Scientific/Engineering
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Spora Python SDK
+
+Official Python client for the [Spora agronomic intelligence API](https://spora.engineer).
+
+## Installation
+
+```bash
+pip install spora-sdk
+```
+
+## Quick start
+
+```python
+from spora import Spora
+
+client = Spora(api_key="spk_live_your_key_here")
+
+# Search species
+species = client.search_species("Rosa", limit=5)
+
+# Get crop requirements
+crop = client.get_crop("solanum_lycopersicum")
+print(crop["temp_optimal_min"], crop["temp_optimal_max"])
+
+# AI question (paid key)
+answer = client.ask(
+    "When should I irrigate my tomatoes?",
+    crop="solanum_lycopersicum",
+    lat=45.4, lon=11.0,
+    tone="concise",
+)
+print(answer["response"])
+
+# Batch
+results = client.batch([
+    ("weather",      {"lat": 45.4, "lon": 11.0, "days": 3}),
+    ("should_water", {"lat": 45.4, "lon": 11.0, "crop": "vitis_vinifera"}),
+])
+```
+
+## Error handling
+
+```python
+from spora import Spora, SporaError
+
+client = Spora(api_key="spk_live_your_key_here")
+
+try:
+    result = client.ask("Best cover crop for clay soil?")
+except SporaError as e:
+    print(e.status, e.error)
+
+print(client.rate_limit.remaining, "/", client.rate_limit.limit)
+```
+
+## Links
+
+- [Documentation](https://spora.engineer/docs/sdk)
+- [API Reference](https://spora.engineer/docs)
+- [Get an API key](https://spora.engineer/request)

spora_sdk-2.0.0/spora_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,8 @@
+README.md
+setup.py
+spora.py
+spora_sdk.egg-info/PKG-INFO
+spora_sdk.egg-info/SOURCES.txt
+spora_sdk.egg-info/dependency_links.txt
+spora_sdk.egg-info/requires.txt
+spora_sdk.egg-info/top_level.txt

spora_sdk-2.0.0/spora_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

spora_sdk-2.0.0/spora_sdk.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.28.0

spora_sdk-2.0.0/spora_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+spora