neural-context-protocol 0.1.0a1__py3-none-any.whl

ncp/__init__.py

@@ -0,0 +1,35 @@
+"""Public package surface for Neural Context Protocol."""
+
+from .api import agent, configure, emit, get_context, run, stream, write_memory
+from .benchmarks import estimate_tokens, run_coding_pipeline_benchmark, run_research_pipeline_benchmark
+from .dogfood import (
+    get_live_provider_readiness,
+    load_dogfood_adapter,
+    run_adapter_continuation_dogfood_loop,
+    run_canonical_dogfood_loop,
+    run_canonical_http_dogfood_loop,
+    run_live_adapter_continuation_attempt,
+    run_repeatability_dogfood_loop,
+)
+from .version import __version__
+
+__all__ = [
+    "__version__",
+    "agent",
+    "configure",
+    "estimate_tokens",
+    "emit",
+    "get_live_provider_readiness",
+    "get_context",
+    "load_dogfood_adapter",
+    "run_adapter_continuation_dogfood_loop",
+    "run_canonical_dogfood_loop",
+    "run_canonical_http_dogfood_loop",
+    "run_live_adapter_continuation_attempt",
+    "run_repeatability_dogfood_loop",
+    "run",
+    "run_coding_pipeline_benchmark",
+    "run_research_pipeline_benchmark",
+    "stream",
+    "write_memory",
+]

ncp/adapters/__init__.py

@@ -0,0 +1,2 @@
+"""Provider adapters package."""
+

ncp/adapters/anthropic.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+from os import environ
+
+from ncp.adapters.base import BaseAdapter
+
+
+class AnthropicAdapter(BaseAdapter):
+    @property
+    def ctx_window(self) -> int:
+        return 200000
+
+    def __init__(
+        self,
+        api_key: str = "",
+        model: str = "claude-sonnet-4-20250514",
+        max_tokens: int = 4096,
+        timeout: float = 120.0,
+    ) -> None:
+        try:
+            import anthropic
+        except ImportError as err:
+            raise ImportError(
+                "anthropic is required. Install it with: pip install 'ncp-sdk[providers]'"
+            ) from err
+        self._anthropic = anthropic
+        resolved_key = api_key or environ.get("ANTHROPIC_API_KEY", "")
+        self._client = anthropic.Anthropic(
+            api_key=self._require_api_key(resolved_key, env_var="ANTHROPIC_API_KEY"),
+            timeout=timeout,
+        )
+        self._model = model
+        self._max_tokens = max_tokens
+
+    def call(self, ncp_context: str, user_turn: str) -> str:
+        msg = self._run_provider_call(
+            lambda: self._client.messages.create(
+                model=self._model,
+                max_tokens=self._max_tokens,
+                system=ncp_context,
+                messages=[{"role": "user", "content": user_turn}],
+            ),
+            provider="Anthropic",
+            timeout_types=(self._anthropic.APITimeoutError, TimeoutError),
+        )
+        texts = [b.text for b in msg.content if b.type == "text"]
+        return self._coerce_text("".join(texts), provider="Anthropic")
+
+    def stream(self, ncp_context: str, user_turn: str) -> Iterator[str]:
+        stream_ctx = self._run_provider_call(
+            lambda: self._client.messages.stream(
+                model=self._model,
+                max_tokens=self._max_tokens,
+                system=ncp_context,
+                messages=[{"role": "user", "content": user_turn}],
+            ),
+            provider="Anthropic",
+            timeout_types=(self._anthropic.APITimeoutError, TimeoutError),
+        )
+        with stream_ctx as stream:
+            for event in stream:
+                if event.type == "content_block_delta" and event.delta.type == "text_delta":
+                    yield event.delta.text

ncp/adapters/base.py

