iolanta 2.1.4__py3-none-any.whl → 2.1.7__py3-none-any.whl

iolanta/mcp/prompts/rules.md

@@ -0,0 +1,83 @@
+# How to author Linked Data with Iolanta
+
+**R00.** Follow this YAML-LD authoring workflow:
+- Draft YAML-LD from user text
+- Use the Iolanta MCP `render_uri` tool with `as_format: labeled-triple-set` to validate and get feedback
+- Address the feedback, correct the YAML-LD document appropriately
+- **After each change to the YAML-LD file, re-run the validation to check for new feedback**
+
+**R01.** Acceptance Criteria:
+
+- The document fits the original statement the user wanted to express;
+- No negative feedback is received.
+
+**R02.** Use YAML-LD format, which is JSON-LD in YAML syntax, for writing Linked Data.
+
+**R03.** Always quote the @ character in YAML since it's reserved. Use `"@id":` instead of `@id:`.
+
+**R04.** Prefer YAML-LD Convenience Context which maps @-keywords to $-keywords that don't need quoting: `"@type"` → `$type`, `"@id"` → `$id`, `"@graph"` → `$graph`.
+
+**R05.** Use the dollar-convenience context with `@import` syntax instead of array syntax. This provides cleaner, more readable YAML-LD documents.
+
+Example:
+```yaml
+"@context":
+  "@import": "https://json-ld.org/contexts/dollar-convenience.jsonld"
+  
+  schema: "https://schema.org/"
+  wd: "https://www.wikidata.org/entity/"
+  
+  author:
+    "@id": "https://schema.org/author"
+    "@type": "@id"
+```
+
+Instead of:
+```yaml
+"@context":
+  - "https://json-ld.org/contexts/dollar-convenience.jsonld"
+  - schema: "https://schema.org/"
+  - wd: "https://www.wikidata.org/entity/"
+  - author:
+      "@id": "https://schema.org/author"
+      "@type": "@id"
+```
+
+**R06.** Reduce quoting when not required by YAML syntax rules.
+
+**R07.** Do not use mock URLs like `https://example.org`. Use resolvable URLs that preferably point to Linked Data.
+
+**R08.** Use URIs that convey meaning and are renderable with Linked Data visualization tools. Search for appropriate URIs from sources like DBPedia or Wikidata.
+
+**R09.** Use the Iolanta MCP `render_uri` tool with `as_format: mermaid` to generate Mermaid graph visualizations of Linked Data. If the user asks, you can save them to `.mmd` files for preview and documentation purposes.
+
+**R10.** For language tags, use YAML-LD syntax: `rdfs:label: { $value: "text", $language: "lang" }` instead of Turtle syntax `"text"@lang`.
+
+**R11.** Do not attach labels to external URIs that are expected to return Linked Data. Iolanta will fetch those URIs and render labels from the fetched data.
+
+**R12.** Use `"@type": "@id"` in the context to coerce properties to IRIs instead of using `$id` wrappers in the document body.
+
+**R13.** For software packages, use `schema:SoftwareApplication` as the main type rather than `codemeta:SoftwareSourceCode`.
+
+**R14.** Use Wikidata entities for programming languages (e.g., `https://www.wikidata.org/entity/Q28865` for Python) instead of string literals.
+
+**R15.** Use proper ORCID URIs for authors (e.g., `https://orcid.org/0009-0001-8740-4213`) and coerce them to IRIs in the context.
+
+**R16.** For tools that provide both library and CLI functionality, classify as `schema:Tool` with `schema:applicationSubCategory: Command-line tool`.
+
+**R17.** Use real, resolvable repository URLs (e.g., `https://github.com/iolanta-tech/python-yaml-ld`) instead of placeholder URLs.
+
+**R18.** Include comprehensive metadata: name, description, author, license, programming language, version, repository links, and application category.
+
+**R19.** Use standard vocabularies: schema.org, RDFS, RDF, DCTerms, FOAF, and CodeMeta when appropriate.
+
+**R20.** Validate Linked Data using the Iolanta MCP `render_uri` tool with `as_format: labeled-triple-set` to check for URL-as-literal issues and proper IRI handling.
+
+**R21.** Do not add `rdfs:label` to external URIs that are expected to return Linked Data. If a URI does not exist or cannot be resolved, do not mask this fact by adding labels. Instead, use a different, existing URI or document the issue with a comment.
+
+**R22.** Define URI coercion in the context using `"@type": "@id"` rather than using `$id` wrappers in the document body. This keeps the document body clean and readable while ensuring proper URI handling.
+
+**R23.** When defining local shortcuts for URIs in the context, use dashed-case (e.g., `appears-in`, `named-after`) instead of camelCase (e.g., `appearsIn`, `namedAfter`). This improves readability and follows common YAML conventions.
+
+**R24.** Do not rely upon `owl:sameAs` or `schema:sameAs` to express identity relationships. This necessitates OWL inference at the side of the reader, which is performance-taxing and tends to create conflicts. Instead, use direct URIs for entities without relying on sameAs statements for identity.
+

