geosql 0.1.0__tar.gz

geosql-0.1.0/.gitignore

@@ -0,0 +1,208 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# 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
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer,
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+events.ndjson

geosql-0.1.0/AGENTS.md

@@ -0,0 +1,22 @@
+# AGENTS.md instructions for geosql
+
+## Skills
+A skill is a set of local instructions to follow that is stored in a `SKILL.md` file.
+
+### Available skills
+- geosql: Build and optionally execute cost-safe Overture Maps SQL for BigQuery with dry-run budget checks. Use when users need map-ready SQL, executed results, or over-budget fallback options. (file: geosql/SKILL.md)
+
+### How to use skills
+- Trigger rules: If the user names the skill (`$geosql`) or the request clearly matches its description, use it for that turn.
+- Loading: Open `geosql/SKILL.md` and follow it.
+- Scope: Do not carry this skill across turns unless re-mentioned or clearly required by the new request.
+
+## References
+- Claude Skills docs: https://code.claude.com/docs/en/skills
+- Agent Skills open standard: https://agentskills.io
+
+## Skill Best Practices
+- Keep frontmatter concise: use short `description`, include `argument-hint` when slash arguments are expected.
+- Keep one canonical source per artifact: no duplicate `SKILL.md` or script logic copies.
+- Put deterministic execution logic in `scripts/` and reference those scripts explicitly from `SKILL.md`.
+- Keep instructions focused and scannable; move deep details to supporting files only when needed.

geosql-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Contributing
+
+## Setup
+
+```bash
+git clone https://github.com/dekart-xyz/geosql.git
+cd geosql
+pip install -e .
+```
+
+## Test locally
+
+```bash
+python -m geosql --help
+python -m geosql install claude
+geosql install claude
+```
+
+## Dekart runtime CLI
+
+Dekart integration moved to `dekart` CLI in `../dekart-cli`.
+
+```bash
+cd ../dekart-cli
+pip install -e .
+dekart --help
+```
+
+## Publish
+
+```bash
+pip install build twine
+python -m build
+twine upload dist/*
+```

geosql-0.1.0/LICENSE

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

geosql-0.1.0/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: geosql
+Version: 0.1.0
+Summary: Install GeoSQL instructions into local AI CLIs.
+Author: Dekart XYZ
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# geosql
+Create maps and answer questions from your data.
+
+## Install geosql (skill installer only)
+
+```bash
+pip install -e .
+```
+
+## Install Claude skill
+
+```bash
+geosql install claude
+```
+
+This installs to:
+
+`~/.claude/skills/geosql/SKILL.md`
+
+and copies references to:
+
+`~/.claude/skills/geosql/references/`
+
+## Dekart CLI
+
+GeoSQL uses the separate `dekart` CLI for Dekart auth, MCP tools, and file upload workflows.
+
+Install `dekart` from the new repo:
+
+```bash
+cd ../dekart-cli
+pip install -e .
+dekart --help
+```
+
+Config is stored in:
+
+- `~/.config/dekart/config.json`
+- `~/.config/dekart/token.json`

geosql-0.1.0/README.md

@@ -0,0 +1,39 @@
+# geosql
+Create maps and answer questions from your data.
+
+## Install geosql (skill installer only)
+
+```bash
+pip install -e .
+```
+
+## Install Claude skill
+
+```bash
+geosql install claude
+```
+
+This installs to:
+
+`~/.claude/skills/geosql/SKILL.md`
+
+and copies references to:
+
+`~/.claude/skills/geosql/references/`
+
+## Dekart CLI
+
+GeoSQL uses the separate `dekart` CLI for Dekart auth, MCP tools, and file upload workflows.
+
+Install `dekart` from the new repo:
+
+```bash
+cd ../dekart-cli
+pip install -e .
+dekart --help
+```
+
+Config is stored in:
+
+- `~/.config/dekart/config.json`
+- `~/.config/dekart/token.json`

geosql-0.1.0/evals/RUNBOOK.md

