krons 0.1.1__tar.gz → 0.2.1__tar.gz

{krons-0.1.1 → krons-0.2.1}/.gitignore

@@ -205,3 +205,5 @@ cython_debug/
 marimo/_static/
 marimo/_lsp/
 __marimo__/
+
+*.DS_Store

{krons-0.1.1 → krons-0.2.1}/CLAUDE.md

@@ -7,7 +7,8 @@
 - **Spec/Operable**: Type-safe field definitions with validation, defaults, and DB metadata
 - **Node**: Polymorphic content containers with DB serialization
 - **Services**: Unified service interfaces (iModel, KronService) with hooks and rate limiting
-- **Enforcement**: Policy evaluation and action handlers with typed I/O
+- **Work**: Declarative workflow orchestration with Report/Worker pattern
+- **Rules**: Validation rules and enforcement
 
 ## Architecture
 
@@ -17,10 +18,11 @@ krons/
 ├── specs/          # Spec definitions, Operable composition, adapters
 │   ├── catalog/    # Pre-built specs (Content, Audit, Common, Enforcement)
 │   └── adapters/   # Pydantic, SQL DDL, Dataclass adapters
+├── work/           # Workflow orchestration (Report, Worker, Form, Phrase)
 ├── services/       # Service backends, iModel, hooks, rate limiting
-├── enforcement/    # Policy protocols, KronService, action decorators
+├── operations/     # Operation builders, context, registry
+├── rules/          # Validation rules, registry, common validators
 ├── types/          # Base types, sentinels, DB types (FK, Vector)
-├── operations/     # Operation builders and registry
 ├── protocols.py    # Runtime-checkable protocols with @implements
 └── utils/          # Fuzzy matching, SQL utilities, helpers
 ```
@@ -192,6 +194,109 @@ fk_meta = extract_kron_db_meta(field_info, metas="FK")
 vec_meta = extract_kron_db_meta(field_info, metas="Vector")
 ```
 
+### 7. Work (Workflow Orchestration)
+
+Two complementary patterns at different abstraction levels:
+
+**Report** (artifact state) - Declarative workflow definition:
+
+```python
+from krons.work import Report
+
+class HiringBriefReport(Report):
+    """Multi-step workflow with typed outputs as class attributes."""
+
+    # Typed output fields
+    role_classification: RoleClassification | None = None
+    strategic_context: StrategicContext | None = None
+    executive_summary: ExecutiveSummary | None = None
+
+    # Overall contract
+    assignment: str = "job_input, market_context -> executive_summary"
+
+    # Form assignments with branch/resource hints
+    # DSL: "branch: inputs -> outputs | resource"
+    form_assignments: list[str] = [
+        # Same branch = sequential execution
+        "classifier: job_input -> role_classification | api:fast",
+        "classifier: role_classification -> extracted_skills | api:fast",
+
+        # Different branches = parallel execution
+        "strategist: job_input, role_classification -> strategic_context | api:synthesis",
+        "writer: strategic_context -> executive_summary | api:reasoning",
+    ]
+
+# Execute workflow
+report = HiringBriefReport()
+report.initialize(job_input="...", market_context="...")
+
+while not report.is_complete():
+    for form in report.next_forms():  # Data-driven scheduling
+        result = await execute_form(form)  # Route to Worker via form.resource
+        form.set_output(result)
+        report.complete_form(form)
+
+output = report.get_deliverable()
+```
+
+**Worker** (execution capability) - Functional station with @work methods:
+
+```python
+from krons.work import Worker, WorkerEngine, work, worklink
+
+class ClassifierWorker(Worker):
+    """Execution capability with internal DAG for retries."""
+
+    name = "classifier"
+
+    @work(assignment="job_input -> role_classification", capacity=2)
+    async def classify_role(self, job_input, **kwargs):
+        result = await self.llm.chat(**kwargs)
+        return result.role_classification
+
+    @work(assignment="code -> execution_result")
+    async def execute_code(self, code):
+        error = run_code(code)
+        return code, error
+
+    # Conditional edge for retry loops
+    @worklink(from_="execute_code", to_="debug_code")
+    async def maybe_debug(self, result):
+        code, error = result
+        if error:  # Only follow if error
+            return {"code": code, "error": error}
+        return None  # Skip edge
+
+# Execute with engine
+engine = WorkerEngine(worker=ClassifierWorker())
+task = await engine.add_task(task_function="classify_role", job_input="...")
+await engine.execute()
+```
+
+**Key concepts:**
+
+| Component | Role | State |
+|-----------|------|-------|
+| **Report** | Work order / artifact | Stateful (tracks one job) |
+| **Worker** | Station / capability | Stateless (handles many jobs) |
+| **Form** | Unit of work | Stateful (one assignment) |
+| **Phrase** | Typed I/O signature | Definition only |
+
+**Form assignment DSL:**
+
+```
+"branch: inputs -> outputs | resource"
+
+Examples:
+  "a, b -> c"                           # Simple (no branch, no resource)
+  "classifier: job -> role | api:fast"  # Full (branch + resource)
+  "writer: context -> summary"          # Branch only
+```
+
+- **branch**: Groups forms for sequential execution (same branch = sequential)
+- **resource**: Hint for routing to Worker capabilities (e.g., `api:fast`, `api:reasoning`)
+- Forms without branch execute in parallel based on data availability
+
 ## Testing Patterns
 
 ### Test Structure
