exemplar-core 0.1.0__tar.gz

exemplar_core-0.1.0/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.1
+Name: exemplar-core
+Version: 0.1.0
+Summary: Shared Exemplar REST clients for skills and memory
+License: LicenseRef-Proprietary
+Author: Exemplar Dev LLC
+Requires-Python: >=3.10,<3.14
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: httpx (>=0.27.0)
+Description-Content-Type: text/markdown
+
+# exemplar-core
+
+Shared HTTP clients for Exemplar **skills** (`/api/agent-skills`) and **memory** (`/api/harness-memory`).
+
+Used by `exemplar-harness-sdk` and `exemplar-cli`. Install directly only if you need the REST layer without the full SDK.
+
+```bash
+pip install exemplar-core
+export EXEMPLAR_API_KEY=eis_...
+```
+
+```python
+from exemplar_core import skills_from_env, memory_from_env
+
+skills = skills_from_env()
+memory = memory_from_env(user_id="user-123")
+```
+

exemplar_core-0.1.0/README.md

@@ -0,0 +1,17 @@
+# exemplar-core
+
+Shared HTTP clients for Exemplar **skills** (`/api/agent-skills`) and **memory** (`/api/harness-memory`).
+
+Used by `exemplar-harness-sdk` and `exemplar-cli`. Install directly only if you need the REST layer without the full SDK.
+
+```bash
+pip install exemplar-core
+export EXEMPLAR_API_KEY=eis_...
+```
+
+```python
+from exemplar_core import skills_from_env, memory_from_env
+
+skills = skills_from_env()
+memory = memory_from_env(user_id="user-123")
+```

exemplar_core-0.1.0/exemplar_core/__init__.py