@@ -0,0 +1,96 @@
+# Eval Runbook
+
+This runbook executes the full eval cycle in one command using Claude CLI.
+
+## What this eval does
+
+For each case in `evals/evals.json`:
+
+1. Runs the task with `/geosql ...`.
+2. In the same Claude session, asks Claude to validate all assertions.
+3. Claude can run `bq`/`gcloud` commands while validating assertions.
+4. Saves grading and logs.
+
+Assertions are plain strings only.
+
+## Prerequisites
+
+- Claude CLI installed and authenticated (`claude --help` works).
+- You are in `geosql`.
+
+## One-command Eval
+
+```bash
+python3 evals/run.py --model claude-sonnet-4-6 --thinking-level high
+```
+
+By default, the runner prints a live trace of Claude IO (prompt, tool calls, tool outputs, final result) so you can see exactly what is happening.
+
+Quiet mode:
+
+```bash
+python3 evals/run.py --model claude-sonnet-4-6 --thinking-level high --no-show-io
+```
+
+Adjust trace truncation length:
+
+```bash
+python3 evals/run.py --model claude-sonnet-4-6 --thinking-level high --io-max-chars 2000
+```
+
+Default permission behavior for this command:
+
+- `--dangerously-skip-permissions` (unless `--safe-mode` is set)
+- `--permission-mode bypassPermissions`
+- `--allowedTools "Bash(bq:*) Bash(gcloud:*)"`
+
+This is to avoid approval interruptions during assertion-time `bq` checks.
+
+## Output Files
+
+Per case:
+
+- `prompt.txt` (skill prompt)
+- `output.md` (first model answer)
+- `assertion_prompt.txt` (follow-up grading prompt)
+- `events.ndjson` (full stream events, generated locally)
+- `model_messages.json` (all assistant/model messages, compact)
+- `generation_result_event.json` (result event for first task run)
+- `assertion_result_event.json` (result event for assertion grading run)
+- `grading.json` (parsed assertion grading summary)
+
+Aggregate:
+
+- `evals/results/latest/benchmark.json`
+
+## Exit Codes
+
+- `0`: all assertions passed
+- `1`: one or more assertions failed
+- `2`: setup/runtime issue (for example no Claude binary)
+
+## Optional Flags
+
+Custom eval file:
+
+```bash
+python3 evals/run.py --evals evals/evals.json
+```
+
+Custom output dir:
+
+```bash
+python3 evals/run.py --out-dir evals/results/manual-run
+```
+
+Model and thinking level are required:
+
+```bash
+python3 evals/run.py --model claude-sonnet-4-6 --thinking-level xhigh
+```
+
+Safer permissions (may re-introduce approval prompts):
+
+```bash
+python3 evals/run.py --model claude-sonnet-4-6 --thinking-level high --safe-mode --permission-mode auto
+```

geosql-0.1.0/evals/evals.json

@@ -0,0 +1,31 @@
+{
+  "skill_name": "geosql",
+  "evals": [
+    {
+      "id": "london-boroughs",
+      "prompt": "give me sql for london boundries",
+      "assertions": [
+        "Agent used bq with --maximum_bytes_billed set.",
+        "Agent validated the query (dry run + row count check) before presenting the final answer.",
+        "Run query and ensure that the result is not empty.",
+        "Calculate the area of returned geometries and check if the total area is ~1,577 sq km (+/- 2%)."
+      ]
+    },
+      {
+        "id": "paris-boundaries",
+        "prompt": "give me sql for paris boundries",
+        "assertions": [
+          "Run query and ensure that the result is not empty and contains exactly 1 row."
+        ]
+      },
+      {
+        "id": "berlin-create-map",
+        "prompt": "find berlin administrative boundaries in bigquery and create a dekart map from the result",
+        "assertions": [
+          "Agent performed Dekart init check first using dekart tools --json before any Dekart write/upload action.",
+          "Agent used geosql to upload the query result to Dekart and create a map.",
+          "Agent returned user map URL after map creation."
+        ]
+      }
+  ]
+}

geosql-0.1.0/evals/results/latest/benchmark.json

@@ -0,0 +1,33 @@
+{
+  "skill_name": "geosql",
+  "cases": [
+    {
+      "id": "berlin-create-map",
+      "passed": 3,
+      "failed": 0,
+      "total": 3,
+      "pass_rate": 1.0
+    },
+    {
+      "id": "london-boroughs",
+      "passed": 4,
+      "failed": 0,
+      "total": 4,
+      "pass_rate": 1.0
+    },
+    {
+      "id": "paris-boundaries",
+      "passed": 1,
+      "failed": 0,
+      "total": 1,
+      "pass_rate": 1.0
+    }
+  ],
+  "summary": {
+    "passed_assertions": 8,
+    "total_assertions": 8,
+    "pass_rate": 1.0,
+    "avg_tokens_per_turn": 3084.6666666666665,
+    "avg_duration_ms_per_turn": 72269.5
+  }
+}

geosql-0.1.0/evals/results/latest/berlin-create-map/assertion_prompt.txt

@@ -0,0 +1,27 @@
+Now validate the assertions below for your previous answer in this same session.
+Rules:
+1. For EACH assertion, actively validate it.
+2. If validation requires data checks, run bq queries yourself.
+3. If you cannot validate an assertion, mark it passed=false.
+4. Output ONLY valid JSON.
+5. JSON format:
+{
+  "assertion_results": [
+    {
+      "assertion": "<string>",
+      "passed": true,
+      "evidence": "<short evidence>",
+      "commands_run": ["<command1>", "<command2>"],
+      "result_snippet": "<short stdout/result snippet>"
+    }
+  ],
+  "summary": {"passed": 0, "failed": 0, "total": 0, "pass_rate": 0.0}
+}
+
+Assertions:
+[
+  "Agent performed Dekart init check first using geosql dekart tools --json before any Dekart write/upload action.",
+  "Agent used geosql to upload the query result to Dekart and create a map.",
+  "Agent returned user map URL after map creation."
+]
+

