askamerica 0.1.0__tar.gz

askamerica-0.1.0/.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+.dev.vars
+.wrangler/

askamerica-0.1.0/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: askamerica
+Version: 0.1.0
+Summary: Query US government data with a single line of Python
+Project-URL: Homepage, https://askamerica.ai
+Project-URL: Documentation, https://askamerica.ai/docs
+Project-URL: Issues, https://github.com/askamerica/askamerica-python/issues
+Author-email: AskAmerica <support@askamerica.ai>
+License: MIT
+Keywords: data,government,open-data,sql
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.8
+Requires-Dist: duckdb>=0.9.0
+Requires-Dist: requests>=2.28.0
+Description-Content-Type: text/markdown
+
+# AskAmerica
+
+Query US government data with a single line of Python.
+
+```python
+pip install askamerica
+```
+
+```python
+import askamerica
+
+askamerica.configure(api_key="aa_free_...")
+df = askamerica.query("SELECT * FROM sec.filings WHERE year = 2024 LIMIT 100")
+```
+
+Sign up for a free API key at [askamerica.ai](https://askamerica.ai).

askamerica-0.1.0/README.md

@@ -0,0 +1,16 @@
+# AskAmerica
+
+Query US government data with a single line of Python.
+
+```python
+pip install askamerica
+```
+
+```python
+import askamerica
+
+askamerica.configure(api_key="aa_free_...")
+df = askamerica.query("SELECT * FROM sec.filings WHERE year = 2024 LIMIT 100")
+```
+
+Sign up for a free API key at [askamerica.ai](https://askamerica.ai).

askamerica-0.1.0/askamerica/__init__.py

@@ -0,0 +1,24 @@
+from .client import query
+from .auth import login
+from .quota import get_quota
+from .config import get_api_key
+from .exceptions import AskAmericaError, AuthError, QuotaExceededError, QueryError
+
+__version__ = "0.1.0"
+__all__ = [
+    "query",
+    "login",
+    "get_quota",
+    "get_api_key",
+    "AskAmericaError",
+    "AuthError",
+    "QuotaExceededError",
+    "QueryError",
+]
+
+
+def configure(api_key: str) -> None:
+    from .config import save_config, load_config
+    config = load_config()
+    config["api_key"] = api_key
+    save_config(config)

askamerica-0.1.0/askamerica/auth.py

@@ -0,0 +1,29 @@
+import getpass
+import requests
+from typing import Optional
+from .config import API_BASE_URL, save_config
+from .exceptions import AuthError
+
+
+def login(email: Optional[str] = None) -> str:
+    if email is None:
+        email = input("Email: ").strip()
+
+    r = requests.post(f"{API_BASE_URL}/v1/auth/request-otp", json={"email": email})
+    if not r.ok:
+        raise AuthError(f"Failed to send OTP: {r.text}")
+
+    print(f"A 6-digit code has been sent to {email}.")
+    code = getpass.getpass("Enter code: ").strip()
+
+    r = requests.post(f"{API_BASE_URL}/v1/auth/verify-otp", json={"email": email, "code": code})
+    if not r.ok:
+        data = r.json()
+        raise AuthError(data.get("error", "verification failed"))
+
+    data = r.json()
+    api_key = data["api_key"]
+    save_config({"api_key": api_key, "email": email, "tier": data["tier"]})
+    print(f"Logged in. API key saved to ~/.askamerica/config.json")
+    print(f"Tier: {data['tier']} — {data['quota_gb']} GB/month")
+    return api_key

askamerica-0.1.0/askamerica/cli.py

@@ -0,0 +1,72 @@
+import sys
+import argparse
+from .auth import login
+from .quota import get_quota
+from .config import get_api_key
+from .exceptions import AuthError
+
+
+def cmd_login(args: argparse.Namespace) -> None:
+    login(email=getattr(args, "email", None))
+
+
+def cmd_quota(args: argparse.Namespace) -> None:
+    key = get_api_key()
+    if not key:
+        print("Not logged in. Run: askamerica login")
+        sys.exit(1)
+    try:
+        quota = get_quota(key)
+        used_gb = quota["used_bytes"] / (1024 ** 3)
+        limit_gb = quota["limit_bytes"] / (1024 ** 3)
+        remaining_gb = quota["remaining_bytes"] / (1024 ** 3)
+        pct = (quota["used_bytes"] / quota["limit_bytes"]) * 100
+        print(f"Period:    {quota['period']}")
+        print(f"Used:      {used_gb:.3f} GB of {limit_gb:.0f} GB ({pct:.1f}%)")
+        print(f"Remaining: {remaining_gb:.3f} GB")
+        if quota["remaining_bytes"] < quota["limit_bytes"] * 0.2:
+            print(f"Upgrade:   {quota['upgrade_url']}")
+    except AuthError as e:
+        print(f"Error: {e}")
+        sys.exit(1)
+
+
+def cmd_whoami(args: argparse.Namespace) -> None:
+    from .config import load_config
+    config = load_config()
+    if not config:
+        print("Not logged in. Run: askamerica login")
+        sys.exit(1)
+    print(f"Email: {config.get('email', 'unknown')}")
+    print(f"Tier:  {config.get('tier', 'free')}")
+    key = config.get("api_key", "")
+    print(f"Key:   {key[:12]}...{key[-4:] if len(key) > 16 else ''}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="askamerica",
+        description="AskAmerica — query US government data",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    p_login = sub.add_parser("login", help="Authenticate and get an API key")
+    p_login.add_argument("--email", help="Email address (optional, prompted if omitted)")
+
+    sub.add_parser("quota", help="Show current quota usage")
+    sub.add_parser("whoami", help="Show current login info")
+
+    args = parser.parse_args()
+
+    if args.command == "login":
+        cmd_login(args)
+    elif args.command == "quota":
+        cmd_quota(args)
+    elif args.command == "whoami":
+        cmd_whoami(args)
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

askamerica-0.1.0/askamerica/client.py

@@ -0,0 +1,97 @@
+import time
+import uuid
+import duckdb
+from typing import Any, Optional
+
+from .config import get_api_key
+from .exceptions import AuthError, QueryError
+from .quota import check_quota, report_usage
+
+ICEBERG_CATALOG_URL = "https://api.askamerica.ai/v1/catalog"
+
+
+def _get_connection(api_key: str) -> duckdb.DuckDBPyConnection:
+    con = duckdb.connect()
+    con.execute("INSTALL iceberg; LOAD iceberg;")
+    con.execute("INSTALL httpfs; LOAD httpfs;")
+    con.execute(f"""
+        CREATE SECRET askamerica_r2 (
+            TYPE S3,
+            PROVIDER CREDENTIAL_CHAIN,
+            ENDPOINT 'api.askamerica.ai/v1/catalog/credentials',
+            EXTRA_HTTP_HEADERS MAP {{
+                'X-API-Key': '{api_key}'
+            }}
+        )
+    """)
+    return con
+
+
+def query(
+    sql: str,
+    api_key: Optional[str] = None,
+    return_type: str = "df",
+) -> Any:
+    key = api_key or get_api_key()
+    if not key:
+        raise AuthError("No API key configured. Run: askamerica login")
+
+    quota = check_quota(key)
+
+    query_id = str(uuid.uuid4())
+    start_ms = time.time() * 1000
+
+    try:
+        con = duckdb.connect()
+        con.execute("INSTALL httpfs; LOAD httpfs;")
+
+        result = con.execute(sql)
+
+        duration_ms = int(time.time() * 1000 - start_ms)
+
+        if return_type == "df":
+            df = result.df()
+            row_count = len(df)
+            actual_bytes = df.memory_usage(deep=True).sum()
+        elif return_type == "arrow":
+            df = result.arrow()
+            row_count = df.num_rows
+            actual_bytes = df.nbytes
+        else:
+            raise QueryError(f"Unknown return_type: {return_type}. Use 'df' or 'arrow'.")
+
+        report_usage(
+            query_id=query_id,
+            table=_extract_table(sql),
+            planned_bytes=actual_bytes,
+            actual_bytes=actual_bytes,
+            row_count=row_count,
+            duration_ms=duration_ms,
+            query_text=sql,
+            api_key=key,
+        )
+
+        _print_quota_reminder(quota, actual_bytes)
+        return df
+
+    except duckdb.Error as e:
+        raise QueryError(str(e)) from e
+
+
+def _extract_table(sql: str) -> str:
+    import re
+    match = re.search(r'\bFROM\s+([\w.]+)', sql, re.IGNORECASE)
+    return match.group(1) if match else "unknown"
+
+
+def _print_quota_reminder(quota: dict, used_bytes: int) -> None:
+    remaining = quota["remaining_bytes"] - used_bytes
+    limit = quota["limit_bytes"]
+    pct_used = ((limit - remaining) / limit) * 100
+    remaining_gb = remaining / (1024 ** 3)
+    if pct_used >= 80:
+        print(
+            f"[askamerica] {pct_used:.0f}% of monthly quota used. "
+            f"{remaining_gb:.2f} GB remaining. "
+            f"Upgrade at https://askamerica.ai/upgrade"
+        )

askamerica-0.1.0/askamerica/config.py

@@ -0,0 +1,24 @@
+import os
+import json
+from pathlib import Path
+from typing import Optional
+
+API_BASE_URL = "https://api.askamerica.ai"
+CONFIG_PATH = Path.home() / ".askamerica" / "config.json"
+
+
+def load_config() -> dict:
+    if CONFIG_PATH.exists():
+        with open(CONFIG_PATH) as f:
+            return json.load(f)
+    return {}
+
+
+def save_config(config: dict) -> None:
+    CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    with open(CONFIG_PATH, "w") as f:
+        json.dump(config, f, indent=2)
+
+
+def get_api_key() -> Optional[str]:
+    return os.environ.get("ASKAMERICA_API_KEY") or load_config().get("api_key")

askamerica-0.1.0/askamerica/exceptions.py

@@ -0,0 +1,20 @@
+class AskAmericaError(Exception):
+    pass
+
+
+class AuthError(AskAmericaError):
+    pass
+
+
+class QuotaExceededError(AskAmericaError):
+    def __init__(self, remaining_bytes: int, period: str):
+        self.remaining_bytes = remaining_bytes
+        self.period = period
+        super().__init__(
+            f"Monthly quota exceeded for {period}. "
+            f"Upgrade at https://askamerica.ai/upgrade"
+        )
+
+
+class QueryError(AskAmericaError):
+    pass

askamerica-0.1.0/askamerica/quota.py

@@ -0,0 +1,72 @@
+import time
+import requests
+from typing import Optional
+from .config import API_BASE_URL, get_api_key
+from .exceptions import AuthError, QuotaExceededError
+
+_cache: dict = {}
+_cache_ttl = 300  # 5 minutes
+
+
+def get_quota(api_key: Optional[str] = None) -> dict:
+    key = api_key or get_api_key()
+    if not key:
+        raise AuthError("No API key. Run: askamerica login")
+
+    now = time.time()
+    if _cache.get("expires_at", 0) > now:
+        return _cache["data"]
+
+    r = requests.get(f"{API_BASE_URL}/v1/quota", headers={"X-API-Key": key})
+    if r.status_code == 401:
+        raise AuthError("Invalid API key. Run: askamerica login")
+    r.raise_for_status()
+
+    data = r.json()
+    _cache["data"] = data
+    _cache["expires_at"] = now + _cache_ttl
+    return data
+
+
+def check_quota(api_key: Optional[str] = None) -> dict:
+    quota = get_quota(api_key)
+    if quota["remaining_bytes"] <= 0:
+        raise QuotaExceededError(
+            remaining_bytes=quota["remaining_bytes"],
+            period=quota["period"],
+        )
+    return quota
+
+
+def report_usage(
+    query_id: str,
+    table: str,
+    planned_bytes: int,
+    actual_bytes: int,
+    row_count: int,
+    duration_ms: int,
+    query_text: str,
+    api_key: Optional[str] = None,
+) -> None:
+    key = api_key or get_api_key()
+    if not key:
+        return
+    try:
+        requests.post(
+            f"{API_BASE_URL}/v1/metering/usage",
+            headers={"X-API-Key": key},
+            json={
+                "query_id": query_id,
+                "table": table,
+                "planned_bytes": planned_bytes,
+                "actual_bytes": actual_bytes,
+                "row_count": row_count,
+                "duration_ms": duration_ms,
+                "query_text": query_text,
+            },
+            timeout=5,
+        )
+        # invalidate quota cache after reporting
+        _cache.clear()
+    except Exception:
+        pass  # metering is best-effort, never block the user

askamerica-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "askamerica"
+version = "0.1.0"
+description = "Query US government data with a single line of Python"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.8"
+authors = [{ name = "AskAmerica", email = "support@askamerica.ai" }]
+keywords = ["government", "data", "sql", "open-data"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Information Analysis",
+]
+dependencies = [
+  "requests>=2.28.0",
+  "duckdb>=0.9.0",
+]
+
+[project.urls]
+Homepage = "https://askamerica.ai"
+Documentation = "https://askamerica.ai/docs"
+Issues = "https://github.com/askamerica/askamerica-python/issues"
+
+[project.scripts]
+askamerica = "askamerica.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["askamerica"]