@@ -0,0 +1,63 @@
+"""Shared Exemplar REST clients for skills and memory."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from exemplar_core.config import (
+    Environment,
+    resolve_api_key,
+    resolve_base_url,
+    resolve_organization_id,
+)
+from exemplar_core.exceptions import ExemplarAPIError, ExemplarConfigError, ExemplarError
+from exemplar_core.memory.client import MemoryHTTPClient
+from exemplar_core.memory.memory import HarnessMemory
+from exemplar_core.memory.models import MemoryRecord, MemoryScopes
+from exemplar_core.skills.client import SkillsHTTPClient
+from exemplar_core.skills.models import SkillRecord, SkillSummary
+from exemplar_core.skills.skills import HarnessSkills
+
+__all__ = [
+    "Environment",
+    "ExemplarAPIError",
+    "ExemplarConfigError",
+    "ExemplarError",
+    "HarnessMemory",
+    "HarnessSkills",
+    "MemoryRecord",
+    "MemoryScopes",
+    "SkillRecord",
+    "SkillSummary",
+    "memory_from_env",
+    "skills_from_env",
+]
+
+
+def skills_from_env(*, organization_id: Optional[str] = None) -> HarnessSkills:
+    api_key = resolve_api_key()
+    base_url = resolve_base_url()
+    org_id = resolve_organization_id(organization_id)
+    client = SkillsHTTPClient(api_key=api_key, base_url=base_url, organization_id=org_id)
+    return HarnessSkills(client)
+
+
+def memory_from_env(
+    *,
+    organization_id: Optional[str] = None,
+    user_id: Optional[str] = None,
+    agent_id: Optional[str] = None,
+    session_id: Optional[str] = None,
+    app_id: Optional[str] = None,
+) -> HarnessMemory:
+    api_key = resolve_api_key()
+    base_url = resolve_base_url()
+    org_id = resolve_organization_id(organization_id)
+    client = MemoryHTTPClient(api_key=api_key, base_url=base_url, organization_id=org_id)
+    scopes = MemoryScopes(
+        user_id=user_id,
+        agent_id=agent_id,
+        session_id=session_id,
+        app_id=app_id,
+    )
+    return HarnessMemory(client, scopes=scopes)

exemplar_core-0.1.0/exemplar_core/config.py

@@ -0,0 +1,64 @@
+"""Resolve API key, base URL, and environment."""
+
+from __future__ import annotations
+
+import os
+from enum import Enum
+from typing import Optional
+
+from exemplar_core.exceptions import ExemplarConfigError
+
+BASE_URLS = {
+    "production": "https://production-api.exemplar.dev",
+    "development": "https://development-api.exemplar.dev",
+    "local": "http://localhost:8000",
+}
+
+
+class Environment(str, Enum):
+    PRODUCTION = "production"
+    DEVELOPMENT = "development"
+    LOCAL = "local"
+
+
+def resolve_api_key(explicit: Optional[str] = None) -> str:
+    key = explicit or os.environ.get("EXEMPLAR_API_KEY") or ""
+    if not key:
+        raise ExemplarConfigError("EXEMPLAR_API_KEY is not set")
+    return key
+
+
+def resolve_environment(explicit: Optional[Environment | str] = None) -> Environment:
+    if explicit is not None:
+        if isinstance(explicit, Environment):
+            return explicit
+        return Environment(str(explicit).lower())
+    env = (os.environ.get("EXEMPLAR_ENV") or "production").lower()
+    try:
+        return Environment(env)
+    except ValueError:
+        return Environment.PRODUCTION
+
+
+def resolve_base_url(
+    *,
+    base_url: Optional[str] = None,
+    environment: Optional[Environment | str] = None,
+) -> str:
+    if base_url:
+        return base_url.rstrip("/")
+    env_url = os.environ.get("EXEMPLAR_BASE_URL")
+    if env_url:
+        return env_url.rstrip("/")
+    env = resolve_environment(environment)
+    return BASE_URLS[env.value]
+
+
+def resolve_organization_id(explicit: Optional[str] = None) -> Optional[str]:
+    org_id = (
+        explicit
+        or os.environ.get("EXEMPLAR_ORGANIZATION_ID")
+        or os.environ.get("EXEMPLAR_ORG_ID")
+        or ""
+    ).strip()
+    return org_id or None

exemplar_core-0.1.0/exemplar_core/exceptions.py

@@ -0,0 +1,20 @@
+"""Core library exceptions."""
+
+from __future__ import annotations
+
+
+class ExemplarError(Exception):
+    """Base error."""
+
+
+class ExemplarConfigError(ExemplarError):
+    """Missing or invalid configuration."""
+
+
+class ExemplarAPIError(ExemplarError):
+    """Integration-service API returned an error."""
+
+    def __init__(self, status_code: int, message: str) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.message = message

exemplar_core-0.1.0/exemplar_core/memory/__init__.py

@@ -0,0 +1,21 @@
+"""Harness memory client."""
+
+from exemplar_core.memory.memory import HarnessMemory
+from exemplar_core.memory.models import (
+    MemoryRecord,
+    MemoryScopes,
+    normalize_search_filters,
+    require_bulk_delete_filters,
+    require_scope,
+    scopes_from_kwargs,
+)
+
+__all__ = [
+    "HarnessMemory",
+    "MemoryRecord",
+    "MemoryScopes",
+    "normalize_search_filters",
+    "require_bulk_delete_filters",
+    "require_scope",
+    "scopes_from_kwargs",
+]

exemplar_core-0.1.0/exemplar_core/memory/client.py

@@ -0,0 +1,80 @@
+"""HTTP client for /api/harness-memory."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import httpx
+
+from exemplar_core.exceptions import ExemplarAPIError
+
+MEMORY_PREFIX = "/api/harness-memory"
+
+
+class MemoryHTTPClient:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str,
+        organization_id: Optional[str] = None,
+        timeout: float = 60.0,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._organization_id = (organization_id or "").strip() or None
+        self._timeout = timeout
+
+    def _headers(self) -> dict[str, str]:
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "X-API-Key": self._api_key,
+            "Content-Type": "application/json",
+        }
+        if self._organization_id:
+            headers["x-organization-id"] = self._organization_id
+        return headers
+
+    def _url(self, path: str) -> str:
+        return f"{self._base_url}{MEMORY_PREFIX}{path}"
+
+    def post(self, path: str, body: dict[str, Any]) -> dict[str, Any]:
+        with httpx.Client(timeout=self._timeout) as client:
+            resp = client.post(self._url(path), json=body, headers=self._headers())
+        if resp.status_code >= 400:
+            raise ExemplarAPIError(resp.status_code, resp.text[:2000])
+        if resp.status_code == 204 or not resp.content:
+            return {}
+        return resp.json()
+
+    def put(self, path: str, body: dict[str, Any]) -> dict[str, Any]:
+        with httpx.Client(timeout=self._timeout) as client:
+            resp = client.put(self._url(path), json=body, headers=self._headers())
+        if resp.status_code >= 400:
+            raise ExemplarAPIError(resp.status_code, resp.text[:2000])
+        if resp.status_code == 204 or not resp.content:
+            return {}
+        return resp.json()
+
+    def get(self, path: str, *, params: Optional[dict[str, Any]] = None) -> dict[str, Any]:
+        with httpx.Client(timeout=self._timeout) as client:
+            resp = client.get(self._url(path), headers=self._headers(), params=params)
+        if resp.status_code >= 400:
+            raise ExemplarAPIError(resp.status_code, resp.text[:2000])
+        if resp.status_code == 204 or not resp.content:
+            return {}
+        return resp.json()
+
+    def delete(self, path: str, *, body: Optional[dict[str, Any]] = None) -> dict[str, Any]:
+        with httpx.Client(timeout=self._timeout) as client:
+            resp = client.request(
+                "DELETE",
+                self._url(path),
+                headers=self._headers(),
+                json=body,
+            )
+        if resp.status_code >= 400:
+            raise ExemplarAPIError(resp.status_code, resp.text[:2000])
+        if resp.status_code == 204 or not resp.content:
+            return {}
+        return resp.json()

