# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [0.4.2] - 2026-03-25

### Changed
- **Removed `anzo-api-wrapper` dependency**: Inlined a minimal `AnzoRestClient` in `utils/rest_api_utils.py` using only Python stdlib (`urllib`), eliminating the external `anzo-api-wrapper` package and its pinned `requests==2.31.0` that caused dependency conflicts with `instructor`
- All 10 graphmart tools continue to work unchanged via the same `get_rest_api_client()` interface

### Added
- **`AnzoRestClient` class** in `rest_api_utils.py` — self-contained REST client implementing all 10 methods used by graphmart tools (layer CRUD, step CRUD, graphmart layer operations)
- **`inspect.sh`** — convenience script to launch MCP Inspector for local testing

### Removed
- `anzo-api-wrapper>=0.0.3` from dependencies — no longer needed

## [0.4.0] - 2026-03-21

### Changed
- **REST API migration for graphmart tools**: Migrated 11 graphmart tools from SPARQL `update_journal()` / `query_journal()` to the `anzo-api-wrapper` REST API, eliminating direct journal manipulation for all graphmart operations
  - **Write tools (8)**: `create_transformation_layer`, `update_transformation_layer`, `delete_transformation_layer`, `add_transformation_step`, `add_direct_load_step`, `update_transformation_step`, `update_direct_load_step`, `delete_transformation_step`
  - **Read tools (2)**: `list_transformation_layers`, `list_transformation_steps` — replaced SPARQL SELECTs with `retrieve_graphmart_layers()` and `retrieve_layer_steps()`
  - **Delegate (1)**: `add_select_step` — inherits REST migration via `add_transformation_step`

### Added
- **`get_rest_api_client()` utility** in `agent_utils.py` — cached `AnzoApi` instance created from `ANZO_SERVER`, `ANZO_PORT`, `ANZO_USERNAME`, `ANZO_PASSWORD` environment variables
- **`anzo-api-wrapper>=0.0.3` dependency** — REST API wrapper for graphmart, layer, step, model, and dataset operations

### Removed
- UUID generation and SPARQL INSERT DATA construction from all 8 graphmart write tools
- Manual ordered-item index calculation — REST API handles ordering automatically
- Per-step type SPARQL queries in `list_transformation_steps` — step type now comes directly from API response

### Security
- No credentials stored in code — REST client reads exclusively from environment variables

## [0.3.4] - 2026-03-21

### Added
- **SPARQL syntax pre-validation**: New `validate_sparql_syntax()` utility (`utils/sparql_syntax.py`) checks every query before it is sent to the server, catching malformed SPARQL instantly without a server round-trip
  - Level 1: fast structural checks — balanced braces/parentheses, recognised SPARQL keyword, SELECT requires WHERE
  - Level 2: full grammar parse via rdflib's SPARQL parser (query and update forms)
- **Three integration points** ensure all code paths are covered:
  - `SPARQLQueryEngine._validate_query_syntax()` — catches bad LLM-generated queries before execution, feeding clear syntax errors into the retry loop
  - `SPARQLQueryEngine.execute_sparql_query()` — pre-flight check on every query, returns immediate `QueryResult(success=False)` with the syntax error
  - `SPARQLAgent.query_sparql_direct()` — validates user-supplied raw SPARQL before sending to Graph Studio

### Changed
- Syntax errors in the NL→SPARQL retry loop now trigger faster — the LLM receives a precise "SPARQL syntax error" message instead of a vague server exception, improving fix quality on subsequent attempts

## [0.3.3] - 2026-03-16

### Changed
- **Clarified API_KEY documentation**: Explicitly explained distinction between VS Code Copilot mode (no API_KEY needed - Copilot generates SPARQL) vs standalone mode with Claude Desktop (API_KEY enables server-side NL→SPARQL)

## [0.3.2] - 2026-03-16

### Changed
- **Updated PyPI Documentation**: README now clearly highlights that API_KEY is optional for basic operations
- Added `--setup-vscode` flag documentation to Quick Start
- Enhanced installation instructions with automated setup option
- Clarified which features require API_KEY vs work without it

## [0.3.1] - 2026-03-16

### Fixed
- **Critical: `execute_sparql_query` fails without API_KEY** - Fixed `'NoneType' object has no attribute 'execute_sparql_query'` error. Query engine now initializes even without OpenAI client, enabling basic SPARQL execution without API_KEY.

### Changed
- Help text clarifies API_KEY is only needed for NL→SPARQL features, not basic operations

## [0.3.0] - 2026-03-16