@@ -0,0 +1,76 @@
+"""Base adapter contract."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Iterator
+from typing import Callable, TypeVar
+
+
+class NCPAdapterError(RuntimeError):
+    """Base class for provider adapter failures."""
+
+
+class NCPAdapterConfigurationError(NCPAdapterError):
+    """Raised when an adapter is misconfigured before making a call."""
+
+
+class NCPAdapterTimeoutError(NCPAdapterError):
+    """Raised when a provider call times out."""
+
+
+class NCPAdapterResponseError(NCPAdapterError):
+    """Raised when a provider returns an unusable response."""
+
+
+_T = TypeVar("_T")
+
+
+class BaseAdapter(ABC):
+    """Minimal provider adapter contract for the first NCP API slice."""
+
+    @property
+    def ctx_window(self) -> int:
+        return 200000
+
+    @abstractmethod
+    def call(self, ncp_context: str, user_turn: str) -> str:
+        """Return a blocking response for one assembled context."""
+
+    def stream(self, ncp_context: str, user_turn: str) -> Iterator[str]:
+        """Yield a streamed response for one assembled context.
+
+        Tier 2 providers override only if they support streaming.
+        """
+        raise NotImplementedError(
+            f"{type(self).__name__} does not support streaming in NCP V1; use blocking call()"
+        )
+
+    def _require_api_key(self, api_key: str, *, env_var: str) -> str:
+        if api_key.strip():
+            return api_key
+        raise NCPAdapterConfigurationError(
+            f"{type(self).__name__} requires {env_var}; configure it or pass api_key explicitly"
+        )
+
+    def _coerce_text(self, value: str | None, *, provider: str) -> str:
+        text = (value or "").strip()
+        if text:
+            return text
+        raise NCPAdapterResponseError(f"{provider} returned an empty text response")
+
+    def _run_provider_call(
+        self,
+        call: Callable[[], _T],
+        *,
+        provider: str,
+        timeout_types: tuple[type[BaseException], ...] = (TimeoutError,),
+    ) -> _T:
+        try:
+            return call()
+        except NCPAdapterError:
+            raise
+        except timeout_types as exc:
+            raise NCPAdapterTimeoutError(f"{provider} timed out: {exc}") from exc
+        except Exception as exc:
+            raise NCPAdapterError(f"{provider} call failed: {exc}") from exc

ncp/adapters/cohere.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from os import environ
+
+from ncp.adapters.base import BaseAdapter
+
+
+class CohereAdapter(BaseAdapter):
+    @property
+    def ctx_window(self) -> int:
+        return 128000
+
+    def __init__(
+        self,
+        api_key: str = "",
+        model: str = "command-a-03-2025",
+        max_tokens: int = 4096,
+        timeout: float = 120.0,
+    ) -> None:
+        try:
+            import cohere
+        except ImportError as err:
+            raise ImportError(
+                "cohere is required. Install it with: pip install 'ncp-sdk[providers]'"
+            ) from err
+        resolved_key = api_key or environ.get("COHERE_API_KEY", "")
+        self._client = cohere.Client(
+            api_key=self._require_api_key(resolved_key, env_var="COHERE_API_KEY"),
+            timeout=timeout,
+        )
+        self._model = model
+        self._max_tokens = max_tokens
+
+    def call(self, ncp_context: str, user_turn: str) -> str:
+        from cohere.types import ChatMessage
+
+        resp = self._run_provider_call(
+            lambda: self._client.chat(
+                model=self._model,
+                max_tokens=self._max_tokens,
+                preamble=ncp_context,
+                messages=[
+                    ChatMessage(role="user", message=user_turn),
+                ],
+            ),
+            provider="Cohere",
+        )
+        return self._coerce_text(resp.text, provider="Cohere")

ncp/adapters/gemini.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from os import environ
+
+from ncp.adapters.base import BaseAdapter
+
+
+class GeminiAdapter(BaseAdapter):
+    @property
+    def ctx_window(self) -> int:
+        return 1000000
+
+    def __init__(
+        self,
+        api_key: str = "",
+        model: str = "gemini-2.0-flash",
+        timeout: float = 120.0,
+    ) -> None:
+        try:
+            import google.generativeai as genai
+        except ImportError as err:
+            raise ImportError(
+                "google-generativeai is required. Install it with: pip install 'ncp-sdk[providers]'"
+            ) from err
+        resolved_key = api_key or environ.get("GOOGLE_API_KEY", "")
+        genai.configure(api_key=self._require_api_key(resolved_key, env_var="GOOGLE_API_KEY"))
+        self._model = genai.GenerativeModel(model)
+        self._timeout = timeout
+
+    def call(self, ncp_context: str, user_turn: str) -> str:
+        prompt = f"{ncp_context}\n\n{user_turn}"
+        resp = self._run_provider_call(
+            lambda: self._model.generate_content(
+                prompt,
+                request_options={"timeout": self._timeout},
+            ),
+            provider="Gemini",
+        )
+        return self._coerce_text(resp.text, provider="Gemini")

ncp/adapters/local.py

@@ -0,0 +1,27 @@
+"""Local deterministic adapter for early dogfood and testing."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+from ncp.adapters.base import BaseAdapter
+
+
+class LocalAdapter(BaseAdapter):
+    """A simple blocking/streaming adapter for the SQLite-first local path."""
+
+    @property
+    def ctx_window(self) -> int:
+        return 200000
+
+    def call(self, ncp_context: str, user_turn: str) -> str:
+        return (
+            "local_adapter_response\n"
+            f"user_turn:{user_turn}\n"
+            f"context_chars:{len(ncp_context)}"
+        )
+
+    def stream(self, ncp_context: str, user_turn: str) -> Iterator[str]:
+        response = self.call(ncp_context, user_turn)
+        for line in response.splitlines(keepends=True):
+            yield line