exemplar_core-0.1.0/exemplar_core/memory/memory.py

@@ -0,0 +1,207 @@
+"""High-level harness memory API."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Optional
+
+from exemplar_core.memory.client import MemoryHTTPClient
+from exemplar_core.memory.models import (
+    MemoryRecord,
+    MemoryScopes,
+    normalize_search_filters,
+    require_bulk_delete_filters,
+    require_scope,
+)
+
+
+def _format_recall(results: list[MemoryRecord]) -> str:
+    if not results:
+        return ""
+    lines = ["Relevant memories:"]
+    for item in results:
+        prefix = f"- [{item.memory_type}]"
+        if item.score is not None:
+            prefix = f"- ({item.score:.2f}) [{item.memory_type}]"
+        lines.append(f"{prefix} {item.content}")
+    return "\n".join(lines)
+
+
+class HarnessMemory:
+    """Add, search, and inject long-term memory via integration-service REST."""
+
+    def __init__(
+        self,
+        client: MemoryHTTPClient,
+        *,
+        scopes: Optional[MemoryScopes] = None,
+    ) -> None:
+        self._client = client
+        self._scopes = scopes or MemoryScopes()
+
+    @property
+    def scopes(self) -> MemoryScopes:
+        return self._scopes
+
+    def with_scopes(self, **kwargs: Any) -> "HarnessMemory":
+        merged = MemoryScopes(
+            user_id=kwargs.get("user_id", self._scopes.user_id),
+            agent_id=kwargs.get("agent_id", self._scopes.agent_id),
+            session_id=kwargs.get("session_id", self._scopes.session_id),
+            app_id=kwargs.get("app_id", self._scopes.app_id),
+        )
+        return HarnessMemory(self._client, scopes=merged)
+
+    def add(
+        self,
+        content: str,
+        *,
+        memory_type: str = "fact",
+        metadata: Optional[dict[str, Any]] = None,
+        scopes: Optional[MemoryScopes] = None,
+    ) -> dict[str, Any]:
+        text = (content or "").strip()
+        if not text:
+            raise ValueError("content must be non-empty")
+        active = scopes or self._scopes
+        require_scope(active)
+        body: dict[str, Any] = {
+            "content": text,
+            "memoryType": memory_type,
+            "scopes": active.to_api_dict(),
+            "metadata": metadata or {},
+        }
+        return self._client.post("/v1/memories", body)
+
+    def update(
+        self,
+        memory_id: str,
+        *,
+        content: Optional[str] = None,
+        memory_type: Optional[str] = None,
+        scopes: Optional[MemoryScopes] = None,
+        metadata: Optional[dict[str, Any]] = None,
+        expires_at: Optional[datetime] = None,
+    ) -> MemoryRecord:
+        mid = (memory_id or "").strip()
+        if not mid:
+            raise ValueError("memory_id must be non-empty")
+        body: dict[str, Any] = {}
+        if content is not None:
+            text = content.strip()
+            if not text:
+                raise ValueError("content must be non-empty when provided")
+            body["content"] = text
+        if memory_type is not None:
+            body["memoryType"] = memory_type
+        if scopes is not None:
+            require_scope(scopes)
+            body["scopes"] = scopes.to_api_dict()
+        if metadata is not None:
+            body["metadata"] = metadata
+        if expires_at is not None:
+            body["expiresAt"] = expires_at.isoformat()
+        if not body:
+            raise ValueError("at least one field must be provided to update")
+        raw = self._client.put(f"/v1/memories/{mid}", body)
+        return MemoryRecord.from_api(raw)
+
+    def search(
+        self,
+        query: str,
+        *,
+        top_k: int = 10,
+        threshold: float = 0.1,
+        include_episodic: bool = False,
+        filters: Optional[dict[str, Any]] = None,
+        scopes: Optional[MemoryScopes] = None,
+    ) -> list[MemoryRecord]:
+        q = (query or "").strip()
+        if not q:
+            raise ValueError("query must be non-empty")
+        active = scopes or self._scopes
+        merged_filters = dict(filters or {})
+        for key, val in active.to_filter_dict().items():
+            merged_filters.setdefault(key, val)
+        body = {
+            "query": q,
+            "filters": normalize_search_filters(merged_filters),
+            "topK": top_k,
+            "threshold": threshold,
+            "includeEpisodic": include_episodic,
+        }
+        raw = self._client.post("/v1/memories/search", body)
+        results = raw.get("results") if isinstance(raw, dict) else []
+        if not isinstance(results, list):
+            return []
+        return [MemoryRecord.from_api(item) for item in results if isinstance(item, dict)]
+
+    def recall(
+        self,
+        query: str,
+        *,
+        top_k: int = 5,
+        threshold: float = 0.1,
+        **search_kwargs: Any,
+    ) -> str:
+        """Return formatted memory context suitable for a system prompt."""
+        records = self.search(query, top_k=top_k, threshold=threshold, **search_kwargs)
+        return _format_recall(records)
+
+    def list(
+        self,
+        *,
+        skip: int = 0,
+        limit: int = 100,
+        memory_type: Optional[str] = None,
+        include_episodic: bool = True,
+        scopes: Optional[MemoryScopes] = None,
+    ) -> list[MemoryRecord]:
+        active = scopes or self._scopes
+        params: dict[str, Any] = {
+            "skip": skip,
+            "limit": limit,
+            "includeEpisodic": include_episodic,
+        }
+        params.update(active.to_api_dict())
+        if memory_type:
+            params["memoryType"] = memory_type
+        raw = self._client.get("/v1/memories", params=params)
+        memories = raw.get("memories") if isinstance(raw, dict) else []
+        if not isinstance(memories, list):
+            return []
+        return [MemoryRecord.from_api(item) for item in memories if isinstance(item, dict)]
+
+    def get(self, memory_id: str) -> MemoryRecord:
+        mid = (memory_id or "").strip()
+        if not mid:
+            raise ValueError("memory_id must be non-empty")
+        raw = self._client.get(f"/v1/memories/{mid}")
+        return MemoryRecord.from_api(raw)
+
+    def delete(self, memory_id: str) -> None:
+        mid = (memory_id or "").strip()
+        if not mid:
+            raise ValueError("memory_id must be non-empty")
+        self._client.delete(f"/v1/memories/{mid}")
+
+    def delete_bulk(
+        self,
+        *,
+        filters: Optional[dict[str, Any]] = None,
+        scopes: Optional[MemoryScopes] = None,
+        memory_type: Optional[str] = None,
+    ) -> int:
+        """Delete all memories matching filters (requires at least one scope filter)."""
+        active = scopes or self._scopes
+        merged: dict[str, Any] = dict(filters or {})
+        for key, val in active.to_filter_dict().items():
+            merged.setdefault(key, val)
+        if memory_type:
+            merged["memoryType"] = memory_type
+        require_bulk_delete_filters(merged)
+        raw = self._client.delete(
+            "/v1/memories",
+            body={"filters": normalize_search_filters(merged)},
+        )
+        return int(raw.get("deleted", 0))

exemplar_core-0.1.0/exemplar_core/memory/models.py

@@ -0,0 +1,108 @@
+"""Memory API models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+
+@dataclass
+class MemoryScopes:
+    user_id: Optional[str] = None
+    agent_id: Optional[str] = None
+    session_id: Optional[str] = None
+    app_id: Optional[str] = None
+
+    def to_api_dict(self) -> dict[str, str]:
+        out: dict[str, str] = {}
+        if self.user_id:
+            out["userId"] = self.user_id
+        if self.agent_id:
+            out["agentId"] = self.agent_id
+        if self.session_id:
+            out["sessionId"] = self.session_id
+        if self.app_id:
+            out["appId"] = self.app_id
+        return out
+
+    def to_filter_dict(self) -> dict[str, str]:
+        return dict(self.to_api_dict())
+
+    def has_scope(self) -> bool:
+        return bool(self.to_api_dict())
+
+
+SCOPE_REQUIRED_MSG = (
+    "at least one scope is required (userId, agentId, sessionId, or appId)"
+)
+
+
+def require_scope(scopes: MemoryScopes) -> None:
+    if not scopes.has_scope():
+        raise ValueError(SCOPE_REQUIRED_MSG)
+
+
+FILTERS_REQUIRED_MSG = "filters required for bulk delete"
+
+_SCOPE_FILTER_KEYS = ("userId", "agentId", "sessionId", "appId")
+
+
+def require_bulk_delete_filters(filters: dict[str, Any]) -> None:
+    if not filters:
+        raise ValueError(FILTERS_REQUIRED_MSG)
+    if not any(filters.get(key) for key in _SCOPE_FILTER_KEYS):
+        raise ValueError(SCOPE_REQUIRED_MSG)
+
+
+def scopes_from_kwargs(**kwargs: Any) -> MemoryScopes:
+    return MemoryScopes(
+        user_id=kwargs.get("user_id"),
+        agent_id=kwargs.get("agent_id"),
+        session_id=kwargs.get("session_id"),
+        app_id=kwargs.get("app_id"),
+    )
+
+
+def normalize_search_filters(filters: dict[str, Any]) -> dict[str, Any]:
+    """Chroma requires a single top-level operator when combining conditions."""
+    if not filters or len(filters) == 1:
+        return filters
+    if any(str(key).startswith("$") for key in filters):
+        return filters
+    return {"$and": [{key: value} for key, value in filters.items()]}
+
+
+@dataclass
+class MemoryRecord:
+    memory_id: str
+    content: str
+    memory_type: str = "fact"
+    score: Optional[float] = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+    scopes: Optional[MemoryScopes] = None
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> "MemoryRecord":
+        scopes_raw = data.get("scopes")
+        scopes: Optional[MemoryScopes] = None
+        if isinstance(scopes_raw, dict):
+            scopes = MemoryScopes(
+                user_id=scopes_raw.get("userId") or scopes_raw.get("user_id"),
+                agent_id=scopes_raw.get("agentId") or scopes_raw.get("agent_id"),
+                session_id=scopes_raw.get("sessionId") or scopes_raw.get("session_id"),
+                app_id=scopes_raw.get("appId") or scopes_raw.get("app_id"),
+            )
+        created = data.get("createdAt") or data.get("created_at")
+        updated = data.get("updatedAt") or data.get("updated_at")
+        return cls(
+            memory_id=str(data.get("memoryId") or data.get("memory_id") or ""),
+            content=str(data.get("content") or ""),
+            memory_type=str(data.get("memoryType") or data.get("memory_type") or "fact"),
+            score=data.get("score"),
+            metadata=dict(data.get("metadata") or {}),
+            scopes=scopes,
+            created_at=str(created) if created is not None else None,
+            updated_at=str(updated) if updated is not None else None,
+        )

