isomer-labs 0.1.0__tar.gz

isomer_labs-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Pixi environments
+.pixi/
+
+# Python caches
+__pycache__/
+*.py[cod]
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+dist/
+
+# Disposable local work
+tmp/
+.env
+web/ui/node_modules/
+
+.claude/
+.claude
+.codex/
+.kimi-code/
+.git/
+.agents/skills
+# Isolated implementation worktrees
+.imsight-arts/impl-branches/

isomer_labs-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CodeGandee
+
+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.

isomer_labs-0.1.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: isomer-labs
+Version: 0.1.0
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: click<9,>=8.4.1
+Requires-Dist: fastapi<0.140,>=0.139.0
+Requires-Dist: jinja2<4,>=3.1.6
+Requires-Dist: jsonschema<5,>=4.26.0
+Requires-Dist: pydantic<3,>=2.12
+Requires-Dist: sqlalchemy<3,>=2.0
+Requires-Dist: tomlkit<0.16,>=0.15.0
+Requires-Dist: uvicorn[standard]<0.39,>=0.38.0

isomer_labs-0.1.0/README.md

@@ -0,0 +1,44 @@
+# isomer-labs
+
+Isomer Labs is a private research platform that uses multi-agent teams as a research engine while a human operator sets goals and steers work at critical steps.
+
+The same base capabilities can form different research teams, workflows, and feedback loops. One Research Topic may need discovery, synthesis, and review agents; another may need planning, data analysis, and report-writing agents. The platform makes those structures easy to create, run, observe, and improve.
+
+## Documentation
+
+- [Getting Started](docs/getting-started.md) — initialize a Project, validate it, prepare a Topic Workspace, and create an Agent Team Instance record.
+- [isomer-cli Reference](docs/isomer-cli.md) — every public command, its side effects, and common examples.
+- [Documentation Index](docs/index.md) — all docs pages and navigation.
+
+## Quick Sampler
+
+```bash
+pixi install
+pixi run isomer-cli project init
+pixi run isomer-cli project topics create my-topic --statement "Investigate the concrete research question." --set-default
+pixi run isomer-cli --print-json project validate
+pixi run isomer-cli --print-json project runtime init --topic my-topic
+pixi run isomer-cli --print-json project runtime prepare --topic my-topic
+pixi run isomer-cli --print-json project team-instances create \
+  --topic my-topic \
+  --topic-agent-team-profile my-topic-deepsci \
+  --id ati-my-topic-deepsci
+```
+
+After a Houmao-backed Agent Team Instance is launched or adopted, manual handoff rounds use one root JSON switch for every command:
+
+```bash
+pixi run isomer-cli --print-json project handoffs dispatch \
+  --topic my-topic \
+  --agent-team-instance ati-my-topic-deepsci \
+  --target-agent-instance ati-my-topic-deepsci-deepsci-org-experimenter \
+  --message "Draft the first experiment handoff."
+pixi run isomer-cli --print-json project handoffs observe <handoff-id> --topic my-topic --source mail
+pixi run isomer-cli --print-json project handoffs normalize <handoff-id> --topic my-topic --status accepted --signal-observation <signal-observation-id> --output-artifact artifact:my-topic:first-handoff
+```
+
+For Houmao-backed launch paths, handoff behavior, and live-gated validation, see [docs/workflows.md](docs/workflows.md) and [docs/houmao-adapter.md](docs/houmao-adapter.md).
+
+## Status
+
+Initial sketch. Structure and scope are expected to change. See [Assumptions and Roadmap](docs/assumptions-and-roadmap.md) for current milestone status and future work.

isomer_labs-0.1.0/pyproject.toml