@@ -200,8 +305,10 @@ vec_meta = extract_kron_db_meta(field_info, metas="Vector")
 tests/
 ├── core/           # Node, Element, Event tests
 ├── specs/          # Spec, Operable, Catalog tests
+├── work/           # Report, Worker, Form, Phrase, Engine tests
 ├── services/       # iModel, hook tests
-├── enforcement/    # KronService, policy tests
+├── operations/     # Operation, context tests
+├── rules/          # Validation rule tests
 └── utils/          # Utility function tests
 ```
 
@@ -251,11 +358,17 @@ class MockPolicyEngine:
 5. **compose_structure frozen param**: Currently broken in PydanticSpecAdapter (doesn't accept
    `frozen` kwarg).
 
+6. **Report vs Worker**: They operate at different levels:
+   - Report = declarative workflow (WHAT to do) - subclass and define `form_assignments`
+   - Worker = execution capability (HOW to do it) - has `@work` methods
+   - Forms without explicit branch run in parallel; same branch = sequential
+
+7. **Form assignment DSL**: The full format is `"branch: inputs -> outputs | resource"`.
+   All parts except `inputs -> outputs` are optional.
+
 ## Running Tests
 
 ```bash
-cd libs/krons
-
 # All tests
 uv run pytest tests/ -q
 
@@ -263,6 +376,7 @@ uv run pytest tests/ -q
 uv run pytest tests/ --cov=krons --cov-report=term-missing
 
 # Specific module
+uv run pytest tests/work/test_report.py -v
 uv run pytest tests/specs/test_catalog.py -v
 
 # Single test

