Merge pull request #353 from iolanta-tech/author-ld-with-llm-prototype

author ld with llm prototype

Author: anatoly-scherbakov

.flake8

@@ -0,0 +1,5 @@
+[flake8]
+per-file-ignores =
+    iolanta/sparqlspace/processor.py:WPS201,WPS202,WPS402
+    jeeves/__init__.py:WPS412,WPS400
+    tests/test_integration.py:WPS202

docs/howto/nanopublish-with-llm/AGENTS.md

@@ -0,0 +1,165 @@
+# Writing Linked Data
+
+You are a helpful assistant and you are going to help the user to convert their plaintext statement(s) into Linked Data.
+
+## Format
+
+**R01.** Format of choice is Markdown-LD, where:
+
+- YAML frontmatter is in YAML-LD format,
+- And the remainder of the document describes in plain text whatever the frontmatter expresses as Linked Data.
+
+**R02.** The content of the frontmatter and the plaintext must match. To achieve that,
+
+- Propose changes to the frontmatter,
+- And if the statements in the text are hard to convert to Linked Data, propose how to adjust them.
+
+## Workflow
+
+**R03.** Follow this YAML-LD authoring workflow:
+
+- Draft YAML-LD from user text
+- Use the `iolanta` CLI command with `--as 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**
+
+**R04.** After every change to the frontmatter of the Markdown file we are editing, execute:
+
+```shell
+iolanta $markdown_document_path --as labeled-triple-set
+```
+
+…which will output a JSON document listing the triples to which the document compiles. They will be labeled and accompanied with linter feedback messages. Satisfy them.
+
+**R05.** Acceptance Criteria:
+
+- The document fits the original statement the user wanted to express;
+- No negative feedback is received.
+
+## YAML-LD Syntax
+
+**R06.** Use YAML-LD format, which is JSON-LD in YAML syntax, for writing Linked Data.
+
+**R07.** Always quote the @ character in YAML since it's reserved. Use `"@id":` instead of `@id:`.
+
+**R08.** Prefer YAML-LD Convenience Context which maps @-keywords to $-keywords that don't need quoting: `"@type"` → `$type`, `"@id"` → `$id`, `"@graph"` → `$graph`.
+
+**R09.** 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"
+```
+
+**R10.** Reduce quoting when not required by YAML syntax rules. Do not quote simple strings without special characters. For example, use `rdfs:label: Rhysling` instead of `rdfs:label: "Rhysling"`. Quotes are only needed when the value contains special YAML characters (like `:`, `@`, `&`, `*`, `|`, `>`, `#`, etc.) or when the value starts with characters that YAML interprets specially.
+
+**R11.** For language tags, use YAML-LD syntax: `rdfs:label: { $value: "text", $language: "lang" }` instead of Turtle syntax `"text"@lang`.
+
+**R12.** Use `"@type": "@id"` in the context to coerce properties to IRIs instead of using `$id` wrappers in the document body. This keeps the document body clean and readable while ensuring proper URI handling.
+
+**R13.** 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.
+
+## URIs and Identifiers
+
+**R15.** Use resolvable URIs that preferably point to Linked Data. Do not use mock URLs like `https://example.org`. Search for appropriate URIs from sources like DBPedia or Wikidata that convey meaning and are renderable with Linked Data visualization tools.
+
+**R17.** When running
+
+```
+iolanta $document --as labeled-triple-set
+```
+
+**DO NOT postprocess the output using any utilities** (no `grep`, `head`, `tail`, `python3 -c`, `json.tool`, `jq`, or any other filtering/parsing tools). Read the raw output directly. You are very often obscuring the output or losing part of it when you postprocess. This is not a good place to optimize for context size. The full output must be read and analyzed as-is.
+
+**R18.** Do not assign labels to URLs which are not minted in this document. A URL is "minted" by a document when the document itself makes that URL resolvable (i.e., the document is hosted at that URL). For example, if a document is hosted at `example.org/johndoe`, then `example.org/johndoe` is minted by that document and can have labels assigned to it. External URIs (like Wikidata or DBpedia URLs) that are not hosted by this document should not have labels assigned to them. 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.
+
+**R19.** 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.
+
+## Software and Code Metadata
+
+**R20.** For software packages, use `schema:SoftwareApplication` as the main type rather than `codemeta:SoftwareSourceCode`.
+
+**R21.** Use Wikidata entities for programming languages (e.g., `https://www.wikidata.org/entity/Q28865` for Python) instead of string literals.
+
+**R22.** Use proper ORCID URIs for authors (e.g., `https://orcid.org/0009-0001-8740-4213`) and coerce them to IRIs in the context.
+
+**R23.** For tools that provide both library and CLI functionality, classify as `schema:Tool` with `schema:applicationSubCategory: Command-line tool`.
+
+**R24.** Use real, resolvable repository URLs (e.g., `https://github.com/iolanta-tech/python-yaml-ld`) instead of placeholder URLs.
+
+**R25.** Include comprehensive metadata: name, description, author, license, programming language, version, repository links, and application category.
+
+## Vocabularies
+
+**R26.** Use standard vocabularies: schema.org, RDFS, RDF, DCTerms, FOAF, and CodeMeta when appropriate.
+
+## Validation and Visualization
+
+**R27.** Do not use `schema:additionalType`, use `rdf:type` instead.
+
+**R28.** Use the `iolanta` CLI command with `--as 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.
+
+## Nanopublications
+
+Nanopublications are a special type of Linked Data that contain structured knowledge statements with three main components:
+
+1. **Assertion** - The core knowledge claim or statement
+2. **Provenance** - Information about how the assertion was derived (sources, methods, contributors)
+3. **Publication Info** - Metadata about the nanopublication itself (author, creation date, etc.)
+
+Nanopublications are cryptographically signed and published in the decentralized **Nanopublication Registry**, making them:
+- Irrevocably attributed to the author
+- Protected from tampering
+- Referenceable by unique IDs
+- Machine readable and reusable
+- Decentralized and persistent
+
+**NP01.** Nanopublication assertion graphs must also satisfy all the general rules for Linked Data authoring and workflow (R01-R28).
+
+**NP02.** We focus only on writing the **assertion graph** of the nanopublication.
+
+**NP03.** The assertion should express a single, clear knowledge claim that can stand alone.
+
+**NP04.** Use proper Linked Data vocabularies and resolvable URIs for all entities and relationships. Use canonical URIs from established knowledge bases (DBpedia, Wikidata, etc.) and standard vocabularies and well-established ontologies.
+
+**NP05.** After the assertion graph is ready, follow this workflow:
+
+```bash
+# Expand the YAML-LD to JSON-LD
+pyld expand assertion.yamlld > expanded.jsonld
+
+# Create nanopublication from the assertion
+np create from-assertion expanded.jsonld > nanopublication.trig
+
+# Publish the nanopublication (when ready)
+np publish nanopublication.trig
+```
+
+**NP06.** The `pyld expand` command converts YAML-LD to expanded JSON-LD format.
+
+**NP07.** The `np create from-assertion` command automatically generates the provenance and publication info components.
+
+**NP08.** The `np publish` command cryptographically signs and publishes the nanopublication to the registry.
+
+**NP09.** Use the `iolanta` CLI command to validate the assertion before proceeding with the workflow. Save Mermaid visualizations of the assertion for documentation purposes.
+
+**NP10.** Keep assertions focused on a single, verifiable claim. Include sufficient context and metadata to make the assertion meaningful and ensure it can be understood independently of external context.