contexture-mcp 1.0.0__py3-none-any.whl

contexture/__init__.py

@@ -0,0 +1,94 @@
+"""Contexture — one Controller framework for agent and human Views.
+
+An application declares its roles, skills and tools once against this object
+model. Contexture can publish that declaration through a native MCP server for
+agents and explicit REST routes for human-facing dashboards.
+
+It does not run an agent loop, choose tools, or talk to a model. Those belong
+to the runtime that connects.
+
+The package is layered, and the layering is the architecture:
+
+    contexture.core.model          the kernel: what a capability is, where it
+                                   hangs, and the five calls an agent makes
+    contexture.core.mcp_interface  what each MCP primitive carries; still no SDK
+    contexture.server              compilation and the native MCP Host adapter
+    contexture.web                 the explicit REST/ASGI Host adapter
+
+Each layer may import the ones below it and never the reverse. This facade
+exports what a business developer *declares* with, and nothing the framework
+*runs* with: importing it loads neither the forest, nor the five entry points,
+nor `contexture.server`, nor the SDK, so a project that only models context
+pays for only that.
+"""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .application import Contexture as Contexture
+
+from .core import (
+    Channels,
+    ContextureError,
+    DeclarationError,
+    DuplicateNameError,
+    ModelValidationError,
+    NodeNotFoundError,
+    Principal,
+    PostProcess,
+    PreProcess,
+    Role,
+    Skill,
+    Tool,
+    binding_instruction,
+    current_graph,
+    current_principal,
+    current_telemetry,
+)
+from .core.constants import PACKAGE_VERSION as __version__
+
+# The two planes a declaration writes on arrive through one import, because
+# which of them a thing belongs to is a modelling decision and not a question
+# about this package's directories. `Prompt` and `Resource` are *constructed*
+# where the three above are *subclassed*; that difference is stated in their
+# own docstrings and enforced when a subclass is attempted, not spelled out in
+# an import path a reader has to decode.
+#
+# It costs nothing to put them here: `core.mcp_interface` stands only on the
+# shared ground, so importing this facade still loads no disclosure layer and
+# no SDK.
+from .core.mcp_interface import Prompt, Resource
+
+
+def __getattr__(name: str) -> object:
+    """Resolve the application facade without pulling it into ``core`` imports."""
+
+    if name != "Contexture":
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    from .application import Contexture
+
+    globals()[name] = Contexture
+    return Contexture
+
+__all__ = [
+    "Channels",
+    "Contexture",
+    "ContextureError",
+    "DeclarationError",
+    "DuplicateNameError",
+    "ModelValidationError",
+    "NodeNotFoundError",
+    "Principal",
+    "Prompt",
+    "PostProcess",
+    "PreProcess",
+    "Resource",
+    "Role",
+    "Skill",
+    "Tool",
+    "__version__",
+    "binding_instruction",
+    "current_graph",
+    "current_principal",
+    "current_telemetry",
+]

contexture/__init__.pyi

@@ -0,0 +1,50 @@
+"""Stable authoring API for Contexture applications.
+
+Use this namespace for business declarations.  ``contexture.server`` is the
+advanced hosting namespace; ``contexture.core`` is implementation detail.
+"""
+
+from .application import Contexture as Contexture
+from .core.emphasis import binding_instruction as binding_instruction
+from .core.errors import ContextureError as ContextureError
+from .core.errors import DeclarationError as DeclarationError
+from .core.errors import DuplicateNameError as DuplicateNameError
+from .core.errors import ModelValidationError as ModelValidationError
+from .core.errors import NodeNotFoundError as NodeNotFoundError
+from .core.mcp_interface import Prompt as Prompt
+from .core.mcp_interface import Resource as Resource
+from .core.model.channels import Channels as Channels
+from .core.model.graph_context import current_graph as current_graph
+from .core.model.role import PostProcess as PostProcess
+from .core.model.role import PreProcess as PreProcess
+from .core.model.role import Role as Role
+from .core.model.skill import Skill as Skill
+from .core.model.telemetry import current_telemetry as current_telemetry
+from .core.model.tool import Tool as Tool
+from .core.principal import Principal as Principal
+from .core.principal import current_principal as current_principal
+
+__version__: str
+
+__all__ = [
+    "Channels",
+    "Contexture",
+    "ContextureError",
+    "DeclarationError",
+    "DuplicateNameError",
+    "ModelValidationError",
+    "NodeNotFoundError",
+    "Principal",
+    "Prompt",
+    "PostProcess",
+    "PreProcess",
+    "Resource",
+    "Role",
+    "Skill",
+    "Tool",
+    "__version__",
+    "binding_instruction",
+    "current_graph",
+    "current_principal",
+    "current_telemetry",
+]

contexture/application.py