ncp/adapters/mistral.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from os import environ
+
+from ncp.adapters.base import BaseAdapter
+
+
+class MistralAdapter(BaseAdapter):
+    @property
+    def ctx_window(self) -> int:
+        return 128000
+
+    def __init__(
+        self,
+        api_key: str = "",
+        model: str = "mistral-large-latest",
+        max_tokens: int = 4096,
+        timeout: float = 120.0,
+    ) -> None:
+        try:
+            from mistralai.client import Mistral
+        except ImportError as err:
+            raise ImportError(
+                "mistralai is required. Install it with: pip install 'ncp-sdk[providers]'"
+            ) from err
+        resolved_key = api_key or environ.get("MISTRAL_API_KEY", "")
+        self._client = Mistral(
+            api_key=self._require_api_key(resolved_key, env_var="MISTRAL_API_KEY"),
+            timeout_ms=int(timeout * 1000),
+        )
+        self._model = model
+        self._max_tokens = max_tokens
+
+    def call(self, ncp_context: str, user_turn: str) -> str:
+        resp = self._run_provider_call(
+            lambda: self._client.chat.complete(
+                model=self._model,
+                max_tokens=self._max_tokens,
+                messages=[
+                    {"role": "system", "content": ncp_context},
+                    {"role": "user", "content": user_turn},
+                ],
+            ),
+            provider="Mistral",
+        )
+        return self._coerce_text(resp.choices[0].message.content, provider="Mistral")

