Skip to content

Graph-Native Infrastructure for Context and Accountable AI Systems

docs: add PR description and update CHANGELOG for #355

KaifAhmad134df1964b968
diff --git a/CHANGELOG.md b/CHANGELOG.md
index afaf9577..4b8c5ba3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+- **TTL Export Alias Fix** (PR #355 by @ZohaibHassan16):
+ - Added `_format_aliases` map in `RDFExporter` so `format="ttl"`, `"nt"`, `"xml"`, `"rdf"`, and `"json-ld"` resolve to their canonical counterparts without breaking existing callers
+ - Alias resolution applied at the top of `export_to_rdf()` before format validation — zero public API changes
+ - Added working TTL export cell to `cookbook/introduction/15_Export.ipynb` (Step 3: RDF Export)
+ - Added `tests/export/test_rdf_exporter.py` with 8 tests covering all aliases, canonical formats, error handling, and file export
+
- **Incremental/Delta Processing Feature** (PR #349 by @ZohaibHassan16, reviewed and fixed by @KaifAhmad1):
- Native delta computation between graph snapshots using SPARQL queries
- Delta-aware pipeline execution with `delta_mode` configuration for processing only changed data
diff --git a/pr_description.md b/pr_description.md
new file mode 100644
index 00000000..bdc64187
--- /dev/null
+++ b/pr_description.md
@@ -0,0 +1,77 @@
+## Description
+
+Fixes two gaps that made Turtle/TTL export inaccessible:
+
+1. `format="ttl"` raised a `ValidationError` because `"ttl"` was not accepted as an alias for `"turtle"` in `RDFExporter`, even though it is the standard file extension.
+2. `RDFExporter` was never introduced in `cookbook/introduction/15_Export.ipynb`, so users following the default learning path had no way to discover TTL export.
+
+## Type of Change
+
+- [x] Bug fix (non-breaking change which fixes an issue)
+- [x] Documentation update
+
+## Related Issues
+
+Closes #355
+
+## Changes Made
+
+- `semantica/export/rdf_exporter.py`: Added `_format_aliases` dict in `RDFExporter.__init__()` mapping common shorthands to canonical format names (`ttl→turtle`, `nt→ntriples`, `xml→rdfxml`, `rdf→rdfxml`, `json-ld→jsonld`). Added one-line alias resolution at the top of `export_to_rdf()` before format validation — all existing callers using canonical names are unaffected.
+- `cookbook/introduction/15_Export.ipynb`: Added a code cell in Step 3 (RDF Export) demonstrating `format="ttl"` and `validate_rdf()`.
+- `tests/export/test_rdf_exporter.py`: New test file with 8 tests covering alias parity, canonical formats, unsupported format error, and file export with `format="ttl"`.
+
+## Testing
+
+- [x] Tested locally
+- [x] Added tests for new functionality
+- [x] Package builds successfully (`python -m build`)
+
+### Test Commands
+
+```bash
+# Run new RDF exporter tests
+pytest tests/export/test_rdf_exporter.py -v
+
+# Verify the original bug is fixed
+python -c "
+from semantica.export import RDFExporter
+exporter = RDFExporter()
+rdf_data = {
+ 'entities': [
+ {'id': 'e1', 'text': 'Apple Inc.', 'type': 'ORG', 'confidence': 0.95},
+ {'id': 'e2', 'text': 'Steve Jobs', 'type': 'PERSON', 'confidence': 0.97},
+ ],
+ 'relationships': [
+ {'source_id': 'e2', 'target_id': 'e1', 'type': 'founded_by', 'confidence': 0.91},
+ ],
+}
+exporter.export(rdf_data, 'output.ttl', format='ttl')
+print('format=ttl works correctly')
+"
+
+# Full test suite
+pytest tests/
+```
+
+## Documentation
+
+- [x] Updated relevant documentation
+- [x] Added code examples if applicable
+- [x] Updated cookbook if adding new examples
+
+## Breaking Changes
+
+**Breaking Changes**: No
+
+All existing callers using canonical format names (`"turtle"`, `"rdfxml"`, `"jsonld"`, `"ntriples"`, `"n3"`) are completely unaffected. The alias map is purely additive.
+
+## Checklist
+
+- [x] My code follows the project's style guidelines
+- [x] I have performed a self-review of my code
+- [x] My changes generate no new warnings
+- [x] Package builds successfully
+
+## Additional Notes
+
+The alias resolution uses `.lower()` on the input before lookup, so `"TTL"`, `"Ttl"`, etc. also work. No public API signatures were changed.