sanctuary-dna 0.1.0__tar.gz

sanctuary_dna-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.DS_Store

sanctuary_dna-0.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: sanctuary-dna
+Version: 0.1.0
+Summary: Sanctuary DNA - Gnostic agent workflow DSL. Ariadne (threading) + Poimandres (generation) = SDNA spiral
+Project-URL: Homepage, https://github.com/sancovp/sdna
+Project-URL: Repository, https://github.com/sancovp/sdna
+Author-email: Isaac Wostrel-Rubin <isaac@sancovp.com>
+License: MIT
+Keywords: agent,anthropic,claude,composition,sdk,workflow
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: anthropic>=0.40.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# SDNA - Sanctuary DNA
+
+Gnostic agent workflow composition for Claude Agent SDK.
+
+**Ariadne** (threading) + **Poimandres** (generation) = **SDNA** spiral
+
+## Installation
+
+```bash
+pip install sdna-agent-sdk
+```
+
+## Quick Start
+
+```python
+from sdna import ariadne, human, inject_file, sdnac, sdna_flow, HermesConfig
+
+# 1. Build Ariadne thread (context prep)
+thread = ariadne('my-thread',
+    inject_file('spec.md', 'spec'),
+    human('Approve spec?', 'approval'),  # Pauses for human input
+)
+
+# 2. Create HermesConfig (the message)
+config = HermesConfig(
+    name="generator",
+    system_prompt="You are a code generator...",
+)
+
+# 3. Combine into SDNAC
+unit = sdnac('generate-code', thread, config)
+
+# 4. Execute
+result = await unit.execute({'initial': 'context'})
+```
+
+## The Trinity
+
+| Component | Role | What It Does |
+|-----------|------|--------------|
+| **Ariadne** | Threader | Context manipulation: inject, weave, dovetail, human input |
+| **Poimandres** | Divine Mind | Generation moment - takes config, runs agent, returns output |
+| **HermesConfig** | The Message | Runner configuration Ariadne sends to Poimandres |
+
+## Decision Tree: What to Build
+
+```
+Is this continuous improvement / optimization loop?
+├── YES → SDNA^F (SDNAFlowchain)
+│         Optimizer + target pairs. Meta-optimization.
+│
+└── NO → Are you composing multiple agent units in sequence?
+    ├── YES → SDNAF (SDNAFlow)
+    │         Flow of SDNACs. Sequential execution.
+    │
+    └── NO → SDNAC
+              Single unit: AriadneChain → HermesConfig → Poimandres executes
+```
+
+## Ariadne Elements
+
+```python
+from sdna import (
+    ariadne,           # Create chain
+    human,             # Human input stop step
+    inject_file,       # Inject file contents
+    inject_func,       # Inject function result
+    inject_literal,    # Inject literal value
+    inject_env,        # Inject env variable
+    weave,             # Context surgery between sessions
+)
+```
+
+## License
+
+MIT

sanctuary_dna-0.1.0/README.md

@@ -0,0 +1,76 @@
+# SDNA - Sanctuary DNA
+
+Gnostic agent workflow composition for Claude Agent SDK.
+
+**Ariadne** (threading) + **Poimandres** (generation) = **SDNA** spiral
+
+## Installation
+
+```bash
+pip install sdna-agent-sdk
+```
+
+## Quick Start
+
+```python
+from sdna import ariadne, human, inject_file, sdnac, sdna_flow, HermesConfig
+
+# 1. Build Ariadne thread (context prep)
+thread = ariadne('my-thread',
+    inject_file('spec.md', 'spec'),
+    human('Approve spec?', 'approval'),  # Pauses for human input
+)
+
+# 2. Create HermesConfig (the message)
+config = HermesConfig(
+    name="generator",
+    system_prompt="You are a code generator...",
+)
+
+# 3. Combine into SDNAC
+unit = sdnac('generate-code', thread, config)
+
+# 4. Execute
+result = await unit.execute({'initial': 'context'})
+```
+
+## The Trinity
+
+| Component | Role | What It Does |
+|-----------|------|--------------|
+| **Ariadne** | Threader | Context manipulation: inject, weave, dovetail, human input |
+| **Poimandres** | Divine Mind | Generation moment - takes config, runs agent, returns output |
+| **HermesConfig** | The Message | Runner configuration Ariadne sends to Poimandres |
+
+## Decision Tree: What to Build
+
+```
+Is this continuous improvement / optimization loop?
+├── YES → SDNA^F (SDNAFlowchain)
+│         Optimizer + target pairs. Meta-optimization.
+│
+└── NO → Are you composing multiple agent units in sequence?
+    ├── YES → SDNAF (SDNAFlow)
+    │         Flow of SDNACs. Sequential execution.
+    │
+    └── NO → SDNAC
+              Single unit: AriadneChain → HermesConfig → Poimandres executes
+```
+
+## Ariadne Elements
+
+```python
+from sdna import (
+    ariadne,           # Create chain
+    human,             # Human input stop step
+    inject_file,       # Inject file contents
+    inject_func,       # Inject function result
+    inject_literal,    # Inject literal value
+    inject_env,        # Inject env variable
+    weave,             # Context surgery between sessions
+)
+```
+
+## License
+
+MIT