@@ -0,0 +1,106 @@
+"""The lazy declaration a business project gives to Contexture.
+
+``Contexture`` is deliberately only a specification.  It records the classes
+that make up one application; it does not construct a Role, open Channels,
+compile an Index, or import the MCP SDK.  The server runner consumes this
+object later, once for each build.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Sequence, TypeAlias
+
+from .core.errors import ModelValidationError
+from .core.mcp_interface import Prompt, Resource
+from .core.model import Channels, Role, Skill, Tool
+
+
+RootFactory: TypeAlias = type[Role] | type[Skill] | type[Tool]
+
+
+@dataclass(slots=True, frozen=True, kw_only=True)
+class Contexture:
+    """One application declaration.
+
+    A project exports exactly one instance:
+
+    ::
+
+        app = Contexture(name="hello", roots=(Hello,))
+
+    A command tree that only a person should enter is declared separately but
+    compiled into the same canonical Index::
+
+        app = Contexture(
+            name="hello",
+            roots=(Hello,),
+            prompt_roots=(Commands,),
+            prompts=(RunCommand,),
+        )
+
+    The values are classes, never constructed nodes.  Importing this module or
+    creating ``app`` is therefore safe in a CLI, a test collector, and an IDE.
+    ``contexture.server.compile_application`` is the first operation that
+    builds the declared forest.
+    """
+
+    name: str
+    roots: Sequence[RootFactory]
+    #: Complete root trees owned by MCP's user-controlled Prompt plane. They
+    #: remain addressable by Prompt and ``goto``, but are absent from
+    #: ``contexture_discover``, server routing instructions, and model opens.
+    prompt_roots: Sequence[RootFactory] = ()
+    channels: type[Channels] | None = None
+    prompts: Sequence[type[Prompt]] = ()
+    resources: Sequence[type[Resource]] = ()
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.name, str) or not self.name.strip():
+            raise ModelValidationError("A Contexture application needs a non-empty `name`.")
+
+        roots = tuple(self.roots)
+        if not roots:
+            raise ModelValidationError(
+                "A Contexture application needs at least one root Role, Skill, or Tool."
+            )
+        for root in roots:
+            self._require_factory(root, (Role, Skill, Tool), "roots")
+
+        prompt_roots = tuple(self.prompt_roots)
+        for root in prompt_roots:
+            self._require_factory(root, (Role, Skill, Tool), "prompt_roots")
+
+        if self.channels is not None:
+            self._require_factory(self.channels, (Channels,), "channels")
+
+        prompts = tuple(self.prompts)
+        for prompt in prompts:
+            self._require_factory(prompt, (Prompt,), "prompts")
+
+        resources = tuple(self.resources)
+        for resource in resources:
+            self._require_factory(resource, (Resource,), "resources")
+
+        object.__setattr__(self, "name", self.name.strip())
+        object.__setattr__(self, "roots", roots)
+        object.__setattr__(self, "prompt_roots", prompt_roots)
+        object.__setattr__(self, "prompts", prompts)
+        object.__setattr__(self, "resources", resources)
+
+    @staticmethod
+    def _require_factory(
+        value: object,
+        kinds: tuple[type[object], ...],
+        field: str,
+    ) -> None:
+        if isinstance(value, type) and issubclass(value, kinds):
+            return
+        expected = " or ".join(kind.__name__ for kind in kinds)
+        raise ModelValidationError(
+            f"`{field}` contains {value!r}; name a {expected} class, not an "
+            "already-built object. A declaration stays lazy until it is compiled."
+        )
+
+
+__all__ = ["Contexture", "RootFactory"]

contexture/cli/__init__.py

@@ -0,0 +1,59 @@
+"""The `contexture` command: scaffold a project, then serve it.
+
+A business project written against this framework contains declarations and
+nothing else. It has no entry point, no `main()`, and no console script of its
+own, because the framework ships the runner:
+
+    contexture new my-context      # write the project
+    contexture list                # what would be served
+    contexture serve               # serve it over MCP
+
+Three modules, because three clocks. `scaffold` moves when the project
+template does, `project` when the packaging ecosystem does, and `main` when the
+commands do — the same reason `server` is six modules rather than one file.
+`usage` is the shared ground beneath them.
+
+This facade is what a test or an embedder names. It is eager rather than lazy:
+unlike `contexture` and `contexture.core`, nothing here is expensive and there
+is no SDK behind any of it — `main` defers that import to the two commands
+that need one, so `new` and `list` still run in an environment without it.
+"""
+
+from __future__ import annotations
+
+from .main import build_parser, main
+from .project import (
+    CONFIG_TABLE,
+    DEMO_APP,
+    DEMO_PUBLISH,
+    DEMO_TARGET,
+    ProjectConfig,
+    find_project,
+    load_application,
+    load_roots,
+    load_published,
+    resolve_target,
+)
+from .scaffold import TEMPLATES, Names, available_templates, new_project, render_file
+from .usage import UsageError
+
+__all__ = [
+    "CONFIG_TABLE",
+    "DEMO_PUBLISH",
+    "DEMO_APP",
+    "DEMO_TARGET",
+    "Names",
+    "ProjectConfig",
+    "TEMPLATES",
+    "UsageError",
+    "available_templates",
+    "build_parser",
+    "find_project",
+    "load_application",
+    "load_roots",
+    "load_published",
+    "main",
+    "new_project",
+    "render_file",
+    "resolve_target",
+]

contexture/cli/__main__.py

@@ -0,0 +1,12 @@
+"""`python -m contexture.cli`, which the tests use and a developer may.
+
+A package needs this where a module got it for free from
+`if __name__ == "__main__"`. The console script named in `pyproject.toml`
+reaches `main` directly and never comes through here.
+"""
+
+from __future__ import annotations
+
+from .main import main
+
+raise SystemExit(main())