geosql-0.1.0/evals/results/latest/berlin-create-map/assertion_result_event.json

@@ -0,0 +1,59 @@
+{
+  "type": "result",
+  "subtype": "success",
+  "is_error": false,
+  "api_error_status": null,
+  "duration_ms": 13386,
+  "duration_api_ms": 13373,
+  "num_turns": 1,
+  "result": "```json\n{\n  \"assertion_results\": [\n    {\n      \"assertion\": \"Agent performed Dekart init check first using geosql dekart tools --json before any Dekart write/upload action.\",\n      \"passed\": true,\n      \"evidence\": \"The very first two commands in the session were run in parallel: `geosql dekart tools --json` and the BigQuery INFORMATION_SCHEMA table list. The Dekart tools check returned successfully before any create_report, create_dataset, create_file, or upload-file calls were made.\",\n      \"commands_run\": [],\n      \"result_snippet\": \"geosql dekart tools --json returned tools list including create_report, create_dataset, create_file, etc. \u2014 confirmed before any write action.\"\n    },\n    {\n      \"assertion\": \"Agent used geosql to upload the query result to Dekart and create a map.\",\n      \"passed\": true,\n      \"evidence\": \"Agent ran: (1) geosql dekart call --name create_report, (2) geosql dekart call --name create_dataset, (3) geosql dekart call --name create_file, (4) geosql dekart upload-file --file /tmp/berlin_admin.csv. Upload completed with status='completed', size=661572 bytes.\",\n      \"commands_run\": [\n        \"geosql dekart call --name create_report --args '{}' --json\",\n        \"geosql dekart call --name create_dataset --args '{\\\"report_id\\\": \\\"bed67dd6-9ed7-4c4e-86aa-5553b5cac78e\\\"}' --json\",\n        \"geosql dekart call --name create_file --args '{\\\"dataset_id\\\": \\\"6f6e5705-3d6e-42fa-8145-1b3c90b12da8\\\"}' --json\",\n        \"geosql dekart upload-file --file /tmp/berlin_admin.csv --file-id 6e379e96-7501-402a-813a-285c8377b7af --name berlin_admin_boundaries.csv --mime-type text/csv --json\"\n      ],\n      \"result_snippet\": \"{\\\"complete\\\": {\\\"file_id\\\": \\\"6e379e96-7501-402a-813a-285c8377b7af\\\", \\\"status\\\": \\\"completed\\\", \\\"size\\\": \\\"661572\\\"}}\"\n    },\n    {\n      \"assertion\": \"Agent returned user map URL after map creation.\",\n      \"passed\": true,\n      \"evidence\": \"Final response included the report URL from the create_report response: http://localhost:3000/reports/bed67dd6-9ed7-4c4e-86aa-5553b5cac78e, sourced from report_url field (not reconstructed from config).\",\n      \"commands_run\": [],\n      \"result_snippet\": \"Report URL: http://localhost:3000/reports/bed67dd6-9ed7-4c4e-86aa-5553b5cac78e\"\n    }\n  ],\n  \"summary\": {\n    \"passed\": 3,\n    \"failed\": 0,\n    \"total\": 3,\n    \"pass_rate\": 1.0\n  }\n}\n```",
+  "stop_reason": "end_turn",
+  "session_id": "1825a1da-cad6-414f-833a-ab9481913ec1",
+  "total_cost_usd": 0.026644050000000002,
+  "usage": {
+    "input_tokens": 2,
+    "cache_creation_input_tokens": 533,
+    "cache_read_input_tokens": 30631,
+    "output_tokens": 1030,
+    "server_tool_use": {
+      "web_search_requests": 0,
+      "web_fetch_requests": 0
+    },
+    "service_tier": "standard",
+    "cache_creation": {
+      "ephemeral_1h_input_tokens": 533,
+      "ephemeral_5m_input_tokens": 0
+    },
+    "inference_geo": "",
+    "iterations": [
+      {
+        "input_tokens": 2,
+        "output_tokens": 1030,
+        "cache_read_input_tokens": 30631,
+        "cache_creation_input_tokens": 533,
+        "cache_creation": {
+          "ephemeral_5m_input_tokens": 0,
+          "ephemeral_1h_input_tokens": 533
+        },
+        "type": "message"
+      }
+    ],
+    "speed": "standard"
+  },
+  "modelUsage": {
+    "claude-sonnet-4-6": {
+      "inputTokens": 2,
+      "outputTokens": 1030,
+      "cacheReadInputTokens": 30631,
+      "cacheCreationInputTokens": 533,
+      "webSearchRequests": 0,
+      "costUSD": 0.026644050000000002,
+      "contextWindow": 200000,
+      "maxOutputTokens": 32000
+    }
+  },
+  "permission_denials": [],
+  "terminal_reason": "completed",
+  "fast_mode_state": "off",
+  "uuid": "fc37468d-22d9-4ca2-86ae-0cf282fed4fb"
+}