sanctuary_dna-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sanctuary-dna"
+version = "0.1.0"
+description = "Sanctuary DNA - Gnostic agent workflow DSL. Ariadne (threading) + Poimandres (generation) = SDNA spiral"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "Isaac Wostrel-Rubin", email = "isaac@sancovp.com"}
+]
+keywords = ["agent", "workflow", "claude", "anthropic", "sdk", "composition"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "pydantic>=2.0",
+    "anthropic>=0.40.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+]
+
+[project.urls]
+Homepage = "https://github.com/sancovp/sdna"
+Repository = "https://github.com/sancovp/sdna"
+
+[tool.hatch.build.targets.wheel]
+packages = ["sdna"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

sanctuary_dna-0.1.0/sdna/__init__.py

@@ -0,0 +1,79 @@
+"""
+SDNA - Sanctuary DNA
+
+Gnostic agent workflow DSL for Claude Agent SDK.
+Ariadne (threading) + Poimandres (generation) = SDNA spiral.
+
+Components:
+- Ariadne: context threading (inject, weave, human input)
+- Poimandres: generation moment (execute)
+- SDNA: spiral composition (SDNAC → SDNAF → SDNA^F)
+"""
+
+from .config import HermesConfig, DovetailModel, HermesConfigInput
+from .tools import BlockedReport, parse_blocked_from_text, get_cached_reports, clear_cached_reports
+from .runner import agent_step, StepResult, StepStatus
+from .ariadne import (
+    AriadneChain, AriadneResult, AriadneStatus,
+    AriadneElement, HumanInput, InjectConfig, WeaveConfig, BrainInjectConfig,
+    ariadne, human, inject_file, inject_func, inject_literal, inject_env, weave, inject_brain,
+)
+from .brain import Brain, BrainConfig, Neuron, CognitionResult
+from .sdna import (
+    SDNAC, SDNAFlow, SDNAFlowchain,
+    SDNAResult, SDNAStatus,
+    SDNACConfig, OptimizerSDNACConfig, SDNAFlowConfig,
+    sdnac, sdna_flow,
+)
+from . import poimandres
+
+__all__ = [
+    # Config
+    "HermesConfig",
+    "DovetailModel",
+    "HermesConfigInput",
+    # Tools
+    "BlockedReport",
+    "parse_blocked_from_text",
+    "get_cached_reports",
+    "clear_cached_reports",
+    # Runner
+    "agent_step",
+    "StepResult",
+    "StepStatus",
+    # Ariadne (context threading)
+    "AriadneChain",
+    "AriadneResult",
+    "AriadneStatus",
+    "AriadneElement",
+    "HumanInput",
+    "InjectConfig",
+    "WeaveConfig",
+    "BrainInjectConfig",
+    "ariadne",
+    "human",
+    "inject_file",
+    "inject_func",
+    "inject_literal",
+    "inject_env",
+    "weave",
+    "inject_brain",
+    # Brain (neural knowledge retrieval)
+    "Brain",
+    "BrainConfig",
+    "Neuron",
+    "CognitionResult",
+    # Poimandres (generation moment)
+    "poimandres",
+    # SDNA (spiral composition)
+    "SDNAC",
+    "SDNAFlow",
+    "SDNAFlowchain",
+    "SDNAResult",
+    "SDNAStatus",
+    "SDNACConfig",
+    "OptimizerSDNACConfig",
+    "SDNAFlowConfig",
+    "sdnac",
+    "sdna_flow",
+]

sanctuary_dna-0.1.0/sdna/ariadne.py

@@ -0,0 +1,328 @@
+"""
+Ariadne - The Threader
+
+Context manipulation: inject, weave, dovetail, human input.
+Ariadne prepares the thread that guides Poimandres.
+"""
+
+from typing import Dict, Any, List, Union, Optional
+from dataclasses import dataclass, field
+from enum import Enum
+from pydantic import BaseModel, Field
+import importlib
+import os
+
+from .config import DovetailModel
+
+
+# =============================================================================
+# ARIADNE ELEMENTS
+# =============================================================================
+
+class HumanInput(BaseModel):
+    """Stop step - pause, return to human, resume with answer."""
+    prompt: str
+    input_key: str
+    choices: Optional[List[str]] = None
+
+
+class InjectConfig(BaseModel):
+    """Inject external data into context."""
+    source: str  # "file", "function", "literal", "env"
+    inject_as: str
+    path: Optional[str] = None
+    module: Optional[str] = None
+    func: Optional[str] = None
+    args: Dict[str, Any] = Field(default_factory=dict)
+    value: Optional[Any] = None
+    env_var: Optional[str] = None
+    default: Optional[str] = None
+
+    async def execute(self, context: Dict[str, Any]) -> Dict[str, Any]:
+        if self.source == "file":
+            with open(self.path, 'r') as f:
+                context[self.inject_as] = f.read()
+        elif self.source == "function":
+            mod = importlib.import_module(self.module)
+            fn = getattr(mod, self.func)
+            resolved = {
+                k: context.get(v[1:], v) if isinstance(v, str) and v.startswith("$") else v
+                for k, v in self.args.items()
+            }
+            context[self.inject_as] = fn(**resolved)
+        elif self.source == "literal":
+            context[self.inject_as] = self.value
+        elif self.source == "env":
+            context[self.inject_as] = os.environ.get(self.env_var, self.default)
+        return context
+
+
+class WeaveConfig(BaseModel):
+    """Context surgery - move message ranges between sessions."""
+    source_session: Optional[str] = None
+    target_session: Optional[str] = None
+    start_index: Optional[int] = None
+    end_index: Optional[int] = None
+    inject_as: str = "woven_context"
+
+    async def execute(self, context: Dict[str, Any]) -> Dict[str, Any]:
+        # TODO: Implement with SDK session access
+        context[self.inject_as] = {
+            "source": self.source_session,
+            "range": (self.start_index, self.end_index),
+            "_pending": True,
+        }
+        return context
+
+
+AriadneElement = Union[HumanInput, InjectConfig, WeaveConfig, DovetailModel, "BrainInjectConfig"]
+
+
+# =============================================================================
+# RESULT
+# =============================================================================
+
+class AriadneStatus(str, Enum):
+    SUCCESS = "success"
+    ERROR = "error"
+    AWAITING_INPUT = "awaiting_input"
+
+
+@dataclass
+class AriadneResult:
+    """Result of Ariadne chain execution."""
+    status: AriadneStatus
+    context: Dict[str, Any] = field(default_factory=dict)
+    error: Optional[str] = None
+    # For AWAITING_INPUT
+    pending_prompt: Optional[str] = None
+    pending_input_key: Optional[str] = None
+    pending_choices: Optional[List[str]] = None
+    resume_at: Optional[int] = None
+
+
+# =============================================================================
+# ARIADNE CHAIN
+# =============================================================================
+
+class AriadneChain:
+    """
+    Chain of context operations.
+    Prepares the thread that guides Poimandres.
+    """
+
+    def __init__(self, name: str, elements: List[AriadneElement]):
+        self.name = name
+        self.elements = elements
+
+    async def execute(
+        self,
+        context: Optional[Dict[str, Any]] = None,
+        start_at: int = 0,
+    ) -> AriadneResult:
+        ctx = dict(context) if context else {}
+
+        for i in range(start_at, len(self.elements)):
+            elem = self.elements[i]
+
+            try:
+                if isinstance(elem, HumanInput):
+                    return AriadneResult(
+                        status=AriadneStatus.AWAITING_INPUT,
+                        context=ctx,
+                        pending_prompt=elem.prompt,
+                        pending_input_key=elem.input_key,
+                        pending_choices=elem.choices,
+                        resume_at=i + 1,
+                    )
+
+                elif isinstance(elem, InjectConfig):
+                    ctx = await elem.execute(ctx)
+
+                elif isinstance(elem, WeaveConfig):
+                    ctx = await elem.execute(ctx)
+
+                elif isinstance(elem, BrainInjectConfig):
+                    ctx = await elem.execute(ctx)
+
+                elif isinstance(elem, DovetailModel):
+                    next_inputs = elem.prepare_next_inputs(ctx)
+                    ctx.update(next_inputs)
+
+            except Exception as e:
+                return AriadneResult(status=AriadneStatus.ERROR, context=ctx, error=str(e))
+
+        return AriadneResult(status=AriadneStatus.SUCCESS, context=ctx)
+
+    def __repr__(self):
+        return f"AriadneChain('{self.name}', {len(self.elements)} elements)"
+
+
+# =============================================================================
+# CONVENIENCE CONSTRUCTORS
+# =============================================================================
+
+def ariadne(name: str, *elements: AriadneElement) -> AriadneChain:
+    """
+    Create an Ariadne chain for context threading.
+
+    Args:
+        name: Chain identifier
+        *elements: HumanInput, InjectConfig, WeaveConfig, or DovetailModel
+
+    Example:
+        thread = ariadne('prep',
+            inject_file('spec.md', 'spec'),
+            human('Approve?', 'approval'),
+        )
+    """
+    return AriadneChain(name, list(elements))
+
+
+def human(prompt: str, as_key: str, choices: List[str] = None) -> HumanInput:
+    """
+    Create a human input stop step. Pauses chain, awaits input, resumes.
+
+    Args:
+        prompt: Question to show the human
+        as_key: Context key where answer is stored
+        choices: Optional list of choices to present
+
+    Example:
+        human('Which approach?', 'choice', ['A', 'B', 'C'])
+    """
+    return HumanInput(prompt=prompt, input_key=as_key, choices=choices)
+
+
+def inject_file(path: str, as_key: str) -> InjectConfig:
+    """
+    Inject file contents into context.
+
+    Args:
+        path: Path to file to read
+        as_key: Context key where contents are stored
+
+    Example:
+        inject_file('README.md', 'readme')
+    """
+    return InjectConfig(source="file", path=path, inject_as=as_key)
+
+
+def inject_func(module: str, func: str, as_key: str, **args) -> InjectConfig:
+    """
+    Inject function result into context.
+
+    Args:
+        module: Python module path (e.g., 'mypackage.utils')
+        func: Function name to call
+        as_key: Context key where result is stored
+        **args: Arguments to pass (use $key to reference context values)
+
+    Example:
+        inject_func('utils', 'get_data', 'data', id='$user_id')
+    """
+    return InjectConfig(source="function", module=module, func=func, args=args, inject_as=as_key)
+
+
+def inject_literal(value: Any, as_key: str) -> InjectConfig:
+    """
+    Inject a literal value into context.
+
+    Args:
+        value: Any value to inject
+        as_key: Context key where value is stored
+
+    Example:
+        inject_literal({'mode': 'fast'}, 'config')
+    """
+    return InjectConfig(source="literal", value=value, inject_as=as_key)
+
+
+def inject_env(env_var: str, as_key: str, default: str = None) -> InjectConfig:
+    """
+    Inject environment variable into context.
+
+    Args:
+        env_var: Environment variable name
+        as_key: Context key where value is stored
+        default: Default if env var not set
+
+    Example:
+        inject_env('API_KEY', 'api_key', default='none')
+    """
+    return InjectConfig(source="env", env_var=env_var, default=default, inject_as=as_key)
+
+
+def weave(source: str = None, start: int = None, end: int = None, as_key: str = "woven") -> WeaveConfig:
+    """
+    Weave message ranges between sessions (context surgery).
+
+    Args:
+        source: Source session ID
+        start: Start message index
+        end: End message index
+        as_key: Context key where woven content is stored
+
+    Example:
+        weave(source='session_123', start=5, end=10, as_key='prior_context')
+    """
+    return WeaveConfig(source_session=source, start_index=start, end_index=end, inject_as=as_key)
+
+
+class BrainInjectConfig(BaseModel):
+    """Inject knowledge from Brain neurons into context."""
+    brain_directory: str
+    query_key: str  # Context key containing query (or literal if starts with !)
+    inject_as: str
+    max_neurons: int = 5
+    extensions: list = Field(default_factory=lambda: [".md", ".txt", ".py"])
+
+    async def execute(self, context: Dict[str, Any]) -> Dict[str, Any]:
+        from .brain import Brain, BrainConfig
+
+        # Resolve query from context or use literal
+        if self.query_key.startswith("$"):
+            query = context.get(self.query_key[1:], "")
+        else:
+            query = self.query_key
+
+        # Create and run brain
+        brain_config = BrainConfig(
+            name="ariadne_brain",
+            directory=self.brain_directory,
+            extensions=self.extensions,
+        )
+        brain = Brain(brain_config)
+        brain.load_neurons()
+
+        # Cognize and synthesize
+        result = await brain.think(query)
+        context[self.inject_as] = result.instructions
+        context[f"{self.inject_as}_neurons"] = [
+            {"name": n.name, "relevance": n.relevance}
+            for n in result.relevant_neurons
+        ]
+        return context
+
+
+def inject_brain(directory: str, query_key: str, as_key: str, max_neurons: int = 5) -> BrainInjectConfig:
+    """
+    Inject knowledge from Brain neurons into context.
+
+    Uses Haiku to find relevant documents and synthesize instructions.
+
+    Args:
+        directory: Path to directory containing neuron files (.md, .txt, .py)
+        query_key: Context key with query (use $key) or literal query
+        as_key: Context key where synthesized instructions are stored
+        max_neurons: Max relevant neurons to use (default 5)
+
+    Example:
+        inject_brain('/docs/mcp-guides', '$user_question', 'knowledge')
+    """
+    return BrainInjectConfig(
+        brain_directory=directory,
+        query_key=query_key,
+        inject_as=as_key,
+        max_neurons=max_neurons,
+    )