Metadata-Version: 2.5
Name: juntai-query-engine
Version: 2.0.0
Summary: Policy-aware in-process logical query planning for Meridian.
Author-email: Juntai Team <dev@juntai.com>
License: Proprietary
Requires-Python: >=3.12
Requires-Dist: juntai-iam==2.0.0
Requires-Dist: meridian-storage-core==1.0.0
Requires-Dist: meridian-storage-query==1.0.0
Requires-Dist: meridian-storage-semantics==1.0.0
Requires-Dist: pydantic<3.0.0,>=2.10.0
Provides-Extra: test
Requires-Dist: build<2.0.0,>=1.2.2; extra == 'test'
Requires-Dist: pytest<9.0.0,>=8.3.0; extra == 'test'
Requires-Dist: ruff<1.0.0,>=0.11.0; extra == 'test'
Description-Content-Type: text/markdown

# Juntai Query Engine

`juntai-query-engine` is a synchronous, in-process Python library that validates an
authorized Juntai logical query, translates it to Meridian's public `structured`
Catalog, and returns a stable Juntai query page. It is not an HTTP service, a storage
Engine, an Adapter registry, or an IAM policy evaluator.

The `2.0.0` contract deliberately has three public operations:

- `JuntaiQueryEngine.query(plan, context)` validates and executes one logical query.
- `JuntaiQueryEngine.catalog(context)` exposes only the authorized logical query surface.
- `JuntaiQueryEngine.translate(text, context)` optionally produces an unexecuted plan
  through an injected translator.

## Composition

The application supplies four in-process objects:

1. an immutable `SnapshotStore` containing exact schema-policy snapshots;
2. a Meridian runtime implementing the IAM operation-context hook, `catalog()`, and
   `execute()`;
3. the exact snapshot digest selected for the request;
4. optionally, a domain-owned natural-language translator.

```python
from juntai_query_engine import JuntaiQueryEngine

engine = JuntaiQueryEngine(
    runtime=meridian_runtime,
    snapshots=snapshot_store,
    snapshot_digest="sha256:...",
)
page = engine.query(plan, authorized_operation_context)
```

Plans use `formatVersion: juntai.logical-query.v1`. They contain a logical resource,
filter, projection, sort, and page only. Tenant, principal, physical storage names,
Bindings, credentials, Adapters, and native cursors are forbidden. Meridian owns the
opaque cursor returned by execution.

The engine validates the exact snapshot, trusted IAM context, field authorization,
operators, limits, deterministic ordering, and result envelope before it touches the
runtime. It then enters IAM's verified operation scope, creates one public Meridian
expression, and calls `runtime.execute(expression)` exactly once.

## Development

```bash
python -m pip install -e '.[test]'
ruff check .
pytest
python -m build
```

Python 3.12 and 3.13 are supported. Runtime dependencies are intentionally pinned
to IAM 2.0.0 and the Meridian 1.0.0 public contracts.