@@ -0,0 +1,74 @@
+[project]
+dependencies = [
+  "click>=8.4.1,<9",
+  "fastapi>=0.139.0,<0.140",
+  "jinja2>=3.1.6,<4",
+  "jsonschema>=4.26.0,<5",
+  "pydantic>=2.12,<3",
+  "sqlalchemy>=2.0,<3",
+  "tomlkit>=0.15.0,<0.16",
+  "uvicorn[standard]>=0.38.0,<0.39",
+]
+name = "isomer-labs"
+requires-python = ">= 3.11"
+version = "0.1.0"
+
+[project.scripts]
+isomer-cli = "isomer_labs.cli:main"
+
+[build-system]
+build-backend = "hatchling.build"
+requires = ["hatchling"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/isomer_labs"]
+
+[tool.hatch.build.targets.sdist]
+only-include = [
+  "LICENSE",
+  "README.md",
+  "pyproject.toml",
+  "src/isomer_labs",
+]
+
+[tool.pixi.workspace]
+channels = ["conda-forge"]
+platforms = ["linux-64", "linux-aarch64", "osx-arm64"]
+
+[tool.pixi.pypi-dependencies]
+isomer_labs = { path = ".", editable = true }
+scipy = ">=1.17.1,<2"
+mdutils = ">=1.8.1,<2"
+ruff = ">=0.15.16,<0.16"
+mkdocs-material = ">=9.7.6,<10"
+mypy = ">=2.1.0,<3"
+attrs = ">=26.1.0,<27"
+omegaconf = ">=2.3.1,<3"
+imageio = ">=2.37.3,<3"
+pytest = ">=8.0.0,<9"
+pytest-xdist = ">=3.6.0,<4"
+
+[tool.pixi.tasks]
+lint = "ruff check ."
+typecheck = "mypy src"
+test = "python -m pytest -n $(python -c 'import os; print(max(1, os.cpu_count() // 2))') tests/unit"
+validate-research-skills = "python scripts/validate_research_paradigm_skillset.py skillset/research-paradigm"
+validate-operator-skills = "python scripts/validate_skillsets.py --scope operator"
+validate-service-skills = "python scripts/validate_skillsets.py --scope service"
+validate-skills = "python scripts/validate_skillsets.py --scope all"
+docs-validate = "python scripts/validate_docs.py"
+
+[tool.ruff]
+extend-exclude = [
+  "teams/lfeng-team",
+  "skillset/research-paradigm/deepsci/*/org/src/**",
+  "src/isomer_labs/assets/system_skills/**",
+]
+
+[tool.mypy]
+exclude = [
+  "^src/isomer_labs/assets/system_skills/",
+]
+
+[tool.pixi.dependencies]
+python = "3.11.*"

isomer_labs-0.1.0/src/isomer_labs/__init__.py

@@ -0,0 +1 @@
+"""Isomer Labs research platform experiments."""

isomer_labs-0.1.0/src/isomer_labs/__main__.py

@@ -0,0 +1,8 @@
+"""Module entrypoint for `python -m isomer_labs`."""
+
+from __future__ import annotations
+
+from isomer_labs.cli import main
+
+
+raise SystemExit(main())

isomer_labs-0.1.0/src/isomer_labs/artifact_formats/__init__.py

@@ -0,0 +1,47 @@
+"""Public artifact-format processing APIs."""
+
+from isomer_labs.artifact_formats.models import (
+    ArtifactFormatProfile,
+    ArtifactFormatRef,
+    ArtifactFormatResolution,
+    RenderResult,
+    ValidationResult,
+    digest_bytes,
+    digest_json,
+    parse_format_ref,
+    validate_format_ref,
+)
+from isomer_labs.artifact_formats.registry import (
+    ArtifactFormatProvider,
+    ArtifactFormatRegistry,
+    StaticArtifactFormatProvider,
+    default_registry,
+    register_provider,
+)
+from isomer_labs.artifact_formats.processing import ArtifactFormatResolver, render_artifact, validate_payload
+from isomer_labs.artifact_formats.workspace_provider import (
+    WorkspaceRuntimeArtifactFormatProvider,
+    register_custom_artifact_format,
+)
+
+__all__ = [
+    "ArtifactFormatProfile",
+    "ArtifactFormatProvider",
+    "ArtifactFormatRef",
+    "ArtifactFormatRegistry",
+    "ArtifactFormatResolution",
+    "ArtifactFormatResolver",
+    "RenderResult",
+    "StaticArtifactFormatProvider",
+    "ValidationResult",
+    "WorkspaceRuntimeArtifactFormatProvider",
+    "default_registry",
+    "digest_bytes",
+    "digest_json",
+    "parse_format_ref",
+    "register_provider",
+    "register_custom_artifact_format",
+    "render_artifact",
+    "validate_format_ref",
+    "validate_payload",
+]

isomer_labs-0.1.0/src/isomer_labs/artifact_formats/models.py

@@ -0,0 +1,346 @@
+"""Models for generic Artifact Format processing."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import hashlib
+import json
+from pathlib import Path
+import re
+from typing import Any, Literal, Mapping
+
+from isomer_labs.core.diagnostics import Diagnostic
+
+
+FORMAT_REF_ORIGINS = ("isomer", "custom")
+FORMAT_REF_SEGMENT_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
+SourceKind = Literal["provider_asset", "runtime_registration", "plain_file", "file_snapshot"]
+
+
+@dataclass(frozen=True)
+class ArtifactFormatRef:
+    """Origin-prefixed Artifact Format ref."""
+
+    origin: Literal["isomer", "custom"]
+    parts: tuple[str, ...]
+
+    @property
+    def text(self) -> str:
+        return f"{self.origin}:{'/'.join(self.parts)}"
+
+    @property
+    def owner_slug(self) -> str:
+        return self.parts[0]
+
+    def __str__(self) -> str:
+        return self.text
+
+
+@dataclass(frozen=True)
+class ArtifactFormatProfile:
+    """Declarative content expectations for one Artifact format."""
+
+    ref: str
+    schema_ref: str
+    templates: dict[str, str] = field(default_factory=dict)
+    media_type: str | None = None
+    schema_version: str | None = None
+    compatibility_version: str | None = None
+    status: str | None = None
+    validation_hints: dict[str, object] = field(default_factory=dict)
+    renderer_hints: dict[str, object] = field(default_factory=dict)
+    metadata: dict[str, object] = field(default_factory=dict)
+
+    @classmethod
+    def from_mapping(cls, ref: str, raw: Mapping[str, Any]) -> tuple["ArtifactFormatProfile" | None, list[Diagnostic]]:
+        diagnostics = validate_format_ref(ref, field="profile_ref")
+        schema_ref = raw.get("schema_ref")
+        if not isinstance(schema_ref, str) or not schema_ref.strip():
+            diagnostics.append(
+                artifact_format_diagnostic(
+                    "ISO200",
+                    "error",
+                    "Artifact Format Profile",
+                    "Artifact Format Profile requires a non-empty schema_ref.",
+                    field="schema_ref",
+                )
+            )
+            return None, diagnostics
+        diagnostics.extend(validate_format_ref(schema_ref, field="schema_ref"))
+        templates_raw = raw.get("templates", {})
+        templates: dict[str, str] = {}
+        if not isinstance(templates_raw, Mapping):
+            diagnostics.append(
+                artifact_format_diagnostic(
+                    "ISO200",
+                    "error",
+                    "Artifact Format Profile",
+                    "Artifact Format Profile templates must be an object keyed by output format.",
+                    field="templates",
+                )
+            )
+        else:
+            for output_format, template_ref in templates_raw.items():
+                if not isinstance(template_ref, str) or not template_ref.strip():
+                    diagnostics.append(
+                        artifact_format_diagnostic(
+                            "ISO200",
+                            "error",
+                            "Artifact Format Profile",
+                            "Artifact Format Profile template refs must be non-empty strings.",
+                            field=f"templates.{output_format}",
+                        )
+                    )
+                    continue
+                diagnostics.extend(validate_format_ref(template_ref, field=f"templates.{output_format}"))
+                templates[str(output_format)] = template_ref
+        if any(diagnostic.is_error for diagnostic in diagnostics):
+            return None, diagnostics
+        return (
+            cls(
+                ref=ref,
+                schema_ref=schema_ref,
+                templates=templates,
+                media_type=_optional_string(raw.get("media_type")),
+                schema_version=_optional_string(raw.get("schema_version")),
+                compatibility_version=_optional_string(raw.get("compatibility_version")),
+                status=_optional_string(raw.get("status")),
+                validation_hints=_object_dict(raw.get("validation_hints")),
+                renderer_hints=_object_dict(raw.get("renderer_hints")),
+                metadata=_object_dict(raw.get("metadata")),
+            ),
+            diagnostics,
+        )
+
+    def to_json(self) -> dict[str, object]:
+        data: dict[str, object] = {
+            "ref": self.ref,
+            "schema_ref": self.schema_ref,
+            "templates": dict(sorted(self.templates.items())),
+        }
+        for key, value in (
+            ("media_type", self.media_type),
+            ("schema_version", self.schema_version),
+            ("compatibility_version", self.compatibility_version),
+            ("status", self.status),
+        ):
+            if value is not None:
+                data[key] = value
+        if self.validation_hints:
+            data["validation_hints"] = self.validation_hints
+        if self.renderer_hints:
+            data["renderer_hints"] = self.renderer_hints
+        if self.metadata:
+            data["metadata"] = self.metadata
+        return data
+
+
+@dataclass(frozen=True)
+class ArtifactFormatResolution:
+    """Resolved provider asset or path-backed material."""
+
+    ref: str
+    kind: Literal["profile", "schema", "template"]
+    source_kind: SourceKind
+    content: str
+    digest: str
+    path: Path | None = None
+    media_type: str | None = None
+    diagnostics: list[Diagnostic] = field(default_factory=list)
+
+    def to_json(self) -> dict[str, object]:
+        data: dict[str, object] = {
+            "ref": self.ref,
+            "kind": self.kind,
+            "source_kind": self.source_kind,
+            "digest": self.digest,
+        }
+        if self.path is not None:
+            data["path"] = str(self.path)
+        if self.media_type is not None:
+            data["media_type"] = self.media_type
+        return data
+
+
+@dataclass(frozen=True)
+class ValidationResult:
+    """Deterministic JSON Schema validation result."""
+
+    ok: bool
+    status: Literal["valid", "invalid", "error"]
+    payload_digest: str
+    schema_ref: str | None
+    schema_digest: str | None
+    schema_source_kind: SourceKind | None
+    diagnostics: list[Diagnostic] = field(default_factory=list)
+    profile_ref: str | None = None
+    schema_version: str | None = None
+
+    def to_json(self) -> dict[str, object]:
+        data: dict[str, object] = {
+            "ok": self.ok,
+            "status": self.status,
+            "payload_digest": self.payload_digest,
+            "schema_ref": self.schema_ref,
+            "schema_digest": self.schema_digest,
+            "schema_source_kind": self.schema_source_kind,
+            "diagnostics": [diagnostic.to_json() for diagnostic in self.diagnostics],
+        }
+        if self.profile_ref is not None:
+            data["format_profile_ref"] = self.profile_ref
+        if self.schema_version is not None:
+            data["schema_version"] = self.schema_version
+        return data
+
+
+@dataclass(frozen=True)
+class RenderResult:
+    """Deterministic Jinja2 render result."""
+
+    ok: bool
+    status: Literal["rendered", "not_requested", "error"]
+    payload_digest: str
+    template_ref: str | None
+    template_digest: str | None
+    template_source_kind: SourceKind | None
+    content: str | None
+    diagnostics: list[Diagnostic] = field(default_factory=list)
+    profile_ref: str | None = None
+    schema_ref: str | None = None
+    schema_digest: str | None = None
+    schema_source_kind: SourceKind | None = None
+    output_format: str | None = None
+
+    def to_json(self, *, include_content: bool = True) -> dict[str, object]:
+        data: dict[str, object] = {
+            "ok": self.ok,
+            "status": self.status,
+            "payload_digest": self.payload_digest,
+            "template_ref": self.template_ref,
+            "template_digest": self.template_digest,
+            "template_source_kind": self.template_source_kind,
+            "diagnostics": [diagnostic.to_json() for diagnostic in self.diagnostics],
+        }
+        if self.profile_ref is not None:
+            data["format_profile_ref"] = self.profile_ref
+        if self.schema_ref is not None:
+            data["schema_ref"] = self.schema_ref
+        if self.schema_digest is not None:
+            data["schema_digest"] = self.schema_digest
+        if self.schema_source_kind is not None:
+            data["schema_source_kind"] = self.schema_source_kind
+        if self.output_format is not None:
+            data["format"] = self.output_format
+        if include_content and self.content is not None:
+            data["content"] = self.content
+        return data
+
+
+def parse_format_ref(value: str) -> ArtifactFormatRef:
+    """Parse a canonical Artifact Format ref or raise ValueError."""
+
+    diagnostics = validate_format_ref(value)
+    if diagnostics:
+        raise ValueError(diagnostics[0].message)
+    origin, path = value.split(":", 1)
+    return ArtifactFormatRef(origin=origin, parts=tuple(path.split("/")))  # type: ignore[arg-type]
+
+
+def validate_format_ref(value: str | None, *, field: str = "format_ref") -> list[Diagnostic]:
+    """Return deterministic diagnostics for a canonical Artifact Format ref."""
+
+    raw = str(value or "")
+    if not raw.strip():
+        return [
+            artifact_format_diagnostic(
+                "ISO200",
+                "error",
+                "Artifact Format Ref",
+                "Artifact Format ref is required.",
+                field=field,
+            )
+        ]
+    if ":" not in raw:
+        return [
+            artifact_format_diagnostic(
+                "ISO200",
+                "error",
+                "Artifact Format Ref",
+                "Artifact Format ref must include an origin prefix such as isomer: or custom:.",
+                field=field,
+            )
+        ]
+    origin, path = raw.split(":", 1)
+    if origin not in FORMAT_REF_ORIGINS:
+        return [
+            artifact_format_diagnostic(
+                "ISO200",
+                "error",
+                "Artifact Format Ref",
+                "Artifact Format ref origin must be isomer or custom.",
+                field=field,
+            )
+        ]
+    parts = path.split("/")
+    if len(parts) < 3:
+        return [
+            artifact_format_diagnostic(
+                "ISO200",
+                "error",
+                "Artifact Format Ref",
+                "Artifact Format ref path must include owner slug, primary group, and name segments.",
+                field=field,
+            )
+        ]
+    invalid_parts = [part for part in parts if part in {"", ".", ".."} or FORMAT_REF_SEGMENT_RE.fullmatch(part) is None]
+    if invalid_parts:
+        return [
+            artifact_format_diagnostic(
+                "ISO200",
+                "error",
+                "Artifact Format Ref",
+                f"Artifact Format ref contains invalid path segment(s): {', '.join(invalid_parts)}.",
+                field=field,
+            )
+        ]
+    return []
+
+
+def digest_bytes(content: bytes) -> str:
+    return "sha256:" + hashlib.sha256(content).hexdigest()
+
+
+def digest_json(value: object) -> str:
+    encoded = json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+    return digest_bytes(encoded)
+
+
+def artifact_format_diagnostic(
+    code: str,
+    severity: Literal["error", "warning"],
+    concept: str,
+    message: str,
+    *,
+    field: str | None = None,
+    path: Path | None = None,
+    hint: str | None = None,
+) -> Diagnostic:
+    return Diagnostic(
+        code=code,
+        severity=severity,
+        concept=concept,
+        message=message,
+        field=field,
+        path=path,
+        hint=hint,
+    )
+
+
+def _optional_string(value: object) -> str | None:
+    return value if isinstance(value, str) and value.strip() else None
+
+
+def _object_dict(value: object) -> dict[str, object]:
+    if not isinstance(value, Mapping):
+        return {}
+    return {str(key): item for key, item in value.items()}