idun-agent-schema 0.2.5__tar.gz

idun_agent_schema-0.2.5/.gitignore

@@ -0,0 +1,206 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+.DS_Store
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Database files
+*.db
+*.db-shm
+*.db-wai
+*.db-journal*
+*.sqlite
+*.sqlite3
+agents.db
+checkpoint_async.db
+
+# Python virtual environment
+.venv/
+venv/
+ENV/
+
+# Python cache
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+
+# Poetry
+poetry.lock
+
+# Environment variables
+.env
+
+# Custom Gitignore for Idun
+*.db-wal
+.DS_Store
+*.DS_Store

idun_agent_schema-0.2.5/PKG-INFO

@@ -0,0 +1,39 @@
+Metadata-Version: 2.4
+Name: idun-agent-schema
+Version: 0.2.5
+Summary: Centralized Pydantic schema library for Idun Agent Engine and Manager
+Project-URL: Homepage, https://github.com/geoffreyharrazi/idun-agent-platform
+Project-URL: Repository, https://github.com/geoffreyharrazi/idun-agent-platform
+Project-URL: Issues, https://github.com/geoffreyharrazi/idun-agent-platform/issues
+Author-email: Idun Group <contact@idun-group.com>
+License-Expression: MIT
+Keywords: fastapi,idun,langgraph,pydantic,schemas
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: <3.14,>=3.12
+Requires-Dist: pydantic-settings<3.0.0,>=2.7.0
+Requires-Dist: pydantic<3.0.0,>=2.11.7
+Description-Content-Type: text/markdown
+
+# Idun Agent Schema
+
+Centralized Pydantic schema library shared by Idun Agent Engine and Idun Agent Manager.
+
+## Install
+
+```bash
+pip install idun-agent-schema
+```
+
+## Usage
+
+```python
+from idun_agent_schema.engine import EngineConfig
+from idun_agent_schema.manager.api import AgentCreateRequest
+```
+
+This package re-exports stable schema namespaces to avoid breaking existing imports. Prefer importing from this package directly going forward.

idun_agent_schema-0.2.5/README.md

@@ -0,0 +1,18 @@
+# Idun Agent Schema
+
+Centralized Pydantic schema library shared by Idun Agent Engine and Idun Agent Manager.
+
+## Install
+
+```bash
+pip install idun-agent-schema
+```
+
+## Usage
+
+```python
+from idun_agent_schema.engine import EngineConfig
+from idun_agent_schema.manager.api import AgentCreateRequest
+```
+
+This package re-exports stable schema namespaces to avoid breaking existing imports. Prefer importing from this package directly going forward.

idun_agent_schema-0.2.5/pyproject.toml