{krons-0.1.1 → krons-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: krons
-Version: 0.1.1
+Version: 0.2.1
 Summary: Spec-based composable framework for building type-safe systems
 Project-URL: Homepage, https://github.com/khive-ai/krons
 Project-URL: Repository, https://github.com/khive-ai/krons
@@ -22,7 +22,21 @@ Requires-Dist: anyio>=4.10.0
 Requires-Dist: httpx>=0.26.0
 Requires-Dist: orjson>=3.10.0
 Requires-Dist: pydantic>=2.10.0
+Requires-Dist: pyyaml>=6.0.3
 Requires-Dist: rapidfuzz>=3.10.0
+Provides-Extra: agent
+Requires-Dist: fastmcp>=2.14.4; extra == 'agent'
+Requires-Dist: tiktoken>=0.11.0; extra == 'agent'
+Provides-Extra: all
+Requires-Dist: fastmcp>=2.14.4; extra == 'all'
+Requires-Dist: rich>=13.0; extra == 'all'
+Requires-Dist: tiktoken>=0.11.0; extra == 'all'
+Provides-Extra: display
+Requires-Dist: rich>=13.0; extra == 'display'
+Provides-Extra: fastmcp
+Requires-Dist: fastmcp>=2.14.4; extra == 'fastmcp'
+Provides-Extra: tiktoken
+Requires-Dist: tiktoken>=0.11.0; extra == 'tiktoken'
 Description-Content-Type: text/markdown
 
 # krons

krons-0.2.1/cookbooks/007_fan_out_in.py

@@ -0,0 +1,227 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Fan-out / fan-in pattern with Claude Code.
+
+Pattern:
+  1. Register resources and operations with session
+  2. session.conduct() -> orchestrator produces structured Instruct tasks
+  3. Tasks fan out to parallel Claude Code instances via session.conduct()
+  4. Results fan in and are synthesized by orchestrator via session.conduct()
+
+Usage:
+  uv run python cookbooks/007_fan_out_in.py
+  uv run python cookbooks/007_fan_out_in.py --simple   # Quick smoke test
+"""
+
+from __future__ import annotations
+
+import sys
+
+import anyio
+from pydantic import BaseModel, Field
+
+from krons.agent.operations import GenerateParams, Instruct, ReturnAs
+from krons.agent.providers.claude_code import (
+    ClaudeCodeEndpoint,
+    create_claude_code_config,
+)
+from krons.resource import iModel
+from krons.session import Session, SessionConfig
+from krons.utils.display import Timer, as_readable, display, phase, status
+from krons.utils.fuzzy import extract_json, fuzzy_validate_mapping
+
+CC_WORKSPACE = ".khive/workspace"
+VERBOSE = True
+
+
+# ---------------------------------------------------------------------------
+# Claude Code factory
+# ---------------------------------------------------------------------------
+
+
+def create_cc(name: str, subdir: str, **kwargs) -> iModel:
+    """Create a Claude Code iModel for a workspace subdirectory."""
+    config = create_claude_code_config(name=name)
+    config.update({"ws": f"{CC_WORKSPACE}/{subdir}", **kwargs})
+    endpoint = ClaudeCodeEndpoint(config=config)
+    return iModel(backend=endpoint)
+
+
+# ---------------------------------------------------------------------------
+# Structured output models
+# ---------------------------------------------------------------------------
+
+
+class InvestigationPlan(BaseModel):
+    """Orchestrator's structured plan: analysis + parallel Instruct tasks."""
+
+    analysis: str = Field(description="Initial analysis of the codebase")
+    research_tasks: list[Instruct] = Field(
+        description="Three parallel research instructions for deeper investigation",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Prompts
+# ---------------------------------------------------------------------------
+
+PLAN_PROMPT = (
+    "Investigate the codebase in the specified directory. "
+    "Glance over the key components, pay attention to architecture, "
+    "design patterns, and notable features. "
+    "Produce three parallel research instructions for deeper investigation."
+)
+
+PLAN_PROMPT_SIMPLE = (
+    "List the top 3 things to investigate in a Python project. "
+    "For each, provide a short research instruction."
+)
+
+SYNTHESIS_PROMPT = """\
+Synthesize the information from the researcher branches into a cohesive overview:
+1. Key components and their roles
+2. Architectural patterns used
+3. Design patterns and notable features
+"""
+
+SYNTHESIS_PROMPT_SIMPLE = """\
+Combine the researcher findings into a brief 2-3 sentence summary.
+"""
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def parse_plan(text: str) -> InvestigationPlan:
+    """Extract InvestigationPlan from LLM text output."""
+    target_keys = list(InvestigationPlan.model_fields.keys())
+    extracted = extract_json(text, fuzzy_parse=True)
+    if not extracted:
+        raise ValueError("Failed to extract JSON from orchestrator response")
+
+    block = extracted[0] if isinstance(extracted, list) else extracted
+    validated = fuzzy_validate_mapping(block, target_keys)
+    return InvestigationPlan.model_validate(validated)
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+
+async def main(simple: bool = False):
+    plan_prompt = PLAN_PROMPT_SIMPLE if simple else PLAN_PROMPT
+    synth_prompt = SYNTHESIS_PROMPT_SIMPLE if simple else SYNTHESIS_PROMPT
+    context = ["lionagi"] if not simple else None
+
+    # --- 1. Create resources ---
+    orc_model = create_cc("orchestrator", "orchestrator")
+
+    # --- 2. Create session with resources and operations ---
+    session = Session(
+        config=SessionConfig(
+            default_branch_name="orchestrator",
+            default_gen_model="orchestrator",
+            shared_resources={"orchestrator"},
+        )
+    )
+    session.resources.register(orc_model)
+
+    orc_branch = session.default_branch
+    status(
+        f"Session ready: {len(session.resources)} resources, branch={orc_branch.name}"
+    )
+
+    # --- 3. Phase 1: Plan (structured output from orchestrator) ---
+    phase("Phase 1: Planning")
+
+    plan_op = await session.conduct(
+        "generate",
+        orc_branch,
+        GenerateParams(
+            primary=plan_prompt,
+            context=context,
+            request_model=InvestigationPlan,
+            imodel="orchestrator",
+            return_as=ReturnAs.TEXT,
+        ),
+        verbose=VERBOSE,
+    )
+    plan = parse_plan(plan_op.execution.response)
+
+    status(f"Analysis: {plan.analysis[:120]}...")
+    status(f"Research tasks: {len(plan.research_tasks)}")
+    for i, task in enumerate(plan.research_tasks):
+        status(f"  [{i + 1}] {(task.instruction or '')[:80]}...")
+
+    if VERBOSE:
+        display(
+            as_readable(plan, format_curly=True),
+            title="Investigation Plan",
+        )
+
+    # --- 4. Phase 2: Fan-out (parallel research) ---
+    phase("Phase 2: Parallel Research")
+    results: list[str | None] = [None] * len(plan.research_tasks)
+
+    async def run_research(idx: int, task: Instruct) -> None:
+        name = f"researcher_{idx}"
+        researcher = create_cc(name, name)
+        session.resources.register(researcher, update=True)
+        branch = session.create_branch(name=name, resources={name})
+
+        instruction = task.instruction or ""
+        if task.guidance:
+            instruction += f"\n\nGuidance: {task.guidance}"
+
+        op = await session.conduct(
+            "generate",
+            branch,
+            GenerateParams(
+                primary=instruction,
+                context=task.context,
+                imodel=name,
+                return_as=ReturnAs.TEXT,
+            ),
+            verbose=VERBOSE,
+        )
+        results[idx] = op.execution.response
+        status(
+            f"Researcher {idx + 1} done ({len(results[idx] or '')} chars)",
+            style="success",
+        )
+
+    async with anyio.create_task_group() as tg:
+        for i, task in enumerate(plan.research_tasks):
+            tg.start_soon(run_research, i, task)
+
+    # --- 5. Phase 3: Fan-in (synthesis) ---
+    phase("Phase 3: Synthesis")
+    research_context = [
+        f"--- Researcher {i + 1} ---\n{r}"
+        for i, r in enumerate(results)
+        if r is not None
+    ]
+
+    synth_op = await session.conduct(
+        "generate",
+        orc_branch,
+        GenerateParams(
+            primary=synth_prompt,
+            context=research_context,
+            imodel="orchestrator",
+            return_as=ReturnAs.TEXT,
+        ),
+        verbose=VERBOSE,
+    )
+
+    phase("Final Synthesis")
+    print(synth_op.execution.response)
+
+
+if __name__ == "__main__":
+    simple = "--simple" in sys.argv
+    anyio.run(main, simple)

krons-0.2.1/cookbooks/test_conduct.py

@@ -0,0 +1,72 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Minimal test: one structured output via session.conduct("structure").
+
+Usage:
+  uv run python cookbooks/test_conduct.py
+"""
+
+from __future__ import annotations
+
+import anyio
+from pydantic import BaseModel, Field
+
+from krons.agent.operations import GenerateParams, Instruct, StructureParams
+from krons.agent.providers.claude_code import (
+    ClaudeCodeEndpoint,
+    create_claude_code_config,
+)
+from krons.core.specs import Operable
+from krons.resource import iModel
+from krons.session import Session, SessionConfig
+from krons.utils.display import as_readable, display, phase, status
+from krons.work.rules.validator import Validator
+
+
+class Plan(BaseModel):
+    analysis: str = Field(description="One sentence analysis")
+    tasks: list[Instruct] = Field(description="Two short research tasks")
+
+
+async def main():
+    # Setup
+    config = create_claude_code_config(name="test")
+    endpoint = ClaudeCodeEndpoint(config=config)
+    model = iModel(backend=endpoint)
+
+    session = Session(
+        config=SessionConfig(
+            default_branch_name="main",
+            default_gen_model="test",
+            shared_resources={"test"},
+        )
+    )
+    session.resources.register(model)
+
+    phase("Structured Output Test (structure operation)")
+
+    operable = Operable.from_structure(Plan)
+
+    op = await session.conduct(
+        "structure",
+        params=StructureParams(
+            generate_params=GenerateParams(
+                primary="Name two colors. For each, give a one-sentence research task.",
+                request_model=Plan,
+                imodel="test",
+            ),
+            validator=Validator(),
+            operable=operable,
+            strict=False,
+        ),
+        verbose=True,
+    )
+
+    result = op.execution.response
+    status(f"Result type: {type(result).__name__}")
+    display(as_readable(result, format_curly=True), title="Structured Output")
+
+
+if __name__ == "__main__":
+    anyio.run(main)

{krons-0.1.1 → krons-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "krons"
-version = "0.1.1"
+version = "0.2.1"
 description = "Spec-based composable framework for building type-safe systems"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -25,6 +25,7 @@ dependencies = [
     "httpx>=0.26.0",
     "orjson>=3.10.0",
     "pydantic>=2.10.0",
+    "pyyaml>=6.0.3",
     "rapidfuzz>=3.10.0",
 ]
 
@@ -41,6 +42,8 @@ dev = [
     "pytest>=8.0.0",
     "pytest-asyncio>=0.24.0",
     "hypothesis>=6.150.2",
+    "ipykernel>=7.1.0",
+    "ipywidgets>=8.1.8",
 ]
 
 [build-system]
@@ -58,4 +61,16 @@ markers = [
     "unit: marks tests as unit tests",
     "integration: marks tests as integration tests",
     "slow: marks tests as slow",
+    "property: marks tests as property-based tests (hypothesis)",
 ]
+
+[project.optional-dependencies]
+tiktoken = ["tiktoken>=0.11.0",]
+fastmcp = ["fastmcp>=2.14.4",]
+
+display = ["rich>=13.0"]
+
+agent = [
+    "krons[tiktoken, fastmcp]",
+]
+all = ["krons[agent, display]"]

krons-0.2.1/src/krons/__init__.py

@@ -0,0 +1,49 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+# Lazy module re-exports via __getattr__
+_MODULE_ALIASES: dict[str, str] = {
+    "types": "krons.core.types",
+    "specs": "krons.core.specs",
+    "session": "krons.session",
+    "operations": "krons.work.operations",
+    "agent": "krons.agent",
+    "resource": "krons.resource",
+    "work": "krons.work",
+}
+
+_LOADED_MODULES: dict[str, object] = {}
+
+
+def __getattr__(name: str) -> object:
+    """Lazy load aliased modules."""
+    if name in _LOADED_MODULES:
+        return _LOADED_MODULES[name]
+
+    if name in _MODULE_ALIASES:
+        from importlib import import_module
+
+        module = import_module(_MODULE_ALIASES[name])
+        _LOADED_MODULES[name] = module
+        return module
+
+    raise AttributeError(f"module 'krons' has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    """List available attributes."""
+    return list(_MODULE_ALIASES.keys())
+
+
+if TYPE_CHECKING:
+    from krons import agent as agent
+    from krons import resource as resource
+    from krons import session as session
+    from krons import work as work
+    from krons.core import specs as specs
+    from krons.core import types as types
+    from krons.work import operations as operations