iolanta/mermaid/facet.py

@@ -122,6 +122,3 @@ class Mermaid(Facet[str]):
         direct_children = self.construct_mermaid_for_graph(self.this)
         subgraphs = self.construct_mermaid_subgraphs()
         return str(Diagram(children=[*direct_children, *subgraphs]))
-
-
-

iolanta/mermaid/mermaid.yamlld

@@ -1,42 +1,25 @@
 "@context":
   "@import": https://json-ld.org/contexts/dollar-convenience.jsonld
-  vann: https://purl.org/vocab/vann/
-  foaf: https://xmlns.com/foaf/0.1/
-  owl: https://www.w3.org/2002/07/owl#
   iolanta: https://iolanta.tech/
-  rdfs: "https://www.w3.org/2000/01/rdf-schema#"
-  rdf: https://www.w3.org/1999/02/22-rdf-syntax-ns#
-  dcterms: https://purl.org/dc/terms/
-  dcam: https://purl.org/dc/dcam/
-
-  iolanta:outputs:
-    "@type": "@id"
-
-  iolanta:when-no-facet-found:
-    "@type": "@id"
+  rdfs: http://www.w3.org/2000/01/rdf-schema#
 
   $: rdfs:label
   →:
     "@type": "@id"
     "@id": iolanta:outputs
 
-  ⊆:
-    "@type": "@id"
-    "@id": rdfs:subClassOf
-
-  ⪯:
-    "@type": "@id"
-    "@id": iolanta:is-preferred-over
-
-  ↦: iolanta:matches
-  iolanta:hasDefaultFacet:
-    "@type": "@id"
+  ↦:
+    "@id": iolanta:matches
+    "@type": iolanta:SPARQLText
 
 $id: pkg:pypi/iolanta#mermaid-graph
 $: Mermaid Graph
+
 →:
   $id: https://iolanta.tech/datatypes/mermaid
   $: Mermaid
+  $type: iolanta:OutputDatatype
+
 ↦:
   - ASK WHERE { GRAPH $this { ?s ?p ?o } }
   - ASK WHERE { $this iolanta:has-sub-graph ?subgraph }

iolanta/mermaid/models.py

