dss-ai-tools 0.4.0__tar.gz

dss_ai_tools-0.4.0/.gitignore

@@ -0,0 +1,19 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+build/
+dist/
+
+# Env / secrets
+.env
+*.env
+
+# OS
+.DS_Store
+
+# Editor
+.idea/
+.vscode/

dss_ai_tools-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Institute of Mathematics and Computer Science, University of Latvia (IMCS)
+
+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.

dss_ai_tools-0.4.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: dss-ai-tools
+Version: 0.4.0
+Summary: Command-line client for exploring a Data Shape Server (DSS) knowledge-graph schemas.
+Project-URL: Homepage, https://github.com/LUMII-Syslab/dss-ai-tools
+Project-URL: Repository, https://github.com/LUMII-Syslab/dss-ai-tools
+Author: Institute of Mathematics and Computer Science, University of Latvia (IMCS)
+License: MIT
+License-File: LICENSE
+Keywords: claude,data-shape-server,dss,knowledge-graphs,mcp,rdf,sparql
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# dss-ai-tools
+
+Tools for exploring a [Data Shape Server (DSS)](https://github.com/LUMII-Syslab/data-shape-server) knowledge-graph schema — classes, properties, their relations, and namespaces — over the DSS HTTP API. Three ways to use it, all sharing one small client:
+
+| Component | What it is | Where |
+| --- | --- | --- |
+| **CLI** | A single-file Python client (`dss`), standard library only, Python ≥ 3.9. | [`dss.py`](dss.py) |
+| **Claude skill** | A self-contained Claude Code skill that drives the CLI. | [`skill/`](skill/) |
+| **MCP server** | An [MCP](https://modelcontextprotocol.io) server exposing the same endpoints as tools. | [`mcp-server/`](mcp-server/) |
+
+The CLI is the source of truth; the skill and MCP server bundle a copy of `dss.py` so each is self-contained. Run [`scripts/sync.sh`](scripts/sync.sh) after editing the canonical `dss.py` to refresh the copies.
+
+## Configure
+
+All three read the same environment variables:
+
+```bash
+export DSS_BASE_URL=https://dss.semtech.lv   # default
+export DSS_TIMEOUT=30                        # optional, seconds
+```
+
+The CLI and MCP tools also accept a per-call override (`--base-url` / `base_url`).
+
+## CLI
+
+```bash
+python3 dss.py --help
+```
+
+Install on your PATH (optional):
+
+```bash
+pipx install .          # provides the `dss` command (see pyproject.toml)
+# or, no packaging:
+ln -s "$(pwd)/dss.py" ~/.local/bin/dss && chmod +x dss.py
+```
+
+### Commands
+
+| Command | DSS endpoint |
+| --- | --- |
+| `ontologies [--variant ...] [--tag TAG]` | `GET /api/info` (variants `2`–`5`, `tags`; `--tag` with variant `3`) |
+| `schema-tags` | `GET /api/schema_tags` |
+| `public-ns` | `GET /api/public_ns` |
+| `namespaces <ont>` | `GET /api/ontologies/<ont>/ns` |
+| `classes <ont> [--limit N] [--filter STR]` | `POST .../getClasses` |
+| `properties <ont> [--limit N] [--filter REGEX] [--kind ...]` | `POST .../getProperties` |
+| `resolve-class <ont> <name>` | `POST .../resolveClassByName` |
+| `resolve-property <ont> <name>` | `POST .../resolvePropertyByName` |
+| `class-out-properties <ont> <class_id> [--limit N]` | `POST .../xx_getClassOutProperties` (by `c_id`) |
+| `class-in-properties <ont> <class_id> [--limit N]` | `POST .../xx_getClassInProperties` (by `c_id`) |
+| `class-pairs <ont> <p_list>` | `POST .../xx_getCPCInfoNew` — (source, target) class pairs for a property |
+| `call <ont> <fn> [--body JSON\|-] [--param k=v ...]` | `POST .../<fn>` (escape hatch) |
+
+The `class-*` commands key on numeric ids: get a class id from `resolve-class` and a property id from `resolve-property`.
+
+Output is indented JSON by default; pass `--compact` for single-line (pipe-friendly).
+
+```bash
+dss ontologies | jq '.[].db_schema_name'
+dss classes dbpedia --filter Person --limit 20
+dss resolve-property dbpedia dbo:birthPlace
+dss class-pairs war_sampo 116
+```
+
+## Claude skill
+
+`skill/` is a self-contained Claude Code skill. Install it user-level:
+
+```bash
+mkdir -p ~/.claude/skills
+cp -R skill ~/.claude/skills/dss
+```
+
+See [`docs/USAGE.md`](docs/USAGE.md) for setup, pointing it at a server, and example prompts.
+
+## MCP server
+
+See [`mcp-server/README.md`](mcp-server/README.md). In short:
+
+```bash
+cd mcp-server
+python3 -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+DSS_BASE_URL=https://dss.semtech.lv python3 dss_mcp.py
+```
+
+## Exit codes (CLI)
+
+- `0` — success, JSON on stdout
+- `2` — HTTP / transport / argument error, message on stderr
+- `130` — interrupted (Ctrl-C)
+
+## License
+
+MIT

dss_ai_tools-0.4.0/README.md

@@ -0,0 +1,96 @@
+# dss-ai-tools
+
+Tools for exploring a [Data Shape Server (DSS)](https://github.com/LUMII-Syslab/data-shape-server) knowledge-graph schema — classes, properties, their relations, and namespaces — over the DSS HTTP API. Three ways to use it, all sharing one small client:
+
+| Component | What it is | Where |
+| --- | --- | --- |
+| **CLI** | A single-file Python client (`dss`), standard library only, Python ≥ 3.9. | [`dss.py`](dss.py) |
+| **Claude skill** | A self-contained Claude Code skill that drives the CLI. | [`skill/`](skill/) |
+| **MCP server** | An [MCP](https://modelcontextprotocol.io) server exposing the same endpoints as tools. | [`mcp-server/`](mcp-server/) |
+
+The CLI is the source of truth; the skill and MCP server bundle a copy of `dss.py` so each is self-contained. Run [`scripts/sync.sh`](scripts/sync.sh) after editing the canonical `dss.py` to refresh the copies.
+
+## Configure
+
+All three read the same environment variables:
+
+```bash
+export DSS_BASE_URL=https://dss.semtech.lv   # default
+export DSS_TIMEOUT=30                        # optional, seconds
+```
+
+The CLI and MCP tools also accept a per-call override (`--base-url` / `base_url`).
+
+## CLI
+
+```bash
+python3 dss.py --help
+```
+
+Install on your PATH (optional):
+
+```bash
+pipx install .          # provides the `dss` command (see pyproject.toml)
+# or, no packaging:
+ln -s "$(pwd)/dss.py" ~/.local/bin/dss && chmod +x dss.py
+```
+
+### Commands
+
+| Command | DSS endpoint |
+| --- | --- |
+| `ontologies [--variant ...] [--tag TAG]` | `GET /api/info` (variants `2`–`5`, `tags`; `--tag` with variant `3`) |
+| `schema-tags` | `GET /api/schema_tags` |
+| `public-ns` | `GET /api/public_ns` |
+| `namespaces <ont>` | `GET /api/ontologies/<ont>/ns` |
+| `classes <ont> [--limit N] [--filter STR]` | `POST .../getClasses` |
+| `properties <ont> [--limit N] [--filter REGEX] [--kind ...]` | `POST .../getProperties` |
+| `resolve-class <ont> <name>` | `POST .../resolveClassByName` |
+| `resolve-property <ont> <name>` | `POST .../resolvePropertyByName` |
+| `class-out-properties <ont> <class_id> [--limit N]` | `POST .../xx_getClassOutProperties` (by `c_id`) |
+| `class-in-properties <ont> <class_id> [--limit N]` | `POST .../xx_getClassInProperties` (by `c_id`) |
+| `class-pairs <ont> <p_list>` | `POST .../xx_getCPCInfoNew` — (source, target) class pairs for a property |
+| `call <ont> <fn> [--body JSON\|-] [--param k=v ...]` | `POST .../<fn>` (escape hatch) |
+
+The `class-*` commands key on numeric ids: get a class id from `resolve-class` and a property id from `resolve-property`.
+
+Output is indented JSON by default; pass `--compact` for single-line (pipe-friendly).
+
+```bash
+dss ontologies | jq '.[].db_schema_name'
+dss classes dbpedia --filter Person --limit 20
+dss resolve-property dbpedia dbo:birthPlace
+dss class-pairs war_sampo 116
+```
+
+## Claude skill
+
+`skill/` is a self-contained Claude Code skill. Install it user-level:
+
+```bash
+mkdir -p ~/.claude/skills
+cp -R skill ~/.claude/skills/dss
+```
+
+See [`docs/USAGE.md`](docs/USAGE.md) for setup, pointing it at a server, and example prompts.
+
+## MCP server
+
+See [`mcp-server/README.md`](mcp-server/README.md). In short:
+
+```bash
+cd mcp-server
+python3 -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+DSS_BASE_URL=https://dss.semtech.lv python3 dss_mcp.py
+```
+
+## Exit codes (CLI)
+
+- `0` — success, JSON on stdout
+- `2` — HTTP / transport / argument error, message on stderr
+- `130` — interrupted (Ctrl-C)
+
+## License
+
+MIT

dss_ai_tools-0.4.0/docs/USAGE.md

@@ -0,0 +1,94 @@
+# Using the `dss` skill in Claude Code
+
+The `skill/` folder is a self-contained Claude Code skill. Once installed, Claude can use it to explore a Data Shape Server schema on your behalf. Run the commands below from the repository root.
+
+## 1. Install the skill
+
+Pick one of these.
+
+**User-level** — available in every project:
+
+```bash
+mkdir -p ~/.claude/skills
+cp -R skill ~/.claude/skills/dss
+```
+
+**Project-level** — only inside this repo:
+
+```bash
+mkdir -p .claude/skills
+ln -s "$(pwd)/skill" .claude/skills/dss
+```
+
+A symlink lets edits to `skill/` take effect immediately, without recopying.
+
+## 2. Point it at a DSS server
+
+The CLI reads `DSS_BASE_URL` from its environment. For the live instance:
+
+**Shell rc (easiest):** add to `~/.zshrc`, then open a new terminal.
+
+```bash
+export DSS_BASE_URL=http://viziquer.app:9005
+```
+
+**Project-scoped** — in `.claude/settings.json`:
+
+```json
+{ "env": { "DSS_BASE_URL": "http://viziquer.app:9005" } }
+```
+
+**One-off** — agent can prefix the command:
+
+```bash
+DSS_BASE_URL=http://viziquer.app:9005 python3 ~/.claude/skills/dss/dss.py ontologies
+```
+
+## 3. Sanity check
+
+```bash
+DSS_BASE_URL=http://viziquer.app:9005 \
+  python3 ~/.claude/skills/dss/dss.py ontologies | head
+```
+
+You should see a JSON array of schemas (DBpedia, Wikidata, Europeana, ...). If you instead see `Cannot reach …`, the URL or network is wrong; if you see `HTTP 404`, the path prefix is wrong (the server expects `/api/...`).
+
+## 4. Drive it from Claude Code
+
+Restart Claude Code so it re-scans skills, then ask things like:
+
+- "What ontologies are loaded in DSS?"
+- "List 20 classes in `dbpedia` whose name contains `Person`."
+- "Resolve `dbo:birthPlace` in the `dbpedia` schema."
+- "What namespaces does `wikidata` use?"
+- "Get object properties in `europeana` matching `creator`."
+
+Claude will pick up the skill from `SKILL.md` and run `python3 dss.py …` for you. Output is JSON, which Claude can then read and summarize.
+
+## 5. Calling the CLI directly
+
+You can also use it as a plain command-line tool. See `README.md` for the full command reference. The most useful ones:
+
+```bash
+dss ontologies                                  # list schemas
+dss namespaces dbpedia                          # prefixes
+dss classes dbpedia --filter Person --limit 20
+dss properties dbpedia --kind Object --filter birth
+dss resolve-class dbpedia dbo:Person
+dss resolve-property dbpedia dbo:birthPlace
+dss call dbpedia getTreeClasses --param limit=200 --param treeMode=Top   # escape hatch
+```
+
+To get a short `dss` command on your PATH:
+
+```bash
+ln -s ~/.claude/skills/dss/dss.py ~/.local/bin/dss
+chmod +x ~/.claude/skills/dss/dss.py
+```
+
+## Troubleshooting
+
+- **`Cannot reach …`** — server unreachable or DNS fails. Check `DSS_BASE_URL` and that the host is online.
+- **`HTTP 400 bad ontology name`** — ontology name has characters outside `[a-zA-Z0-9_-]`.
+- **`HTTP 404 unknown ontology`** — name doesn't match any `db_schema_name` from `dss ontologies`.
+- **Claude doesn't seem to know the skill exists** — make sure the folder is at `~/.claude/skills/dss/` (or `.claude/skills/dss/` in the project), contains `SKILL.md`, and that you restarted Claude Code after installing.