exemplar_core-0.1.0/exemplar_core/skills/__init__.py

@@ -0,0 +1,13 @@
+"""Org-scoped agent skill registry client."""
+
+from exemplar_core.skills.models import SkillRecord, SkillSummary
+from exemplar_core.skills.skill_md import parse_skill_md, skill_md_template
+from exemplar_core.skills.skills import HarnessSkills
+
+__all__ = [
+    "HarnessSkills",
+    "SkillRecord",
+    "SkillSummary",
+    "parse_skill_md",
+    "skill_md_template",
+]

exemplar_core-0.1.0/exemplar_core/skills/client.py

@@ -0,0 +1,90 @@
+"""HTTP client for /api/agent-skills."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import httpx
+
+from exemplar_core.exceptions import ExemplarAPIError
+
+SKILLS_PREFIX = "/api/agent-skills"
+
+
+class SkillsHTTPClient:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str,
+        organization_id: Optional[str] = None,
+        timeout: float = 60.0,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._organization_id = (organization_id or "").strip() or None
+        self._timeout = timeout
+
+    def _headers(self) -> dict[str, str]:
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "X-API-Key": self._api_key,
+            "Content-Type": "application/json",
+        }
+        if self._organization_id:
+            headers["x-organization-id"] = self._organization_id
+        return headers
+
+    def _url(self, path: str) -> str:
+        return f"{self._base_url}{SKILLS_PREFIX}{path}"
+
+    def post(self, path: str, body: dict[str, Any]) -> dict[str, Any]:
+        with httpx.Client(timeout=self._timeout) as client:
+            resp = client.post(self._url(path), json=body, headers=self._headers())
+        if resp.status_code >= 400:
+            raise ExemplarAPIError(resp.status_code, resp.text[:2000])
+        if resp.status_code == 204 or not resp.content:
+            return {}
+        return resp.json()
+
+    def put(self, path: str, body: dict[str, Any]) -> dict[str, Any]:
+        with httpx.Client(timeout=self._timeout) as client:
+            resp = client.put(self._url(path), json=body, headers=self._headers())
+        if resp.status_code >= 400:
+            raise ExemplarAPIError(resp.status_code, resp.text[:2000])
+        if resp.status_code == 204 or not resp.content:
+            return {}
+        return resp.json()
+
+    def get(
+        self,
+        path: str,
+        *,
+        params: Optional[dict[str, Any]] = None,
+        as_text: bool = False,
+    ) -> Any:
+        with httpx.Client(timeout=self._timeout) as client:
+            resp = client.get(self._url(path), headers=self._headers(), params=params)
+        if resp.status_code >= 400:
+            raise ExemplarAPIError(resp.status_code, resp.text[:2000])
+        if resp.status_code == 204 or not resp.content:
+            return {} if not as_text else ""
+        if as_text:
+            return resp.text
+        return resp.json()
+
+    def delete(self, path: str) -> dict[str, Any]:
+        with httpx.Client(timeout=self._timeout) as client:
+            resp = client.delete(self._url(path), headers=self._headers())
+        if resp.status_code >= 400:
+            raise ExemplarAPIError(resp.status_code, resp.text[:2000])
+        if resp.status_code == 204 or not resp.content:
+            return {}
+        return resp.json()
+
+    def get_bytes(self, path: str, *, params: Optional[dict[str, Any]] = None) -> bytes:
+        with httpx.Client(timeout=self._timeout) as client:
+            resp = client.get(self._url(path), headers=self._headers(), params=params)
+        if resp.status_code >= 400:
+            raise ExemplarAPIError(resp.status_code, resp.text[:2000])
+        return resp.content

exemplar_core-0.1.0/exemplar_core/skills/models.py

@@ -0,0 +1,70 @@
+"""Agent skill registry API models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+
+@dataclass
+class SkillRecord:
+    skill_id: str
+    name: str
+    display_name: str = ""
+    description: str = ""
+    instructions: str = ""
+    tags: list[str] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+    status: str = "active"
+    file_count: int = 0
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+    created_by: Optional[str] = None
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> "SkillRecord":
+        return cls(
+            skill_id=str(data.get("skillId") or data.get("skill_id") or ""),
+            name=str(data.get("name") or ""),
+            display_name=str(data.get("displayName") or data.get("display_name") or data.get("name") or ""),
+            description=str(data.get("description") or ""),
+            instructions=str(data.get("instructions") or ""),
+            tags=list(data.get("tags") or []),
+            metadata=dict(data.get("metadata") or {}),
+            status=str(data.get("status") or "active"),
+            file_count=int(data.get("fileCount") or data.get("file_count") or 0),
+            created_at=_str_or_none(data.get("createdAt") or data.get("created_at")),
+            updated_at=_str_or_none(data.get("updatedAt") or data.get("updated_at")),
+            created_by=data.get("createdBy") or data.get("created_by"),
+        )
+
+
+@dataclass
+class SkillSummary:
+    skill_id: str
+    name: str
+    display_name: str = ""
+    description: str = ""
+    tags: list[str] = field(default_factory=list)
+    status: str = "active"
+    file_count: int = 0
+    updated_at: Optional[str] = None
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> "SkillSummary":
+        return cls(
+            skill_id=str(data.get("skillId") or data.get("skill_id") or ""),
+            name=str(data.get("name") or ""),
+            display_name=str(data.get("displayName") or data.get("display_name") or data.get("name") or ""),
+            description=str(data.get("description") or ""),
+            tags=list(data.get("tags") or []),
+            status=str(data.get("status") or "active"),
+            file_count=int(data.get("fileCount") or data.get("file_count") or 0),
+            updated_at=_str_or_none(data.get("updatedAt") or data.get("updated_at")),
+        )
+
+
+def _str_or_none(value: Any) -> Optional[str]:
+    if value is None:
+        return None
+    return str(value)