@@ -60,7 +60,9 @@ class MermaidLiteral(Documented, BaseModel, arbitrary_types_allowed=True, frozen
 
     @property
     def id(self) -> str:
-        value_hash = hashlib.md5(str(self.literal.value).encode()).hexdigest()
+        # Use the lexical form of the literal, not rdflib's .value (which may be empty for typed literals),
+        # to ensure different texts get distinct node IDs in Mermaid.
+        value_hash = hashlib.md5(str(self.literal).encode()).hexdigest()
         return f'Literal-{value_hash}'
 
 
@@ -142,7 +144,7 @@ class Diagram(Documented, BaseModel):
     """
     graph {self.direction}
     {self.formatted_body}
-      classDef predicate fill:none,stroke:none,stroke-width:0px;
+      classDef predicate fill:transparent,stroke:transparent,stroke-width:0px;
     """
 
     children: list[MermaidScalar | MermaidSubgraph]

iolanta/mermaid/sparql/ask-has-triples.sparql

@@ -0,0 +1,3 @@
+ASK WHERE {
+  GRAPH $this { ?s ?p ?o }
+}

iolanta/models.py

@@ -83,9 +83,6 @@ class TripleTemplate(NamedTuple):
 
 
 def _normalize_term(term: Node):
-    if isinstance(term, URIRef) and term.startswith('http://'):
-        return URIRef(re.sub('^http', 'https', term))
-
     return term
 
 

iolanta/namespaces.py

@@ -20,11 +20,11 @@ class OWL(rdflib.OWL):
 
 
 class RDFS(rdflib.RDFS):
-    _NS = rdflib.Namespace('https://www.w3.org/2000/01/rdf-schema#')
+    _NS = rdflib.Namespace('http://www.w3.org/2000/01/rdf-schema#')
 
 
 class RDF(rdflib.RDF):
-    _NS = rdflib.Namespace('https://www.w3.org/1999/02/22-rdf-syntax-ns#')
+    _NS = rdflib.Namespace('http://www.w3.org/1999/02/22-rdf-syntax-ns#')
 
 
 class DCTERMS(rdflib.DCTERMS):

iolanta/parse_quads.py

@@ -13,8 +13,8 @@ from iolanta.models import Quad
 from iolanta.namespaces import IOLANTA, META
 
 NORMALIZE_TERMS_MAP = MappingProxyType({
-    URIRef(_url := 'https://www.w3.org/2002/07/owl'): URIRef(f'{_url}#'),
-    URIRef(_url := 'https://www.w3.org/2000/01/rdf-schema'): URIRef(f'{_url}#'),
+    URIRef(_url := 'http://www.w3.org/2002/07/owl'): URIRef(f'{_url}#'),
+    URIRef(_url := 'http://www.w3.org/2000/01/rdf-schema'): URIRef(f'{_url}#'),
 })
 
 

iolanta/sparqlspace/inference/wikidata-prop-label.sparql

@@ -0,0 +1,10 @@
+PREFIX wikibase: <http://wikiba.se/ontology#>
+
+CONSTRUCT {
+  ?thing rdfs:label ?label .
+}
+WHERE {
+  ?entity
+    (wikibase:claim | wikibase:qualifier | wikibase:statementProperty | wikibase:statementValueNormalized) ?thing ;
+    rdfs:label ?label .
+}

iolanta/sparqlspace/inference/wikidata-statement-label.sparql

@@ -0,0 +1,27 @@
+PREFIX wikibase: <http://wikiba.se/ontology#>
+PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
+PREFIX prov: <http://www.w3.org/ns/prov#>
+
+CONSTRUCT {
+  ?statement rdfs:label ?label .
+}
+WHERE {
+  ?statement a wikibase:Statement .
+  
+  # Find predicates from statement to values (excluding metadata predicates)
+  ?statement ?statementProp ?value .
+  
+  FILTER(?statementProp != wikibase:rank)
+  FILTER(?statementProp != rdf:type)
+  FILTER(?statementProp != prov:wasDerivedFrom)
+  FILTER(?statementProp != iolanta:last-loaded-time)
+  
+  # Handle entity values: get their label
+  {
+    ?value rdfs:label ?label .
+  } UNION {
+    # Handle literal values: use the literal directly
+    ?statement ?statementProp ?label .
+    FILTER(isLiteral(?label))
+  }
+}

iolanta/sparqlspace/processor.py

@@ -35,6 +35,7 @@ from iolanta.namespaces import (  # noqa: WPS235
     DCTERMS,
     FOAF,
     IOLANTA,
+    LOCAL,
     META,
     OWL,
     PROV,
@@ -46,6 +47,8 @@ from iolanta.parse_quads import NORMALIZE_TERMS_MAP, parse_quads
 
 REASONING_ENABLED = True
 OWL_REASONING_ENABLED = False
+
+INFERENCE_DIR = Path(__file__).parent / 'inference'
 INDICES = [
     URIRef('https://iolanta.tech/visualizations/index.yaml'),
 ]
@@ -112,7 +115,7 @@ def _extract_from_mapping(  # noqa: WPS213
     algebra: Mapping[str, Any],
 ) -> Iterable[URIRef | Variable]:
     match algebra.name:
-        case 'SelectQuery' | 'AskQuery' | 'Project' | 'Distinct':
+        case 'SelectQuery' | 'AskQuery' | 'Project' | 'Distinct' | 'Slice':
             yield from extract_mentioned_urls(algebra['p'])
 
         case 'BGP':
@@ -159,7 +162,7 @@ def _extract_from_mapping(  # noqa: WPS213
 
         case unknown_name:
             formatted_keys = ', '.join(algebra.keys())
-            loguru.logger.error(
+            loguru.logger.info(
                 'Unknown SPARQL expression '
                 f'{unknown_name}({formatted_keys}): {algebra}',
             )
@@ -203,9 +206,6 @@ def normalize_term(term: Node) -> Node:
       * A dirty hack;
       * Based on hard code.
     """
-    if isinstance(term, URIRef) and term.startswith('http://'):
-        term = URIRef(re.sub('^http', 'https', term))
-
     return NORMALIZE_TERMS_MAP.get(term, term)
 
 
@@ -263,6 +263,12 @@ def _extract_nanopublication_uris(
     match algebra.name:
         case 'SelectQuery' | 'AskQuery' | 'Project' | 'Distinct' | 'Graph':
             yield from _extract_nanopublication_uris(algebra['p'])
+        case 'ConstructQuery':
+            # CONSTRUCT queries don't have nanopublication URIs in bindings
+            return
+
+        case 'Slice':
+            yield from _extract_nanopublication_uris(algebra['p'])
 
         case 'BGP':
             for retractor, retracts, retractee in algebra['triples']:
@@ -404,64 +410,6 @@ class GlobalSPARQLProcessor(Processor):  # noqa: WPS338, WPS214
         self.graph.last_not_inferred_source = None
         self.graph._indices_loaded = False
 
-    def _infer_with_sparql(self):
-        """
-        Infer triples with SPARQL rules.
-
-        FIXME:
-          * Code these rules into SHACL or some other RDF based syntax;
-          * Make them available at iolanta.tech/visualizations/ and indexed.
-        """
-        inference = Path(__file__).parent / 'inference'
-
-        file_names = {
-            'wikibase-claim.sparql': URIRef('local:inference-wikibase-claim'),
-            'wikibase-statement-property.sparql': URIRef(
-                'local:inference-statement-property',
-            ),
-        }
-
-        for file_name, graph_name in file_names.items():
-            start_time = time.time()
-            self.graph.update(
-                update_object=(inference / file_name).read_text(),
-            )
-            triple_count = len(self.graph.get_context(graph_name))
-            duration = datetime.timedelta(seconds=time.time() - start_time)
-            self.logger.info(
-                f'{file_name}: {triple_count} triple(s), '
-                f'inferred at {duration}',
-            )
-
-    def maybe_apply_inference(self):
-        """Apply global OWL RL inference if necessary."""
-        if not REASONING_ENABLED:
-            return
-
-        if self.graph.last_not_inferred_source is None:
-            return
-
-        with self.inference_lock:
-            self._infer_with_sparql()
-            self._infer_with_owl_rl()
-            self.logger.info('Inference @ cyberspace: complete.')
-
-            self.graph.last_not_inferred_source = None
-
-    def _infer_with_owl_rl(self):
-        if not OWL_REASONING_ENABLED:
-            return
-
-        reasoner = reasonable.PyReasoner()
-        reasoner.from_graph(self.graph)
-        inferred_triples = reasoner.reason()
-        inference_graph_name = BNode('_:inference')
-        inferred_quads = [
-            (*triple, inference_graph_name)
-            for triple in inferred_triples
-        ]
-        self.graph.addN(inferred_quads)
-
     def _maybe_load_indices(self):
         if not self.graph._indices_loaded:
             for index in INDICES:
@@ -486,7 +434,7 @@ class GlobalSPARQLProcessor(Processor):  # noqa: WPS338, WPS214
 
         initBindings = initBindings or {}
         initNs = initNs or {}
-
+        
         if isinstance(strOrQuery, Query):
             query = strOrQuery
 
@@ -494,12 +442,14 @@ class GlobalSPARQLProcessor(Processor):  # noqa: WPS338, WPS214
             parse_tree = parseQuery(strOrQuery)
             query = translateQuery(parse_tree, base, initNs)
 
-        self.load_retracting_nanopublications_by_query(
-            query=query,
-            bindings=initBindings,
-            base=base,
-            namespaces=initNs,
-        )
+        # Only extract nanopublications from SELECT/ASK queries, not CONSTRUCT
+        if query.algebra.name != 'ConstructQuery':
+            self.load_retracting_nanopublications_by_query(
+                query=query,
+                bindings=initBindings,
+                base=base,
+                namespaces=initNs,
+            )
 
         query, urls = extract_mentioned_urls_from_query(
             query=query,
@@ -508,15 +458,24 @@ class GlobalSPARQLProcessor(Processor):  # noqa: WPS338, WPS214
             namespaces=initNs,
         )
 
+        # Filter out inference graph names (they're not URLs to load)
+        urls = {url for url in urls if not str(url).startswith('inference:')}
+
         for url in urls:
             try:
                 self.load(url)
             except Exception as err:
-                self.logger.error(f'Failed to load {url}: {err}', url, err)
+                self.logger.exception(f'Failed to load {url}: {err}', url, err)
 
-        NanopubQueryPlugin(graph=self.graph)(query, bindings=initBindings)
+        # Run inference if there's new data since last inference run
+        # (after URLs are loaded so inference can use the loaded data)
+        if self.graph.last_not_inferred_source is not None:
+            self.logger.debug(f'Running inference, last_not_inferred_source: {self.graph.last_not_inferred_source}')
+            self._run_inference()
+        else:
+            self.logger.debug('Skipping inference, last_not_inferred_source is None')
 
-        self.maybe_apply_inference()
+        NanopubQueryPlugin(graph=self.graph)(query, bindings=initBindings)
 
         is_anything_loaded = True
         while is_anything_loaded:
@@ -531,6 +490,7 @@ class GlobalSPARQLProcessor(Processor):  # noqa: WPS338, WPS214
                 return query_result
 
             for row in bindings:
+                break
                 for _, maybe_iri in row.items():
                     if (
                         isinstance(maybe_iri, URIRef)
@@ -566,12 +526,10 @@ class GlobalSPARQLProcessor(Processor):  # noqa: WPS338, WPS214
 
     def _follow_is_visualized_with_links(self, uri: URIRef):
         """Follow `dcterms:isReferencedBy` links."""
-        self.logger.info(f'Following links for {uri}…')
         triples = self.graph.triples((uri, DCTERMS.isReferencedBy, None))
         for _, _, visualization in triples:
             if isinstance(visualization, URIRef):
                 self.load(visualization)
-        self.logger.info('Links followed.')
 
     def load(   # noqa: C901, WPS210, WPS212, WPS213, WPS231
         self,
@@ -611,8 +569,6 @@ class GlobalSPARQLProcessor(Processor):  # noqa: WPS338, WPS214
         source_uri = normalize_term(source)
         if self._is_loaded(source_uri):
             return Skipped()
-        else:
-            self.logger.info(f'{source_uri} is not loaded yet')
 
         # FIXME This is definitely inefficient. However, python-yaml-ld caches
         #   the document, so the performance overhead is not super high.
@@ -718,8 +674,9 @@ class GlobalSPARQLProcessor(Processor):  # noqa: WPS338, WPS214
             for quad in quads
         })
         self.logger.info(
-            f'{source} | loaded successfully into graphs: {into_graphs}',
+            f'{source} | loaded {len(quads)} triples into graphs: {into_graphs}',
         )
+
         return Loaded()
 
     def resolve_term(self, term: Node, bindings: dict[str, Node]):
@@ -732,6 +689,51 @@ class GlobalSPARQLProcessor(Processor):  # noqa: WPS338, WPS214
 
         return term
 
+    def _run_inference(self):  # noqa: WPS231
+        """
+        Run inference queries from the inference directory.
+
+        For each SPARQL file in the inference directory:
+        1. Truncate the named graph `local:inference-{filename}`
+        2. Execute the CONSTRUCT query
+        3. Insert the resulting triples into that graph
+        """
+        with self.inference_lock:
+            for inference_file in INFERENCE_DIR.glob('*.sparql'):
+                filename = inference_file.stem  # filename without .sparql extension
+                inference_graph = URIRef(f'inference:{filename}')
+
+                # Truncate the inference graph
+                context = self.graph.get_context(inference_graph)
+                context.remove((None, None, None))
+
+                # Read and execute the CONSTRUCT query
+                query_text = inference_file.read_text()
+                result = self.graph.query(query_text)
+
+                # CONSTRUCT queries return a SPARQLResult with a graph attribute
+                result_graph = result.get('graph') if isinstance(result, dict) else result.graph
+                self.logger.debug(f'Inference {filename}: result_graph is {result_graph}, type: {type(result_graph)}')
+                if result_graph is not None:
+                    inferred_quads = [
+                        (s, p, o, inference_graph)
+                        for s, p, o in result_graph
+                    ]
+                    self.logger.debug(f'Inference {filename}: generated {len(inferred_quads)} quads')
+
+                    if inferred_quads:
+                        self.graph.addN(inferred_quads)
+                        self.logger.info(
+                            'Inference {filename}: added {count} triples',
+                            filename=filename,
+                            count=len(inferred_quads),
+                        )
+                else:
+                    self.logger.debug(f'Inference {filename}: result_graph is None')
+        
+        # Clear the flag after running inference
+        self.graph.last_not_inferred_source = None
+
     def load_retracting_nanopublications_by_query(    # noqa: WPS231
         self,
         query: Query,

{iolanta-2.1.4.dist-info → iolanta-2.1.7.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: iolanta
-Version: 2.1.4
+Version: 2.1.7
 Summary: Semantic Web browser
 License: MIT
 Author: Anatoly Scherbakov
@@ -10,6 +10,7 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Provides-Extra: all
 Requires-Dist: boltons (>=24.0.0)
 Requires-Dist: classes (>=0.4.0)
@@ -17,9 +18,11 @@ Requires-Dist: deepmerge (>=0.1.1)
 Requires-Dist: diskcache (>=5.6.3)
 Requires-Dist: documented (>=0.1.1)
 Requires-Dist: dominate (>=2.6.0)
+Requires-Dist: fastmcp (>=2.12.4,<3.0.0)
 Requires-Dist: funcy (>=2.0)
 Requires-Dist: loguru (>=0.7.3)
 Requires-Dist: more-itertools (>=9.0.0)
+Requires-Dist: nanopub (>=2.1.0,<3.0.0)
 Requires-Dist: owlrl (>=6.0.2)
 Requires-Dist: oxrdflib (>=0.4.0)
 Requires-Dist: packageurl-python (>=0.17.5)
@@ -31,7 +34,7 @@ Requires-Dist: rich (>=13.3.1)
 Requires-Dist: textual (>=0.83.0)
 Requires-Dist: typer (>=0.9.0)
 Requires-Dist: watchfiles (>=1.0.4)
-Requires-Dist: yaml-ld (>=1.1.12)
+Requires-Dist: yaml-ld (>=1.1.15)
 Requires-Dist: yarl (>=1.9.4)
 Description-Content-Type: text/markdown