{"id":51989242,"url":"https://github.com/citiususc/shard","last_synced_at":"2026-07-30T22:01:15.191Z","repository":{"id":372729217,"uuid":"1267516314","full_name":"citiususc/shard","owner":"citiususc","description":"A WebApp to translate data constraints from natural language into SHACL using an ontology","archived":false,"fork":false,"pushed_at":"2026-07-23T01:35:53.000Z","size":1496,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-23T03:16:14.843Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://w3id.org/citius-kg/shard","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/citiususc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-12T15:57:32.000Z","updated_at":"2026-07-23T01:35:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/citiususc/shard","commit_stats":null,"previous_names":["citiususc/shard"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/citiususc/shard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/citiususc%2Fshard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/citiususc%2Fshard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/citiususc%2Fshard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/citiususc%2Fshard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/citiususc","download_url":"https://codeload.github.com/citiususc/shard/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/citiususc%2Fshard/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36093192,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-30T02:00:05.956Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-30T22:01:14.229Z","updated_at":"2026-07-30T22:01:15.181Z","avatar_url":"https://github.com/citiususc.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SHARD\n\n**Interactive Ontology-Grounded SHACL Authoring from Natural-Language Data Constraints**\n\nSHARD is an interactive workbench for generating reviewable SHACL shapes from\nan OWL/RDF ontology and natural-language data constraints. It keeps a human in\nthe loop: ontology grounding can be reviewed, generated Turtle can be edited,\nand every accepted shape can be validated and exported.\n\nRepository: \u003chttps://github.com/citiususc/shard\u003e\n\n## Authoring Workflows\n\n### Rule to Shape\n\nWrite one data constraint and resolve its ontology context into focus nodes,\nconstrained property paths and related terms. The proposed roles remain\neditable before SHARD generates one grounded SHACL document.\n\n### Batch to Shapes\n\nUpload a structured Markdown or HTML batch. SHARD parses each data constraint,\nresolves it through the `label -\u003e semantic -\u003e LLM` cascade, generates one\ndocument per resolved constraint and consolidates compatible property\nconstraints under their target-class NodeShapes. Progress is streamed per data\nconstraint. Unresolved constraints and discarded candidates remain visible for\nhuman review.\n\n## Validation and Baselines\n\nGenerated and imported shapes pass through:\n\n1. Turtle/RDF syntax validation.\n2. Generic SHACL for SHACL validation using the bundled `shacl-shacl.ttl`.\n3. Optional user-supplied domain validation profiles.\n4. Ontology-grounding checks for SHACL target, path and class IRIs.\n\nDomain profiles are always opt-in and are never inferred from the ontology.\n\nSHARD can send the current ontology to the Astrea REST API and use its response\nas structural generation evidence, as a rule-focused merge input, or both.\nMerging takes place before human review and is limited to the resolved focus\nnodes and constrained paths. Astrea output is normalized before generic SHACL\nfor SHACL validation, including canonical SHACL literals and lossless repair of\nmalformed RDF collections. The complete normalized document remains available as\nevidence, while merge consumes a separately validated conforming subset;\nfragments that cannot be repaired deterministically are quarantined and\nreported instead of being discarded silently. Export serializes the accepted shapes exactly as\nreviewed, removes only structurally identical anonymous constraints and checks\nthat no distinct constraint was lost.\n\nThe Astrea endpoint defaults to\n`https://astrea.linkeddata.es/api/shacl/document`. Set\n`SHARD_ASTREA_API_URL` to use another deployment.\n\n## Requirements\n\n- Python 3.10 or newer.\n- A remote inference endpoint, or enough local resources to run a compatible\n  Hugging Face model.\n- Node.js is not required at runtime; the frontend is served as static assets.\n\n## Installation\n\nClone the repository and install every production backend:\n\n```bash\ngit clone https://github.com/citiususc/shard.git\ncd shard\npython -m venv .venv\nsource .venv/bin/activate\npython -m pip install --upgrade pip\npython -m pip install -r requirements.txt\n```\n\n`requirements.txt` installs the project with its `local` extra. A remote-only\ninstallation can omit the large local-model dependencies:\n\n```bash\npython -m pip install .\n```\n\n## Running SHARD\n\nFrom a source checkout:\n\n```bash\npython run_demo.py\n```\n\nThe installed command is equivalent:\n\n```bash\nshard\n```\n\nOpen \u003chttp://127.0.0.1:8768/\u003e. The default `unified` layout serves the UI, REST\nAPI and SSE endpoint from the same process. Loopback listeners on ports\n`9100`-`9104` preserve API v1 compatibility and are not intended to be exposed.\n\nSHARD loads the first `.env` found in the current directory or project root.\nExisting process variables take precedence. Copy `.env.example` when a local\nconfiguration file is useful, never commit `.env`, and never place provider\ncredentials in frontend files.\n\n### Remote inference\n\nConfigure the remote endpoint in the process environment or `.env`:\n\n```bash\nDATABRICKS_BASE_URL=https://workspace.example/ai-gateway/mlflow/v1\nDATABRICKS_TOKEN=replace-with-a-secret\n```\n\nThe public deployment profile obtains these values from the server and never\nreturns them to the browser. Local API clients may supply request-scoped\nprovider credentials where the deployment permits it. Tokens are write-only,\nredacted from logs and excluded from sessions and provenance.\n\n### Local inference\n\nThe local profile permits Hugging Face models running on the same machine:\n\n```bash\nshard --deployment-profile local\n```\n\nNo model is selected or downloaded automatically. SHARD checks the local cache\nwhen the user chooses a model and asks for confirmation before downloading a\nmissing snapshot.\n\n## Public Deployment\n\nUse the public profile to disable server-side local-model execution:\n\n```bash\nshard --deployment-profile public --host 127.0.0.1 --port 8000\n```\n\nPlace this listener behind HTTPS and a reverse proxy. Only the unified listener\nshould be exposed. The frontend uses relative assets and the relative API base\n`api/v1/`, so a proxy can publish the application below `/shard/` while\nstripping that prefix before forwarding requests. See\n[Deployment Profiles](docs/deployment.md) for environment settings, proxy and\nSSE requirements.\n\n## Preloaded ePO Examples\n\nThe Import session menu exposes two complete examples based on the public\neProcurement Ontology dataset:\n\n- One data constraint for Rule to Shape.\n- A batch of ten representative data constraints for Batch to Shapes.\n\nThe sessions, extensible manifest and license attribution live in\n[`frontend/examples/`](frontend/examples/README.md). ePO is demonstration data;\nno ePO-specific behavior exists in the SHARD core.\n\n## Architecture\n\nSHARD exposes one versioned application API and five logical capability\nboundaries:\n\n1. Ontology Catalog and Retrieval Service.\n2. Data Constraint Grounding Service.\n3. Shape Generation Service.\n4. Shape Assurance and Baseline Integration Service.\n5. Authoring Workflow Service.\n\nThese are scientific and API responsibilities, not a requirement to deploy\nfive operating-system services. See [Architecture](docs/architecture.md).\n\n```text\nsrc/shard/\n  domain/          data-constraint and ontology concepts\n  application/     grounding, generation, validation and orchestration\n  inference/       remote and local inference adapters\n  baselines/       Astrea evidence and RDF-aware merge strategies\n  api/             OpenAPI, JSON, job and SSE transport adapters\n  deployment/      deployment policy and operational safeguards\n  observability/   request-scoped, secret-safe logging\n  resources/       generic prompts and validation resources\nfrontend/          static application and preloaded ePO sessions\ndocs/              architecture, API and deployment documentation\n```\n\n## REST API\n\nThe canonical API is available under `/api/v1`. Recommended complete workflows:\n\n- `POST /api/v1/workflows/rule-to-shape`\n- `POST /api/v1/workflows/batch-to-shapes`\n- `POST /api/v1/batches/generate` for incremental SSE progress\n\nComposable operations cover ontology parsing and search, target resolution,\nshape generation, validation, lossless export, Astrea and merge. Discovery and\ndocumentation are available at:\n\n- `GET /api/v1`\n- `GET /api/v1/openapi.json`\n- `GET /api/v1/docs` for Swagger UI\n- `GET /api/v1/redoc` for ReDoc\n- `GET /api/v1/capabilities`\n- `GET /api/v1/health`\n\nSHARD does not authenticate API clients itself. Provider credentials authorize\ninference providers, not the SHARD API. Deployments that require client access\ncontrol must enforce it at the reverse proxy or platform boundary.\n\nCanonical routes use typed snake_case payloads and secret-free provenance.\nUnversioned compatibility routes, the `BR2SHACL_*` environment aliases and\n`X-BR2SHACL-*` response headers remain available during API v1 for existing\nclients. New integrations should use `/api/v1`, `SHARD_*` and `X-SHARD-*`.\n\nSee [REST API](docs/api.md) for endpoint selection, schemas, jobs, SSE, errors\nand executable `curl` examples.\n\n## Citation and License\n\nThe software citation is provided in [`CITATION.cff`](CITATION.cff). SHARD is\nreleased under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcitiususc%2Fshard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcitiususc%2Fshard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcitiususc%2Fshard/lists"}