ncp/adapters/ollama.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from os import environ
+
+from ncp.adapters.base import BaseAdapter
+
+_DEFAULT_OLLAMA_BASE_URL = "http://localhost:11434/v1"
+
+
+class OllamaAdapter(BaseAdapter):
+    @property
+    def ctx_window(self) -> int:
+        return 8192
+
+    def __init__(
+        self,
+        base_url: str = "",
+        model: str = "llama3.1",
+        max_tokens: int = 4096,
+        timeout: float = 120.0,
+        max_retries: int = 2,
+    ) -> None:
+        try:
+            import openai
+        except ImportError as err:
+            raise ImportError(
+                "openai is required. Install it with: pip install 'ncp-sdk[providers]'"
+            ) from err
+        self._openai = openai
+        resolved_base_url = base_url or environ.get("OLLAMA_BASE_URL", _DEFAULT_OLLAMA_BASE_URL)
+        self._client = openai.OpenAI(
+            base_url=resolved_base_url,
+            api_key="ollama",
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        self._model = model
+        self._max_tokens = max_tokens
+
+    def call(self, ncp_context: str, user_turn: str) -> str:
+        resp = self._run_provider_call(
+            lambda: self._client.chat.completions.create(
+                model=self._model,
+                max_tokens=self._max_tokens,
+                messages=[
+                    {"role": "system", "content": ncp_context},
+                    {"role": "user", "content": user_turn},
+                ],
+            ),
+            provider="Ollama",
+            timeout_types=(self._openai.APITimeoutError, TimeoutError),
+        )
+        return self._coerce_text(resp.choices[0].message.content, provider="Ollama")

ncp/adapters/openai.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+from os import environ
+
+from ncp.adapters.base import BaseAdapter
+
+_MODEL_WINDOWS: dict[str, int] = {
+    "gpt-4o": 128000,
+    "gpt-4o-mini": 128000,
+    "o1": 200000,
+    "o3-mini": 200000,
+    "gpt-4.1": 1047576,
+    "gpt-4.1-mini": 1047576,
+    "gpt-4.1-nano": 1047576,
+}
+
+
+class OpenAIAdapter(BaseAdapter):
+    def __init__(
+        self,
+        api_key: str = "",
+        model: str = "gpt-4o",
+        max_tokens: int = 4096,
+        timeout: float = 120.0,
+        max_retries: int = 2,
+        base_url: str | None = None,
+    ) -> None:
+        try:
+            import openai
+        except ImportError as err:
+            raise ImportError(
+                "openai is required. Install it with: pip install 'ncp-sdk[providers]'"
+            ) from err
+        self._openai = openai
+        resolved_key = api_key or environ.get("OPENAI_API_KEY", "")
+        kwargs: dict = {
+            "api_key": self._require_api_key(resolved_key, env_var="OPENAI_API_KEY"),
+            "timeout": timeout,
+            "max_retries": max_retries,
+        }
+        if base_url is not None:
+            kwargs["base_url"] = base_url
+        self._client = openai.OpenAI(**kwargs)
+        self._model = model
+        self._max_tokens = max_tokens
+
+    @property
+    def ctx_window(self) -> int:
+        return _MODEL_WINDOWS.get(self._model, 128000)
+
+    def call(self, ncp_context: str, user_turn: str) -> str:
+        resp = self._run_provider_call(
+            lambda: self._client.chat.completions.create(
+                model=self._model,
+                max_tokens=self._max_tokens,
+                messages=[
+                    {"role": "system", "content": ncp_context},
+                    {"role": "user", "content": user_turn},
+                ],
+                stream=False,
+            ),
+            provider="OpenAI",
+            timeout_types=(self._openai.APITimeoutError, TimeoutError),
+        )
+        return self._coerce_text(resp.choices[0].message.content, provider="OpenAI")
+
+    def stream(self, ncp_context: str, user_turn: str) -> Iterator[str]:
+        stream = self._run_provider_call(
+            lambda: self._client.chat.completions.create(
+                model=self._model,
+                max_tokens=self._max_tokens,
+                messages=[
+                    {"role": "system", "content": ncp_context},
+                    {"role": "user", "content": user_turn},
+                ],
+                stream=True,
+            ),
+            provider="OpenAI",
+            timeout_types=(self._openai.APITimeoutError, TimeoutError),
+        )
+        for chunk in stream:
+            if chunk.choices and (delta := chunk.choices[0].delta.content):
+                yield delta

ncp/api.py

@@ -0,0 +1,210 @@
+"""Public API helpers for the SQLite-first NCP runtime."""
+
+from __future__ import annotations
+
+from pathlib import Path
+import time
+
+from ncp.adapters.base import BaseAdapter
+from ncp.adapters.local import LocalAdapter
+from ncp.assembler import Assembler
+from ncp.config import NCPConfig, load_config
+from ncp.stores.sqlite import SQLiteStore
+from ncp.types import BudgetContext, ConsciousBlock, NCPResponse, SubconsciousChunk, Whisper
+
+_CONFIG: NCPConfig | None = None
+
+
+def configure(
+    *,
+    path: str | Path | None = None,
+    cwd: str | Path | None = None,
+    env: dict[str, str] | None = None,
+) -> NCPConfig:
+    """Load and cache the active NCP configuration."""
+
+    global _CONFIG
+    _CONFIG = load_config(path=path, cwd=cwd, env=env)
+    return _CONFIG
+
+
+def agent(
+    *,
+    id: str,
+    role: str,
+    owns: list[str] | None = None,
+    must_not: list[str] | None = None,
+    task: str = "idle",
+    slot: str = "unassigned",
+    intent: str = "maintain_context",
+    **overrides: object,
+) -> ConsciousBlock:
+    """Create a conscious-block template through the public API."""
+
+    payload = {
+        "agent_id": id,
+        "role": role,
+        "owns": owns or [],
+        "must_not": must_not or [],
+        "task": task,
+        "slot": slot,
+        "intent": intent,
+        **overrides,
+    }
+    return ConsciousBlock(**payload)
+
+
+def get_context(
+    *,
+    agent: ConsciousBlock,
+    budget: BudgetContext | None = None,
+    query_text: str | None = None,
+    store: SQLiteStore | None = None,
+    config: NCPConfig | None = None,
+) -> str:
+    """Assemble raw pidgin context for one agent turn."""
+
+    resolved_config = config or _CONFIG or configure(cwd=Path.cwd())
+    resolved_store = store or SQLiteStore(resolved_config.store_path)
+    assembler = Assembler(store=resolved_store)
+    return assembler.assemble(
+        conscious=agent,
+        budget=budget or BudgetContext(),
+        query_text=query_text,
+    ).context
+
+
+def write_memory(
+    chunk: SubconsciousChunk,
+    *,
+    store: SQLiteStore | None = None,
+    config: NCPConfig | None = None,
+) -> bool:
+    """Persist one chunk through the public API."""
+
+    resolved_config = config or _CONFIG or configure(cwd=Path.cwd())
+    resolved_store = store or SQLiteStore(resolved_config.store_path)
+    return resolved_store.write(chunk)
+
+
+def emit(
+    whisper: Whisper,
+    *,
+    store: SQLiteStore | None = None,
+    config: NCPConfig | None = None,
+) -> None:
+    """Persist one whisper through the public API."""
+
+    resolved_config = config or _CONFIG or configure(cwd=Path.cwd())
+    resolved_store = store or SQLiteStore(resolved_config.store_path)
+    resolved_store.emit_whisper(whisper)
+
+
+def run(
+    *,
+    agent: ConsciousBlock,
+    turn: str,
+    adapter: BaseAdapter | None = None,
+    budget: BudgetContext | None = None,
+    query_text: str | None = None,
+    store: SQLiteStore | None = None,
+    config: NCPConfig | None = None,
+) -> NCPResponse:
+    """Run one blocking local-runtime call through an adapter."""
+
+    resolved_config = config or _CONFIG or configure(cwd=Path.cwd())
+    resolved_store = store or SQLiteStore(resolved_config.store_path)
+    resolved_budget = budget or BudgetContext()
+    resolved_adapter = adapter or LocalAdapter()
+    assembler = Assembler(store=resolved_store)
+
+    start = time.perf_counter()
+    assembly = assembler.assemble(
+        conscious=agent,
+        budget=resolved_budget,
+        query_text=query_text or turn,
+        ctx_window=resolved_adapter.ctx_window,
+    )
+    content = resolved_adapter.call(assembly.context, turn)
+    response = _build_response(
+        agent=agent,
+        adapter=resolved_adapter,
+        context=assembly.context,
+        turn=turn,
+        content=content,
+        start=start,
+    )
+    assembler.post_turn(
+        conscious=agent,
+        response=response,
+        result_summary=content.splitlines()[0] if content else "",
+        result_full=content,
+    )
+    return response
+
+
+def stream(
+    *,
+    agent: ConsciousBlock,
+    turn: str,
+    adapter: BaseAdapter | None = None,
+    budget: BudgetContext | None = None,
+    query_text: str | None = None,
+    store: SQLiteStore | None = None,
+    config: NCPConfig | None = None,
+):
+    """Yield a streamed response through the adapter."""
+
+    resolved_config = config or _CONFIG or configure(cwd=Path.cwd())
+    resolved_store = store or SQLiteStore(resolved_config.store_path)
+    resolved_budget = budget or BudgetContext()
+    resolved_adapter = adapter or LocalAdapter()
+    assembler = Assembler(store=resolved_store)
+    assembly = assembler.assemble(
+        conscious=agent,
+        budget=resolved_budget,
+        query_text=query_text or turn,
+        ctx_window=resolved_adapter.ctx_window,
+    )
+    start = time.perf_counter()
+    chunks: list[str] = []
+    for chunk in resolved_adapter.stream(assembly.context, turn):
+        chunks.append(chunk)
+        yield chunk
+
+    content = "".join(chunks)
+    response = _build_response(
+        agent=agent,
+        adapter=resolved_adapter,
+        context=assembly.context,
+        turn=turn,
+        content=content,
+        start=start,
+    )
+    assembler.post_turn(
+        conscious=agent,
+        response=response,
+        result_summary=content.splitlines()[0] if content else "",
+        result_full=content,
+    )
+
+
+def _build_response(
+    *,
+    agent: ConsciousBlock,
+    adapter: BaseAdapter,
+    context: str,
+    turn: str,
+    content: str,
+    start: float,
+) -> NCPResponse:
+    return NCPResponse(
+        content=content,
+        input_tokens=len((context + "\n" + turn).split()),
+        output_tokens=len(content.split()),
+        cost_usd=0.0,
+        model=adapter.__class__.__name__.lower(),
+        pipeline_id=agent.pipeline_id,
+        turn_id=f"turn_{int(time.time() * 1000)}",
+        latency_ms=int((time.perf_counter() - start) * 1000),
+    )