openconstruct 0.1.0__tar.gz

openconstruct-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 SuperInstance
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

openconstruct-0.1.0/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: openconstruct
+Version: 0.1.0
+Summary: Python thin client for OpenConstruct - SuperInstance ecosystem onboarding
+Author-email: SuperInstance <contact@superinstance.dev>
+Project-URL: Homepage, https://github.com/SuperInstance/openconstruct-python
+Project-URL: Repository, https://github.com/SuperInstance/openconstruct-python
+Project-URL: Issues, https://github.com/SuperInstance/openconstruct-python/issues
+Keywords: openconstruct,agent,onboarding,superinstance
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Dynamic: license-file
+
+# OpenConstruct Python — Thin Client for Agent Onboarding
+
+Python client for [OpenConstruct](https://github.com/SuperInstance/OpenConstruct). Onboard agents into the SuperInstance ecosystem in under 10 lines.
+
+## What This Gives You
+
+- **5-phase onboarding** — `start()` → `declare_agent()` → `select_modules()` → `choose_interface()` → `generate_config()`
+- **Module registry** — domain-filtered catalog of available modules
+- **Pip-installable** — `pip install openconstruct`
+- **Zero runtime dependencies** — pure Python, no native extensions
+
+## Quick Start
+
+```python
+from openconstruct import OpenConstructClient, AgentIdentity
+
+client = OpenConstructClient()
+client.start()
+
+identity = AgentIdentity(
+    name="my-agent",
+    model="claude-4",
+    capabilities=["code_generation", "web_search", "file_ops"],
+    tools=["exec", "read", "write"]
+)
+client.declare_agent(identity)
+
+modules = client.list_modules(domain="math")
+client.select_modules(["spectral-graph-core", "plato-room"])
+client.choose_interface(["cli", "api"])
+
+config = client.generate_config()
+print(config)
+```
+
+## Installation
+
+```bash
+pip install openconstruct
+```
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## How It Fits
+
+One of the [polyglot OpenConstruct bindings](https://github.com/SuperInstance/OpenConstruct). Used by [openconstruct-jupyter](https://github.com/SuperInstance/openconstruct-jupyter) for notebook integration. See [openconstruct-examples](https://github.com/SuperInstance/openconstruct-examples) for a Python onboarding walkthrough.
+
+## License
+
+MIT

openconstruct-0.1.0/README.md

@@ -0,0 +1,55 @@
+# OpenConstruct Python — Thin Client for Agent Onboarding
+
+Python client for [OpenConstruct](https://github.com/SuperInstance/OpenConstruct). Onboard agents into the SuperInstance ecosystem in under 10 lines.
+
+## What This Gives You
+
+- **5-phase onboarding** — `start()` → `declare_agent()` → `select_modules()` → `choose_interface()` → `generate_config()`
+- **Module registry** — domain-filtered catalog of available modules
+- **Pip-installable** — `pip install openconstruct`
+- **Zero runtime dependencies** — pure Python, no native extensions
+
+## Quick Start
+
+```python
+from openconstruct import OpenConstructClient, AgentIdentity
+
+client = OpenConstructClient()
+client.start()
+
+identity = AgentIdentity(
+    name="my-agent",
+    model="claude-4",
+    capabilities=["code_generation", "web_search", "file_ops"],
+    tools=["exec", "read", "write"]
+)
+client.declare_agent(identity)
+
+modules = client.list_modules(domain="math")
+client.select_modules(["spectral-graph-core", "plato-room"])
+client.choose_interface(["cli", "api"])
+
+config = client.generate_config()
+print(config)
+```
+
+## Installation
+
+```bash
+pip install openconstruct
+```
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## How It Fits
+
+One of the [polyglot OpenConstruct bindings](https://github.com/SuperInstance/OpenConstruct). Used by [openconstruct-jupyter](https://github.com/SuperInstance/openconstruct-jupyter) for notebook integration. See [openconstruct-examples](https://github.com/SuperInstance/openconstruct-examples) for a Python onboarding walkthrough.
+
+## License
+
+MIT

openconstruct-0.1.0/openconstruct/__init__.py

@@ -0,0 +1,15 @@
+"""OpenConstruct - Python thin client for SuperInstance ecosystem onboarding."""
+
+from openconstruct.client import OpenConstructClient
+from openconstruct.registry import ModuleRegistry
+from openconstruct.types import AgentIdentity, ModuleInfo, OnboardingConfig
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "OpenConstructClient",
+    "ModuleRegistry",
+    "AgentIdentity",
+    "ModuleInfo",
+    "OnboardingConfig",
+]

openconstruct-0.1.0/openconstruct/client.py

@@ -0,0 +1,165 @@
+"""Main OpenConstruct client for agent onboarding."""
+
+import uuid
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from openconstruct.registry import ModuleRegistry
+from openconstruct.types import AgentIdentity, ModuleInfo, OnboardingConfig
+
+
+class OpenConstructClient:
+    """Main client class for OpenConstruct onboarding."""
+
+    def __init__(self):
+        """Initialize the OpenConstruct client."""
+        self._session_id: Optional[str] = None
+        self._started = False
+        self._identity: Optional[AgentIdentity] = None
+        self._selected_modules: List[ModuleInfo] = []
+        self._selected_interfaces: List[str] = []
+        self._registry = ModuleRegistry()
+
+    def start(self) -> str:
+        """
+        Start a new onboarding session.
+
+        Returns:
+            Session ID for the new session
+        """
+        self._session_id = str(uuid.uuid4())
+        self._started = True
+        self._identity = None
+        self._selected_modules = []
+        self._selected_interfaces = []
+        return self._session_id
+
+    def declare_agent(self, identity: AgentIdentity) -> None:
+        """
+        Declare agent identity.
+
+        Args:
+            identity: AgentIdentity object with agent details
+
+        Raises:
+            RuntimeError: If session not started
+        """
+        if not self._started:
+            raise RuntimeError("Session not started. Call start() first.")
+        self._identity = identity
+
+    def list_modules(self, domain: Optional[str] = None) -> List[Dict[str, Any]]:
+        """
+        List available modules, optionally filtered by domain.
+
+        Args:
+            domain: Optional domain filter
+
+        Returns:
+            List of module dictionaries
+        """
+        modules = self._registry.list_modules(domain)
+        return [m.to_dict() for m in modules]
+
+    def select_modules(self, module_ids: List[str]) -> None:
+        """
+        Select modules for the agent.
+
+        Args:
+            module_ids: List of module IDs to select
+
+        Raises:
+            RuntimeError: If session not started
+            ValueError: If any module ID is invalid
+        """
+        if not self._started:
+            raise RuntimeError("Session not started. Call start() first.")
+
+        for module_id in module_ids:
+            if not self._registry.module_exists(module_id):
+                raise ValueError(f"Module '{module_id}' not found")
+
+        self._selected_modules = [
+            self._registry.get_module(mid) for mid in module_ids if self._registry.get_module(mid)
+        ]
+
+    def choose_interface(self, interfaces: List[str]) -> None:
+        """
+        Choose interface types for the agent.
+
+        Args:
+            interfaces: List of interface types (e.g., ["cli", "api"])
+
+        Raises:
+            RuntimeError: If session not started
+        """
+        if not self._started:
+            raise RuntimeError("Session not started. Call start() first.")
+        self._selected_interfaces = interfaces
+
+    def generate_config(self) -> Dict[str, Any]:
+        """
+        Generate the final onboarding configuration.
+
+        Returns:
+            Dictionary containing the complete onboarding configuration
+
+        Raises:
+            RuntimeError: If session not started or identity not declared
+        """
+        if not self._started:
+            raise RuntimeError("Session not started. Call start() first.")
+
+        if not self._identity:
+            raise RuntimeError("Agent identity not declared. Call declare_agent() first.")
+
+        config = OnboardingConfig(
+            session_id=self._session_id,
+            agent=self._identity.to_dict(),
+            selected_modules=[m.to_dict() for m in self._selected_modules],
+            selected_interfaces=self._selected_interfaces,
+            workspace=self._build_workspace_config(),
+            created_at=datetime.utcnow().isoformat() + "Z",
+        )
+
+        return config.to_dict()
+
+    def _build_workspace_config(self) -> Dict[str, Any]:
+        """
+        Build workspace configuration based on selections.
+
+        Returns:
+            Dictionary with workspace configuration
+        """
+        workspace_config = {
+            "agent_name": self._identity.name if self._identity else "",
+            "modules": [m.id for m in self._selected_modules],
+            "interfaces": self._selected_interfaces,
+            "environment_variables": {
+                "OPENCONSTRUCT_SESSION_ID": self._session_id or "",
+            },
+        }
+
+        # Add module-specific configurations
+        for module in self._selected_modules:
+            workspace_config[f"module_{module.id}_config"] = {
+                "version": module.version,
+                "enabled": True,
+            }
+
+        return workspace_config
+
+    @property
+    def session_id(self) -> Optional[str]:
+        """Get the current session ID."""
+        return self._session_id
+
+    @property
+    def is_started(self) -> bool:
+        """Check if a session is started."""
+        return self._started
+
+    @property
+    def identity(self) -> Optional[AgentIdentity]:
+        """Get the declared agent identity."""
+        return self._identity

openconstruct-0.1.0/openconstruct/registry.py

@@ -0,0 +1,112 @@
+"""Module registry for browsing available modules."""
+
+import uuid
+from typing import List, Optional
+
+from openconstruct.types import ModuleInfo
+
+
+class ModuleRegistry:
+    """Registry of available OpenConstruct modules."""
+
+    def __init__(self):
+        """Initialize the module registry with sample modules."""
+        self._modules = self._initialize_modules()
+
+    def _initialize_modules(self) -> dict:
+        """Initialize with sample modules."""
+        return {
+            "spectral-graph-core": ModuleInfo(
+                id="spectral-graph-core",
+                name="Spectral Graph Core",
+                domain="math",
+                description="Core spectral graph theory operations and algorithms",
+                version="1.0.0",
+                dependencies=[],
+                requires_agent_capabilities=["computation"],
+            ),
+            "plato-room": ModuleInfo(
+                id="plato-room",
+                name="Plato Room",
+                domain="collaboration",
+                description="Virtual collaboration space for agent discussions",
+                version="0.9.0",
+                dependencies=["spectral-graph-core"],
+                requires_agent_capabilities=["communication"],
+            ),
+            "tensor-flow": ModuleInfo(
+                id="tensor-flow",
+                name="Tensor Flow Operations",
+                domain="math",
+                description="Advanced tensor manipulation and operations",
+                version="2.1.0",
+                dependencies=[],
+                requires_agent_capabilities=["computation"],
+            ),
+            "memory-bank": ModuleInfo(
+                id="memory-bank",
+                name="Memory Bank",
+                domain="storage",
+                description="Persistent memory storage for agents",
+                version="1.2.0",
+                dependencies=[],
+                requires_agent_capabilities=["persistence"],
+            ),
+            "code-analyzer": ModuleInfo(
+                id="code-analyzer",
+                name="Code Analyzer",
+                domain="analysis",
+                description="Static code analysis and quality checks",
+                version="0.8.0",
+                dependencies=[],
+                requires_agent_capabilities=["code_generation"],
+            ),
+            "web-crawler": ModuleInfo(
+                id="web-crawler",
+                name="Web Crawler",
+                domain="web",
+                description="Efficient web crawling and data extraction",
+                version="1.5.0",
+                dependencies=[],
+                requires_agent_capabilities=["web_search"],
+            ),
+        }
+
+    def list_modules(self, domain: Optional[str] = None) -> List[ModuleInfo]:
+        """
+        List all available modules, optionally filtered by domain.
+
+        Args:
+            domain: Optional domain filter (e.g., "math", "collaboration")
+
+        Returns:
+            List of ModuleInfo objects
+        """
+        modules = list(self._modules.values())
+        if domain:
+            modules = [m for m in modules if m.domain == domain]
+        return modules
+
+    def get_module(self, module_id: str) -> Optional[ModuleInfo]:
+        """
+        Get a specific module by ID.
+
+        Args:
+            module_id: The module identifier
+
+        Returns:
+            ModuleInfo if found, None otherwise
+        """
+        return self._modules.get(module_id)
+
+    def module_exists(self, module_id: str) -> bool:
+        """
+        Check if a module exists.
+
+        Args:
+            module_id: The module identifier
+
+        Returns:
+            True if module exists, False otherwise
+        """
+        return module_id in self._modules

openconstruct-0.1.0/openconstruct/types.py

@@ -0,0 +1,75 @@
+"""Data types for OpenConstruct."""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class AgentIdentity:
+    """Agent self-declaration for onboarding."""
+
+    name: str
+    model: str
+    capabilities: List[str] = field(default_factory=list)
+    tools: List[str] = field(default_factory=list)
+    description: Optional[str] = None
+    version: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert identity to dictionary."""
+        return {
+            "name": self.name,
+            "model": self.model,
+            "capabilities": self.capabilities,
+            "tools": self.tools,
+            "description": self.description,
+            "version": self.version,
+        }
+
+
+@dataclass
+class ModuleInfo:
+    """Information about an available module."""
+
+    id: str
+    name: str
+    domain: str
+    description: str
+    version: str
+    dependencies: List[str] = field(default_factory=list)
+    requires_agent_capabilities: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert module info to dictionary."""
+        return {
+            "id": self.id,
+            "name": self.name,
+            "domain": self.domain,
+            "description": self.description,
+            "version": self.version,
+            "dependencies": self.dependencies,
+            "requires_agent_capabilities": self.requires_agent_capabilities,
+        }
+
+
+@dataclass
+class OnboardingConfig:
+    """Final onboarding configuration output."""
+
+    session_id: str
+    agent: Dict[str, Any]
+    selected_modules: List[Dict[str, Any]]
+    selected_interfaces: List[str]
+    workspace: Dict[str, Any] = field(default_factory=dict)
+    created_at: str = ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert config to dictionary."""
+        return {
+            "session_id": self.session_id,
+            "agent": self.agent,
+            "selected_modules": self.selected_modules,
+            "selected_interfaces": self.selected_interfaces,
+            "workspace": self.workspace,
+            "created_at": self.created_at,
+        }

openconstruct-0.1.0/openconstruct.egg-info/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: openconstruct
+Version: 0.1.0
+Summary: Python thin client for OpenConstruct - SuperInstance ecosystem onboarding
+Author-email: SuperInstance <contact@superinstance.dev>
+Project-URL: Homepage, https://github.com/SuperInstance/openconstruct-python
+Project-URL: Repository, https://github.com/SuperInstance/openconstruct-python
+Project-URL: Issues, https://github.com/SuperInstance/openconstruct-python/issues
+Keywords: openconstruct,agent,onboarding,superinstance
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Dynamic: license-file
+
+# OpenConstruct Python — Thin Client for Agent Onboarding
+
+Python client for [OpenConstruct](https://github.com/SuperInstance/OpenConstruct). Onboard agents into the SuperInstance ecosystem in under 10 lines.
+
+## What This Gives You
+
+- **5-phase onboarding** — `start()` → `declare_agent()` → `select_modules()` → `choose_interface()` → `generate_config()`
+- **Module registry** — domain-filtered catalog of available modules
+- **Pip-installable** — `pip install openconstruct`
+- **Zero runtime dependencies** — pure Python, no native extensions
+
+## Quick Start
+
+```python
+from openconstruct import OpenConstructClient, AgentIdentity
+
+client = OpenConstructClient()
+client.start()
+
+identity = AgentIdentity(
+    name="my-agent",
+    model="claude-4",
+    capabilities=["code_generation", "web_search", "file_ops"],
+    tools=["exec", "read", "write"]
+)
+client.declare_agent(identity)
+
+modules = client.list_modules(domain="math")
+client.select_modules(["spectral-graph-core", "plato-room"])
+client.choose_interface(["cli", "api"])
+
+config = client.generate_config()
+print(config)
+```
+
+## Installation
+
+```bash
+pip install openconstruct
+```
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## How It Fits
+
+One of the [polyglot OpenConstruct bindings](https://github.com/SuperInstance/OpenConstruct). Used by [openconstruct-jupyter](https://github.com/SuperInstance/openconstruct-jupyter) for notebook integration. See [openconstruct-examples](https://github.com/SuperInstance/openconstruct-examples) for a Python onboarding walkthrough.
+
+## License
+
+MIT

openconstruct-0.1.0/openconstruct.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+openconstruct/__init__.py
+openconstruct/client.py
+openconstruct/registry.py
+openconstruct/types.py
+openconstruct.egg-info/PKG-INFO
+openconstruct.egg-info/SOURCES.txt
+openconstruct.egg-info/dependency_links.txt
+openconstruct.egg-info/requires.txt
+openconstruct.egg-info/top_level.txt
+tests/test_client.py

openconstruct-0.1.0/openconstruct.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

openconstruct-0.1.0/openconstruct.egg-info/requires.txt

@@ -0,0 +1,4 @@
+
+[dev]
+pytest>=7.0
+pytest-cov>=4.0

openconstruct-0.1.0/openconstruct.egg-info/top_level.txt

@@ -0,0 +1 @@
+openconstruct

openconstruct-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openconstruct"
+version = "0.1.0"
+description = "Python thin client for OpenConstruct - SuperInstance ecosystem onboarding"
+readme = "README.md"
+requires-python = ">=3.8"
+authors = [
+    {name = "SuperInstance", email = "contact@superinstance.dev"}
+]
+keywords = ["openconstruct", "agent", "onboarding", "superinstance"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "pytest-cov>=4.0"]
+
+[project.urls]
+Homepage = "https://github.com/SuperInstance/openconstruct-python"
+Repository = "https://github.com/SuperInstance/openconstruct-python"
+Issues = "https://github.com/SuperInstance/openconstruct-python/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["openconstruct*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]

openconstruct-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

openconstruct-0.1.0/tests/test_client.py

@@ -0,0 +1,247 @@
+"""Tests for OpenConstructClient."""
+
+import pytest
+
+from openconstruct import OpenConstructClient, AgentIdentity
+
+
+class TestClientStart:
+    """Tests for client start functionality."""
+
+    def test_start_creates_session(self):
+        """Test that start() creates a session with a valid ID."""
+        client = OpenConstructClient()
+        session_id = client.start()
+
+        assert isinstance(session_id, str)
+        assert len(session_id) > 0
+        assert client.is_started
+        assert client.session_id == session_id
+
+
+class TestClientDeclareAgent:
+    """Tests for agent declaration."""
+
+    def test_declare_agent_stores_identity(self):
+        """Test that declare_agent() stores the identity."""
+        client = OpenConstructClient()
+        client.start()
+
+        identity = AgentIdentity(
+            name="test-agent",
+            model="gpt-4",
+            capabilities=["test"],
+            tools=["exec"]
+        )
+        client.declare_agent(identity)
+
+        assert client.identity is not None
+        assert client.identity.name == "test-agent"
+        assert client.identity.model == "gpt-4"
+
+    def test_declare_agent_fails_without_start(self):
+        """Test that declare_agent() raises error without start()."""
+        client = OpenConstructClient()
+        identity = AgentIdentity(name="test", model="gpt-4")
+
+        with pytest.raises(RuntimeError, match="Session not started"):
+            client.declare_agent(identity)
+
+
+class TestClientListModules:
+    """Tests for module listing."""
+
+    def test_list_modules_returns_list(self):
+        """Test that list_modules() returns a list."""
+        client = OpenConstructClient()
+        client.start()
+
+        modules = client.list_modules()
+
+        assert isinstance(modules, list)
+        assert len(modules) > 0
+        assert all(isinstance(m, dict) for m in modules)
+
+    def test_list_modules_filters_by_domain(self):
+        """Test that list_modules(domain=X) filters correctly."""
+        client = OpenConstructClient()
+        client.start()
+
+        math_modules = client.list_modules(domain="math")
+        all_modules = client.list_modules()
+
+        assert len(math_modules) < len(all_modules)
+        assert all(m["domain"] == "math" for m in math_modules)
+
+    def test_list_modules_with_unknown_domain(self):
+        """Test that list_modules() with unknown domain returns empty list."""
+        client = OpenConstructClient()
+        client.start()
+
+        modules = client.list_modules(domain="nonexistent")
+
+        assert isinstance(modules, list)
+        assert len(modules) == 0
+
+
+class TestClientSelectModules:
+    """Tests for module selection."""
+
+    def test_select_modules_stores_selection(self):
+        """Test that select_modules() stores the selection."""
+        client = OpenConstructClient()
+        client.start()
+        client.declare_agent(AgentIdentity(name="test", model="gpt-4"))
+
+        client.select_modules(["spectral-graph-core", "plato-room"])
+
+        config = client.generate_config()
+        assert len(config["selected_modules"]) == 2
+
+    def test_select_modules_fails_without_start(self):
+        """Test that select_modules() raises error without start()."""
+        client = OpenConstructClient()
+
+        with pytest.raises(RuntimeError, match="Session not started"):
+            client.select_modules(["spectral-graph-core"])
+
+    def test_select_modules_fails_with_invalid_module(self):
+        """Test that select_modules() raises error with invalid module."""
+        client = OpenConstructClient()
+        client.start()
+
+        with pytest.raises(ValueError, match="not found"):
+            client.select_modules(["nonexistent-module"])
+
+    def test_select_modules_with_mixed_valid_invalid(self):
+        """Test that select_modules() fails with mix of valid and invalid modules."""
+        client = OpenConstructClient()
+        client.start()
+
+        with pytest.raises(ValueError, match="not found"):
+            client.select_modules(["spectral-graph-core", "invalid-module"])
+
+
+class TestClientChooseInterface:
+    """Tests for interface selection."""
+
+    def test_choose_interface_stores_choice(self):
+        """Test that choose_interface() stores the choice."""
+        client = OpenConstructClient()
+        client.start()
+        client.declare_agent(AgentIdentity(name="test", model="gpt-4"))
+
+        client.choose_interface(["cli", "api"])
+
+        config = client.generate_config()
+        assert config["selected_interfaces"] == ["cli", "api"]
+
+    def test_choose_interface_fails_without_start(self):
+        """Test that choose_interface() raises error without start()."""
+        client = OpenConstructClient()
+
+        with pytest.raises(RuntimeError, match="Session not started"):
+            client.choose_interface(["cli"])
+
+
+class TestClientGenerateConfig:
+    """Tests for configuration generation."""
+
+    def test_generate_config_produces_dict(self):
+        """Test that generate_config() produces a dictionary."""
+        client = OpenConstructClient()
+        client.start()
+        client.declare_agent(AgentIdentity(name="test", model="gpt-4"))
+
+        config = client.generate_config()
+
+        assert isinstance(config, dict)
+
+    def test_generate_config_has_required_fields(self):
+        """Test that generate_config() has all required fields."""
+        client = OpenConstructClient()
+        client.start()
+        client.declare_agent(AgentIdentity(name="test", model="gpt-4"))
+
+        config = client.generate_config()
+
+        assert "session_id" in config
+        assert "agent" in config
+        assert "selected_modules" in config
+        assert "selected_interfaces" in config
+        assert "workspace" in config
+        assert "created_at" in config
+
+    def test_generate_config_fails_without_start(self):
+        """Test that generate_config() raises error without start()."""
+        client = OpenConstructClient()
+
+        with pytest.raises(RuntimeError, match="Session not started"):
+            client.generate_config()
+
+    def test_generate_config_fails_without_identity(self):
+        """Test that generate_config() raises error without identity."""
+        client = OpenConstructClient()
+        client.start()
+
+        with pytest.raises(RuntimeError, match="Agent identity not declared"):
+            client.generate_config()
+
+
+class TestClientFullLifecycle:
+    """Tests for the complete client lifecycle."""
+
+    def test_full_lifecycle(self):
+        """Test the complete onboarding flow."""
+        client = OpenConstructClient()
+
+        # Start session
+        session_id = client.start()
+        assert session_id is not None
+
+        # Declare agent
+        identity = AgentIdentity(
+            name="my-agent",
+            model="claude-4",
+            capabilities=["code_generation", "web_search", "file_ops"],
+            tools=["exec", "read", "write"]
+        )
+        client.declare_agent(identity)
+        assert client.identity.name == "my-agent"
+
+        # List and select modules
+        modules = client.list_modules(domain="math")
+        assert len(modules) > 0
+
+        client.select_modules(["spectral-graph-core", "plato-room"])
+
+        # Choose interfaces
+        client.choose_interface(["cli", "api"])
+
+        # Generate config
+        config = client.generate_config()
+
+        # Verify structure
+        assert config["session_id"] == session_id
+        assert config["agent"]["name"] == "my-agent"
+        assert len(config["selected_modules"]) == 2
+        assert config["selected_interfaces"] == ["cli", "api"]
+        assert "workspace" in config
+        assert config["created_at"] != ""
+
+    def test_lifecycle_with_multiple_sessions(self):
+        """Test that starting a new session resets state."""
+        client = OpenConstructClient()
+
+        # First session
+        client.start()
+        client.declare_agent(AgentIdentity(name="agent1", model="gpt-4"))
+        session1_id = client.session_id
+
+        # Second session
+        client.start()
+        client.declare_agent(AgentIdentity(name="agent2", model="claude-4"))
+        session2_id = client.session_id
+
+        assert session1_id != session2_id
+        assert client.identity.name == "agent2"