# Garden Layer helper module

The garden layer sits on top of `virtuoso_mcp`. It knows your garden-specific URIs (cycles, clone roots, seed products) but delegates every SPARQL/insert/discovery call to the MCP helpers.

## Structure

- `config.py` loads `.env` values and exposes the Garden URIs (seed product, cycle `2026-3`, clone property, etc.).
- `helpers.py` defines `GardenLayer`, which wraps MCP tools such as `insert_triple`, `traverse_property`, and ontology discovery into domain actions (`add_seedling`, `traverse`).

## Domain helpers

`GardenLayer` now exposes these convenience methods:

- `describe_subject(subject_uri, limit=10)` – returns predicates/objects (with labels) for a given node.
- `path_traverse(subject_uri, property_path, direction="outgoing", limit=10)` – walks a property sequence from the subject and returns each step’s bindings.
- `property_usage_statistics(property_uri, examples_limit=5)` – reports how often a property is used and includes sample subjects/objects.
- `batch_insert(ttl, graph=None)` – pushes a TTL snippet (or multiple triples via TTL) into the chosen graph in a single request.

These helpers keep domain code focused on planned workflows while still leveraging the generic MCP toolset.

## Architectural split

- `virtuoso_mcp` owns **generic** capabilities: query guardrails, traversal, ontology/class/property discovery.
- `garden_layer` owns **domain workflows**: breeding lifecycle helpers, documentation flows, trait-specific routines.

This split allows additional specialized layers to reuse the same generic ontology tooling without copy/paste.

## Example

```python
from garden_layer import GardenLayer
from garden_layer.config import SEED_PRODUCT, CYCLE_2026_3

garden = GardenLayer()
garden.add_seedling(
    plant_uri="http://world.eu.org/example1#Plant_cookie_kerosene_2027",
    seed_product_uri=SEED_PRODUCT,
    cycle_uri=CYCLE_2026_3,
    label="Cookie x Kerosene 2027",
)
``` 

## Testing

`garden_layer/test_garden_layer.py` exercises the garden helpers (`traverse`, `describe_subject`, `path_traverse`, `property_usage_statistics`, and `batch_insert`) against a running MCP server. Start the MCP service (`./virtuoso_mcp/run.sh` or `./restart.sh`) before running the tests and invoke them with `python3 -m pytest garden_layer/test_garden_layer.py`. If `pytest` is not installed, install it inside a virtual environment (e.g., `python3 -m venv .env && .env/bin/pip install pytest`).