exemplar_core-0.1.0/exemplar_core/skills/skill_md.py

@@ -0,0 +1,54 @@
+"""Parse and synthesize local SKILL.md files for CLI push/pull."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def parse_skill_md(content: str) -> dict[str, Any]:
+    """Extract name, description, and instructions from SKILL.md frontmatter."""
+    text = content or ""
+    if not text.startswith("---\n"):
+        return {"name": "", "description": "", "instructions": text.strip()}
+
+    end = text.find("\n---\n", 4)
+    if end == -1:
+        return {"name": "", "description": "", "instructions": text.strip()}
+
+    frontmatter = text[4:end]
+    body = text[end + 5 :].strip()
+    name = ""
+    description_lines: list[str] = []
+    description_mode = False
+
+    for line in frontmatter.splitlines():
+        if line.startswith("name:"):
+            name = line.split(":", 1)[1].strip()
+        elif line.startswith("description:"):
+            rest = line.split(":", 1)[1].strip()
+            if rest == ">-":
+                description_mode = True
+            elif rest:
+                description = rest
+                description_mode = False
+            else:
+                description_mode = True
+        elif description_mode:
+            description_lines.append(line.strip())
+
+    description = " ".join(description_lines).strip() if description_lines else ""
+    if not description and "description:" in frontmatter:
+        for line in frontmatter.splitlines():
+            if line.startswith("description:") and line.split(":", 1)[1].strip() not in (">-", ""):
+                description = line.split(":", 1)[1].strip()
+                break
+
+    return {"name": name, "description": description, "instructions": body}
+
+
+def skill_md_template(*, name: str, description: str = "", instructions: str = "") -> str:
+    lines = ["---", f"name: {name}"]
+    if description:
+        lines.append(f"description: {description}")
+    lines.extend(["---", "", instructions.strip(), ""])
+    return "\n".join(lines)

exemplar_core-0.1.0/exemplar_core/skills/skills.py

@@ -0,0 +1,134 @@
+"""High-level org-scoped agent skill registry API."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from exemplar_core.skills.client import SkillsHTTPClient
+from exemplar_core.skills.models import SkillRecord, SkillSummary
+
+
+class HarnessSkills:
+    """Create, list, search, and export org skills via integration-service REST."""
+
+    def __init__(self, client: SkillsHTTPClient) -> None:
+        self._client = client
+
+    def create(
+        self,
+        *,
+        name: str,
+        instructions: str,
+        description: Optional[str] = None,
+        display_name: Optional[str] = None,
+        tags: Optional[list[str]] = None,
+        metadata: Optional[dict[str, Any]] = None,
+        files: Optional[dict[str, str]] = None,
+    ) -> SkillRecord:
+        body: dict[str, Any] = {
+            "name": name.strip(),
+            "instructions": instructions.strip(),
+            "tags": tags or [],
+            "metadata": metadata or {},
+            "files": files or {},
+        }
+        if description is not None:
+            body["description"] = description
+        if display_name is not None:
+            body["displayName"] = display_name
+        data = self._client.post("/v1/skills", body)
+        return SkillRecord.from_api(data)
+
+    def list(
+        self,
+        *,
+        skip: int = 0,
+        limit: int = 100,
+        status: str = "active",
+        tag: Optional[str] = None,
+        query: Optional[str] = None,
+    ) -> list[SkillSummary]:
+        params: dict[str, Any] = {"skip": skip, "limit": limit, "status": status}
+        if tag:
+            params["tag"] = tag
+        if query:
+            params["query"] = query
+        data = self._client.get("/v1/skills", params=params)
+        return [SkillSummary.from_api(item) for item in data.get("skills") or []]
+
+    def get(self, skill_id_or_name: str) -> SkillRecord:
+        key = (skill_id_or_name or "").strip()
+        if not key:
+            raise ValueError("skill_id_or_name must be non-empty")
+        if key.startswith("skill_"):
+            data = self._client.get(f"/v1/skills/{key}")
+            return SkillRecord.from_api(data)
+        for item in self.list(limit=500):
+            if item.name == key or item.skill_id == key:
+                return self.get(item.skill_id)
+        raise ValueError(f"skill not found: {key}")
+
+    def update(
+        self,
+        skill_id: str,
+        *,
+        instructions: Optional[str] = None,
+        description: Optional[str] = None,
+        display_name: Optional[str] = None,
+        tags: Optional[list[str]] = None,
+        metadata: Optional[dict[str, Any]] = None,
+        status: Optional[str] = None,
+    ) -> SkillRecord:
+        body: dict[str, Any] = {}
+        if instructions is not None:
+            body["instructions"] = instructions
+        if description is not None:
+            body["description"] = description
+        if display_name is not None:
+            body["displayName"] = display_name
+        if tags is not None:
+            body["tags"] = tags
+        if metadata is not None:
+            body["metadata"] = metadata
+        if status is not None:
+            body["status"] = status
+        data = self._client.put(f"/v1/skills/{skill_id}", body)
+        return SkillRecord.from_api(data)
+
+    def delete(self, skill_id: str) -> None:
+        self._client.delete(f"/v1/skills/{skill_id}")
+
+    def search(
+        self,
+        query: str,
+        *,
+        tags: Optional[list[str]] = None,
+        status: str = "active",
+        top_k: int = 20,
+    ) -> list[SkillSummary]:
+        body: dict[str, Any] = {
+            "query": query,
+            "tags": tags or [],
+            "status": status,
+            "topK": top_k,
+            "mode": "keyword",
+        }
+        data = self._client.post("/v1/skills/search", body)
+        return [SkillSummary.from_api(item) for item in data.get("results") or []]
+
+    def export_skill_md(self, skill_id_or_name: str) -> str:
+        record = self.get(skill_id_or_name)
+        return str(
+            self._client.get(
+                f"/v1/skills/{record.skill_id}/export",
+                params={"format": "skill-md"},
+                as_text=True,
+            )
+        )
+
+    def export_zip(self, skill_id_or_name: str) -> bytes:
+        record = self.get(skill_id_or_name)
+        return self._client.get_bytes(
+            f"/v1/skills/{record.skill_id}/export",
+            params={"format": "zip"},
+        )

exemplar_core-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[tool.poetry]
+name = "exemplar-core"
+version = "0.1.0"
+description = "Shared Exemplar REST clients for skills and memory"
+authors = ["Exemplar Dev LLC"]
+license = "LicenseRef-Proprietary"
+readme = "README.md"
+packages = [{ include = "exemplar_core" }]
+
+[tool.poetry.dependencies]
+python = ">=3.10,<3.14"
+httpx = ">=0.27.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = ">=8.0"
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]