#
# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements.  See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership.  The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License.  You may obtain a copy of the License at
#
#   https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied.  See the License for the
# specific language governing permissions and limitations
# under the License.
#

"""Pydantic models for Veculo API request and response objects."""

from __future__ import annotations

from typing import Any, Optional

from pydantic import BaseModel, Field


class Vertex(BaseModel):
    """A vertex (node) in the graph.

    Attributes:
        id: Unique vertex identifier.
        label: Vertex label / type (e.g., ``"person"``, ``"document"``).
        properties: Arbitrary key-value properties stored on the vertex.
        embedding: Optional vector embedding for similarity search.
        visibility: Accumulo-style visibility expression (e.g., ``"PUBLIC"``).
    """

    id: str
    label: str = "default"
    properties: dict[str, Any] = Field(default_factory=dict)
    embedding: Optional[list[float]] = None
    visibility: Optional[str] = None


class Edge(BaseModel):
    """A directed edge connecting two vertices.

    Attributes:
        source: Source vertex ID.
        target: Target vertex ID.
        edge_type: Relationship type (e.g., ``"knows"``, ``"contains"``).
        properties: Arbitrary key-value properties stored on the edge.
        visibility: Accumulo-style visibility expression.
    """

    source: str
    target: str
    edge_type: str
    properties: dict[str, Any] = Field(default_factory=dict)
    visibility: Optional[str] = None


class VectorResult(BaseModel):
    """A single result from a vector similarity search.

    Attributes:
        vertex_id: ID of the matched vertex.
        score: Cosine similarity score (0.0 to 1.0).
        properties: Properties of the matched vertex.
    """

    vertex_id: str
    score: float
    properties: dict[str, Any] = Field(default_factory=dict)


class QueryResult(BaseModel):
    """Combined result from a hybrid vector + graph query.

    Attributes:
        results: List of vector similarity matches.
        graph_context: Neighboring vertices and edges discovered via traversal.
    """

    results: list[VectorResult] = Field(default_factory=list)
    graph_context: dict[str, Any] = Field(default_factory=dict)