@@ -0,0 +1,75 @@
+[project]
+name = "idun-agent-schema"
+version = "0.2.5"
+description = "Centralized Pydantic schema library for Idun Agent Engine and Manager"
+authors = [{ name = "Idun Group", email = "contact@idun-group.com" }]
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12,<3.14"
+keywords = ["pydantic", "schemas", "fastapi", "langgraph", "idun"]
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = [
+  "pydantic>=2.11.7,<3.0.0",
+  "pydantic-settings>=2.7.0,<3.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/geoffreyharrazi/idun-agent-platform"
+Repository = "https://github.com/geoffreyharrazi/idun-agent-platform"
+Issues = "https://github.com/geoffreyharrazi/idun-agent-platform/issues"
+
+[build-system]
+requires = ["hatchling>=1.25.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/idun_agent_schema",
+  "src/idun_agent_schema/py.typed",
+]
+
+[tool.hatch.build.targets.wheel]
+include = [
+  "src/idun_agent_schema",
+  "src/idun_agent_schema/py.typed",
+]
+
+[tool.hatch.build.targets.wheel.sources]
+"src/idun_agent_schema" = "idun_agent_schema"
+
+[tool.ruff]
+target-version = "py312"
+line-length = 88
+
+[tool.ruff.lint]
+select = [
+  "E", "F", "W", "I", "B", "UP", "N", "SIM", "D"
+]
+extend-ignore = ["E501"]
+
+[tool.black]
+line-length = 88
+target-version = ["py312", "py313"]
+include = "\\.pyi?$"
+
+[tool.mypy]
+python_version = "3.12"
+warn_return_any = true
+warn_unused_ignores = true
+ignore_missing_imports = true
+strict_optional = true
+no_implicit_optional = true
+check_untyped_defs = true
+pretty = true
+show_error_codes = true
+
+[tool.pytest.ini_options]
+addopts = "-ra -q --strict-markers --disable-warnings"
+testpaths = ["tests"]

idun_agent_schema-0.2.5/src/idun_agent_schema/__init__.py

@@ -0,0 +1,9 @@
+"""Idun Agent Schema - Centralized Pydantic schemas.
+
+Public namespaces:
+- idun_agent_schema.engine: Engine-related schemas
+- idun_agent_schema.manager: Manager-related schemas
+- idun_agent_schema.shared: Shared cross-cutting schemas
+"""
+
+__version__ = "0.2.5"

idun_agent_schema-0.2.5/src/idun_agent_schema/engine/__init__.py

@@ -0,0 +1,13 @@
+"""Engine-related schemas."""
+
+from .agent import BaseAgentConfig,AgentConfig  # noqa: F401
+from .api import ChatRequest, ChatResponse  # noqa: F401
+from .agent_framework import AgentFramework  # noqa: F401
+from .engine import EngineConfig  # noqa: F401
+from .langgraph import (  # noqa: F401
+    CheckpointConfig,
+    LangGraphAgentConfig,
+    SqliteCheckpointConfig,
+)
+from .server import ServerAPIConfig, ServerConfig  # noqa: F401
+from .observability import ObservabilityConfig  # noqa: F401

idun_agent_schema-0.2.5/src/idun_agent_schema/engine/agent.py

@@ -0,0 +1,42 @@
+"""Common agent model definitions (engine)."""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from idun_agent_schema.engine.agent_framework import AgentFramework
+from idun_agent_schema.engine.langgraph import LangGraphAgentConfig
+from idun_agent_schema.engine.haystack import HaystackAgentConfig
+from idun_agent_schema.engine.base_agent import BaseAgentConfig
+from pydantic import model_validator
+
+
+class AgentConfig(BaseModel):
+    """Configuration for agent specification and settings."""
+
+    type: AgentFramework
+    config: BaseAgentConfig | LangGraphAgentConfig | HaystackAgentConfig
+
+    @model_validator(mode="after")
+    def _validate_framework_config(self) -> "AgentConfig":
+        """Ensure the `config` type matches the selected framework.
+
+        - LANGGRAPH  -> LangGraphAgentConfig
+        - HAYSTACK   -> HaystackAgentConfig
+        - ADK/CREWAI/CUSTOM -> BaseAgentConfig (or subclass)
+        """
+        expected_type: type[BaseAgentConfig] | None = None
+
+        if self.type == AgentFramework.LANGGRAPH:
+            expected_type = LangGraphAgentConfig
+        elif self.type == AgentFramework.HAYSTACK:
+            expected_type = HaystackAgentConfig
+        elif self.type in {AgentFramework.ADK, AgentFramework.CREWAI, AgentFramework.CUSTOM}:
+            expected_type = BaseAgentConfig
+
+        if expected_type is not None and not isinstance(self.config, expected_type):
+            raise ValueError(
+                f"config must be {expected_type.__name__} when type is {self.type}"
+            )
+
+        return self

idun_agent_schema-0.2.5/src/idun_agent_schema/engine/agent_framework.py

@@ -0,0 +1,13 @@
+"""Agent framework enumeration (engine)."""
+
+from enum import Enum
+
+
+class AgentFramework(str, Enum):
+    """Supported agent frameworks for engine."""
+
+    LANGGRAPH = "LANGGRAPH"
+    ADK = "ADK"
+    CREWAI = "CREWAI"
+    HAYSTACK = "HAYSTACK"
+    CUSTOM = "CUSTOM"

idun_agent_schema-0.2.5/src/idun_agent_schema/engine/api.py

@@ -0,0 +1,29 @@
+"""Schemas for engine HTTP API request/response payloads."""
+
+from pydantic import BaseModel
+
+
+class ChatRequest(BaseModel):
+    """Request payload for synchronous and streaming chat endpoints.
+
+    Attributes:
+        session_id: Client-provided session identifier for routing state.
+        query: Natural language prompt or input for the agent.
+
+    """
+
+    session_id: str
+    query: str
+
+
+class ChatResponse(BaseModel):
+    """Response payload for chat endpoints.
+
+    Attributes:
+        session_id: Echoed session identifier.
+        response: Agent's textual response.
+
+    """
+
+    session_id: str
+    response: str

idun_agent_schema-0.2.5/src/idun_agent_schema/engine/base_agent.py

@@ -0,0 +1,15 @@
+"""Common agent model definitions (engine)."""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from idun_agent_schema.engine.observability import ObservabilityConfig
+
+class BaseAgentConfig(BaseModel):
+    """Base model for agent configurations. Extend for specific frameworks."""
+
+    name: str
+    input_schema_definition: dict[str, Any] | None = Field(default_factory=dict)
+    output_schema_definition: dict[str, Any] | None = Field(default_factory=dict)
+    observability: ObservabilityConfig | None = Field(default=None)

idun_agent_schema-0.2.5/src/idun_agent_schema/engine/engine.py

@@ -0,0 +1,13 @@
+"""Main engine configuration model."""
+
+from pydantic import BaseModel, Field
+
+from .server import ServerConfig
+from .agent import AgentConfig
+
+
+class EngineConfig(BaseModel):
+    """Main engine configuration model for the entire Idun Agent Engine."""
+
+    server: ServerConfig = Field(default_factory=ServerConfig)
+    agent: AgentConfig

idun_agent_schema-0.2.5/src/idun_agent_schema/engine/haystack.py

@@ -0,0 +1,13 @@
+"""Configuration models for Haystack agents."""
+
+from typing import Literal
+
+from .base_agent import BaseAgentConfig
+
+
+class HaystackAgentConfig(BaseAgentConfig):
+    """Configuration model for Haystack Agents."""
+
+    type: Literal["haystack"] = "haystack"
+    component_type: Literal["pipeline", "agent"]
+    component_definition: str

idun_agent_schema-0.2.5/src/idun_agent_schema/engine/langgraph.py

@@ -0,0 +1,47 @@
+"""Configuration models for LangGraph agents (engine)."""
+
+from typing import Any, Literal
+from urllib.parse import urlparse
+
+from pydantic import BaseModel, field_validator
+
+from .base_agent import BaseAgentConfig
+
+
+class SqliteCheckpointConfig(BaseModel):
+    """Configuration for SQLite checkpointer."""
+
+    type: Literal["sqlite"]
+    db_url: str
+
+    @field_validator("db_url")
+    @classmethod
+    def db_url_must_be_sqlite(cls, v: str) -> str:
+        """Ensure the provided database URL uses the sqlite scheme.
+
+        Raises:
+            ValueError: If the URL does not start with 'sqlite:///'.
+
+        """
+        if not v.startswith("sqlite:///"):
+            raise ValueError("SQLite DB URL must start with 'sqlite:///'")
+        return v
+
+    @property
+    def db_path(self) -> str:
+        """Return filesystem path component derived from the sqlite URL."""
+        path = urlparse(self.db_url).path
+        if self.db_url.startswith("sqlite:///"):
+            return path.lstrip("/")
+        return path
+
+
+CheckpointConfig = SqliteCheckpointConfig
+
+
+class LangGraphAgentConfig(BaseAgentConfig):
+    """Configuration model for LangGraph agents."""
+
+    graph_definition: str
+    checkpointer: CheckpointConfig | None = None
+    store: dict[str, Any] | None = None

idun_agent_schema-0.2.5/src/idun_agent_schema/engine/observability.py

@@ -0,0 +1,56 @@
+"""Provider-agnostic observability configuration model (engine-scoped)."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+def _resolve_env(value: Any) -> Any:
+    """Resolve environment placeholders in strings.
+
+    Supports patterns ${VAR} and $VAR. Non-strings are returned unchanged.
+    """
+    if isinstance(value, str):
+        if value.startswith("${") and value.endswith("}"):
+            return os.getenv(value[2:-1])
+        if value.startswith("$"):
+            return os.getenv(value[1:])
+    return value
+
+
+class ObservabilityConfig(BaseModel):
+    """Provider-agnostic observability configuration based on Pydantic.
+
+    Example YAML:
+      observability:
+        provider: "langfuse"  # or "phoenix"
+        enabled: true
+        options:
+          host: ${LANGFUSE_HOST}
+          public_key: ${LANGFUSE_PUBLIC_KEY}
+          secret_key: ${LANGFUSE_SECRET_KEY}
+          run_name: "my-run"
+    """
+
+    provider: str | None = Field(default=None)
+    enabled: bool = Field(default=False)
+    options: dict[str, Any] = Field(default_factory=dict)
+
+    def _resolve_value(self, value: Any) -> Any:
+        if isinstance(value, dict):
+            return {k: self._resolve_value(v) for k, v in value.items()}
+        if isinstance(value, list):
+            return [self._resolve_value(v) for v in value]
+        return _resolve_env(value)
+
+    def resolved(self) -> ObservabilityConfig:
+        """Return a copy with env placeholders resolved in options."""
+        resolved_options = self._resolve_value(self.options)
+        return ObservabilityConfig(
+            provider=self.provider,
+            enabled=self.enabled,
+            options=resolved_options,
+        )

idun_agent_schema-0.2.5/src/idun_agent_schema/engine/server.py

@@ -0,0 +1,15 @@
+"""Server configuration models (engine)."""
+
+from pydantic import BaseModel, Field
+
+
+class ServerAPIConfig(BaseModel):
+    """API server configuration."""
+
+    port: int = 8000
+
+
+class ServerConfig(BaseModel):
+    """Configuration for the Engine's universal settings."""
+
+    api: ServerAPIConfig = Field(default_factory=ServerAPIConfig)

idun_agent_schema-0.2.5/src/idun_agent_schema/manager/__init__.py

@@ -0,0 +1,9 @@
+"""Manager-related schemas."""
+
+from .managed_agent import (  # noqa: F401
+    ManagedAgentCreate,
+    ManagedAgentRead,
+    ManagedAgentPatch,
+    AgentStatus,
+)
+from .api import ApiKeyResponse  # noqa: F401

idun_agent_schema-0.2.5/src/idun_agent_schema/manager/api.py

@@ -0,0 +1,17 @@
+"""Pydantic schemas for Agent Manager API I/O."""
+
+from datetime import datetime
+from typing import Any
+from uuid import UUID
+
+from pydantic import BaseModel, Field, field_validator
+
+class ApiKeyResponse(BaseModel):
+    """Response shape for a single agent resource."""
+
+    api_key: str
+
+    class Config:
+        """Pydantic configuration for ORM compatibility."""
+
+        from_attributes = True

idun_agent_schema-0.2.5/src/idun_agent_schema/manager/managed_agent.py

@@ -0,0 +1,58 @@
+"""Main managed agent configuration model."""
+
+from datetime import datetime
+from typing import Any
+from uuid import UUID
+
+from pydantic import BaseModel, Field, field_validator, ConfigDict
+
+from idun_agent_schema.engine import EngineConfig
+from enum import Enum
+
+
+class AgentStatus(str, Enum):
+    """Agent status enumeration."""
+
+    DRAFT = "draft"
+    ACTIVE = "active"
+    INACTIVE = "inactive"
+    DEPRECATED = "deprecated"
+    ERROR = "error"
+
+# class ManagedAgentBase(BaseModel):
+#     """Base model for managed agent configuration."""
+
+#     id: UUID = Field(, description="Agent UUID")
+#     name: str
+#     status: AgentStatus = Field(AgentStatus.DRAFT, description="Agent status")
+#     version: str | None = Field(None, description="Agent version")
+#     engine_config: EngineConfig = Field(..., description="Idun Agent Engine configuration")
+#     created_at: datetime = Field(..., description="Creation timestamp")
+#     updated_at: datetime = Field(..., description="Last update timestamp")
+#     agent_hash: str | None = Field(default=None, description="Agent hash")
+
+class ManagedAgentCreate(BaseModel):
+    """Create managed agent model for requests."""
+
+    name: str
+    version: str | None = Field(None, description="Agent version")
+    engine_config: EngineConfig = Field(..., description="Idun Agent Engine configuration")
+
+
+class ManagedAgentRead(BaseModel):
+    """Complete managed agent model for responses."""
+    model_config = ConfigDict(from_attributes=True)
+
+    id: UUID
+    name: str
+    status: AgentStatus = Field(AgentStatus.DRAFT, description="Agent status")
+    version: str | None = Field(None, description="Agent version")
+    engine_config: EngineConfig = Field(..., description="Idun Agent Engine configuration")
+    created_at: datetime = Field(..., description="Creation timestamp")
+    updated_at: datetime = Field(..., description="Last update timestamp")
+
+
+class ManagedAgentPatch(BaseModel):
+    """Full replacement schema for PUT of a managed agent."""
+    name: str
+    engine_config: EngineConfig = Field(..., description="Idun Agent Engine configuration")

idun_agent_schema-0.2.5/src/idun_agent_schema/shared/__init__.py

@@ -0,0 +1 @@
+"""Shared cross-cutting schemas used by both Engine and Manager."""