### Fixed
- **Critical: Broken imports** - Fixed `from ontology_discovery` → `from .ontology_discovery` in `sparql_agent_core.py` (caused `ModuleNotFoundError` at runtime)
- **Critical: `import ags_sparql_agent`** - Removed reference to non-existent module in `test_system_connection.py`
- **Hardcoded bad endpoint** - Azure OpenAI endpoint was set to `"badendpoint"`, now reads from `AZURE_OPENAI_ENDPOINT` env var
- Removed stale `sys.path` hacks from tool modules

### Changed
- **API_KEY is now truly optional** - Basic SPARQL operations (execute queries, discovery, list layers/steps, ontology management) work without any OpenAI key. Only NL→SPARQL translation requires API_KEY. Clear error message when NL features are used without a key.
- Config loader now supports `.env` files in addition to JSON/JSONC, with clear error for unsupported formats

### Added
- **`--setup-vscode` CLI flag** - Generates `.vscode/mcp.json` in current directory with the correct command path and placeholder credentials
- **`add_select_step` tool** - Create transformation steps from SELECT queries; auto-converts to the required INSERT/GRAPH pattern
- `AZURE_OPENAI_ENDPOINT` environment variable support (defaults to Azure endpoint)

## [0.2.3] - 2026-03-16

### Added
- **Installation verification**: New `--verify` flag runs full diagnostics (Python version, dependencies, PATH, environment variables)
- **Module runner support**: Can now run via `python -m siemens_graph_studio_mcp` when CLI not in PATH
- **Comprehensive Installation Guide**: New `docs/INSTALLATION_GUIDE.md` with:
  - Multiple installation methods (pipx, uv, pip)
  - Step-by-step VS Code MCP setup
  - PATH troubleshooting for all platforms
  - Common error solutions

### Changed
- README now recommends pipx/uv for isolated installation
- Improved troubleshooting section with expandable details

## [0.2.2] - 2026-03-16

### Fixed
- **Critical import bug**: Fixed absolute imports that caused "attempted relative import beyond top-level package" error when running tools after pip install
- All internal imports now use relative imports (e.g., `from .models` instead of `from models`)
- Removed sys.path hacks from tool modules that broke when installed as a package

## [0.2.1] - 2026-03-13

### Added
- "What's New" section in README for PyPI visibility
- VS Code MCP config example file

### Fixed
- Version consistency across all package files
- Removed example credentials from test documentation

## [0.2.0] - 2026-03-13

### Added
- **Property Type Detection**: Distinguish between `owl:ObjectProperty` (relationships) and `owl:DatatypeProperty` (attributes) for smarter query generation
- **Improved Property Discovery**: Knowledge overview now returns ALL object properties + top data properties per class, providing better context for SPARQL query construction
- **Agent System Prompt**: Comprehensive documentation (`docs/AGENT_SYSTEM_PROMPT.md`) with:
  - Recommended query workflow with decision tree
  - Tool call budget (5 calls max per turn)
  - SPARQL best practices and pitfalls
  - Fallback strategies for empty results
- **SPARQL Reference Guide**: New documentation (`docs/SPARQL_REFERENCE.md`) with:
  - Property naming conventions and URI structure
  - Essential query patterns for discovery and exploration
  - Common pitfalls and retry strategies
  - Performance tips
- **Architecture Documentation**: Improved README with module structure and key component descriptions

### Changed
- Enhanced `discover_knowledge_overview` to categorize properties by type (object vs data)
- Property discovery now prioritizes cross-domain relationships (object properties) alongside high-frequency data properties
- Increased property budget from 10 to 50 for comprehensive schema coverage
- Updated cache serialization to persist `is_object_property` field

### Fixed
- Property discovery now correctly identifies property types from OWL type annotations

## [0.1.0] - 2026-03-10

### Added
- Initial public release
- MCP server implementation for Siemens Graph Studio
- SPARQL query execution tools
- Knowledge discovery tools (ontologies, classes, properties)
- Ontology management tools (create, delete, modify)
- GraphMart transformation layer management
- Support for multiple MCP transports (stdio, SSE, HTTP)
- Configuration via environment variables or JSON config files
- OpenAI integration for natural language to SPARQL translation
- Ontology caching for improved performance
- Claude Desktop integration support
- Comprehensive documentation and examples

### Security
- No hardcoded credentials - all configuration via environment variables or config files
- Sensitive values masked in log output
- Apache 2.0 license

## [Unreleased]

### Planned
- Additional query optimization features
- Enhanced error handling and retry logic
- Support for federated queries
- Performance monitoring tools
- Integration with additional AI providers
