krons 0.2.2__tar.gz → 0.2.4__tar.gz

{krons-0.2.2 → krons-0.2.4}/.gitignore

@@ -206,4 +206,5 @@ marimo/_static/
 marimo/_lsp/
 __marimo__/
 
-*.DS_Store
+*.DS_Store
+*.*_cache/

krons-0.2.4/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.4] - 2026-02-04
+
+### Added
+
+- `parse_forward_ref` canonical parser for ForwardRef annotations
+- Support for `FK["Model"]` and `FK['Model']` string forward references
+- Robust nullability detection: `Optional[X]`, `Union[X, None]`, `X | None`
+- `meta_key` parameter in `ContentSpecs.get_specs()` for DB alias customization
+- Duck typing (`_is_spec_like`) to avoid circular imports
+
+### Changed
+
+- DDL generation now uses config-driven audit columns (dict pattern)
+- `_utils.py` uses shared `parse_forward_ref` instead of duplicate implementation
+- Removed `include_audit_columns` parameter from `generate_ddl()` (now config-driven)
+
+### Fixed
+
+- ForwardRef parsing with `from __future__ import annotations` (PEP 563)
+- Nested Union types in nullability detection (e.g., `Union[FK[User], None]`)
+
+## [0.2.3] - 2026-02-04
+
+### Added
+
+- Multi-agent example patterns (code_review_panel, tech_debate)
+- 10 comprehensive examples demonstrating framework capabilities
+
+### Fixed
+
+- Pile UUID access bug for Element retrieval

krons-0.2.4/CLAUDE.md

@@ -0,0 +1,183 @@
+# krons - Spec-Based Composable Framework
+
+## Quick Reference
+
+```text
+krons/
+├── core/           # Element, Node, Flow, Graph, Pile, Event
+├── session/        # Session, Branch, Message (conversation orchestration)
+├── resource/       # iModel, Endpoint, HookRegistry (API backends)
+├── agent/          # Operations pipeline (generate → parse → structure → operate → react)
+├── work/           # Report, Worker, Form (workflow orchestration)
+└── utils/          # JSON, concurrency, display helpers
+```
+
+## Core Primitives
+
+### Element — Base identity class
+
+```python
+from krons.core import Element
+
+class MyEntity(Element):
+    name: str
+
+e = MyEntity(name="test")
+e.id          # UUID (frozen)
+e.created_at  # datetime (frozen)
+e.to_dict(mode="json")  # Serialization with kron_class for polymorphic restore
+Element.from_dict(data)  # Polymorphic deserialization
+```
+
+### Pile — Thread-safe typed collection
+
+```python
+from krons.core import Pile
+
+pile = Pile[MyEntity](item_type={MyEntity})
+pile.add(entity)
+pile.get(uuid_or_str)
+pile[0]                    # By index
+pile[lambda x: x.name]     # Filter
+async with pile:           # Async lock
+    ...
+```
+
+### Node — Polymorphic content container
+
+```python
+from krons.core import Node, create_node
+
+# Dynamic node
+node = Node(content={"key": "value"})
+
+# Typed node with DB features
+MyNode = create_node("MyNode", content=MyContent, flatten_content=True)
+```
+
+## Session — Conversation Orchestration
+
+```python
+from krons.session import Session, SessionConfig
+
+session = Session(config=SessionConfig(
+    default_branch_name="main",
+    default_gen_model="gpt-4",
+    log_persist_dir="./logs",      # Enable persistence (None = disabled)
+    log_auto_save_on_exit=True,    # atexit handler
+))
+
+# Register model
+session.resources.register(imodel)
+
+# Execute operations
+op = await session.conduct("generate", params=GenerateParams(...))
+op = await session.conduct("structure", params=StructureParams(...))
+
+# Access messages
+session.messages              # Pile[Message]
+session.dump()                # Sync dump full session to JSON
+await session.adump()         # Async dump
+
+# Restore from dump
+restored = Session.from_dict(data)  # Then re-register resources
+```
+
+## Resource — API Backends
+
+```python
+from krons.resource import iModel, Endpoint, EndpointConfig
+
+config = EndpointConfig(
+    name="gpt-4",
+    provider="openai",
+    endpoint="chat/completions",
+    base_url="https://api.openai.com/v1",
+    api_key="...",
+)
+model = iModel(backend=Endpoint(config=config))
+calling = await model.invoke(messages=[...])
+```
+
+## Agent Operations
+
+Pipeline: `generate → parse → structure → operate → react`
+
+```python
+from krons.agent.operations import GenerateParams, StructureParams
+
+# Generate raw LLM response
+op = await session.conduct("generate", params=GenerateParams(
+    primary="Your prompt",
+    imodel="gpt-4",
+))
+
+# Structured output with validation
+op = await session.conduct("structure", params=StructureParams(
+    generate_params=GenerateParams(primary="...", request_model=MyModel),
+    validator=Validator(),
+    operable=Operable.from_structure(MyModel),
+))
+```
+
+## Work — Workflow Orchestration
+
+### Report (declarative workflow)
+
+```python
+from krons.work import Report
+
+class MyReport(Report):
+    result: str | None = None
+    assignment: str = "input -> result"
+    form_assignments: list[str] = [
+        "step1: input -> intermediate",
+        "step2: intermediate -> result",
+    ]
+```
+
+### Worker (execution capability)
+
+```python
+from krons.work import Worker, work
+
+class MyWorker(Worker):
+    name = "processor"
+
+    @work(assignment="input -> output")
+    async def process(self, input, **kwargs):
+        return transform(input)
+```
+
+## Protocols
+
+```python
+from krons.protocols import implements, Serializable
+
+@implements(Serializable, signature_check="error")
+class MyClass:
+    def to_dict(self, **kwargs): ...
+```
+
+## Testing
+
+```bash
+uv run pytest tests/ -q              # All tests
+uv run pytest tests/core/ -xvs       # Core module verbose
+uv run pytest -k "test_session" -v   # Pattern match
+```
+
+```python
+import pytest
+
+@pytest.mark.anyio
+async def test_async():
+    result = await some_call()
+    assert result
+```
+
+## Code Style
+
+- Python 3.11+, Pydantic v2, anyio
+- `uv run ruff check src/ --fix && uv run ruff format src/`
+- Type hints required on public APIs

{krons-0.2.2 → krons-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: krons
-Version: 0.2.2
+Version: 0.2.4
 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

krons-0.2.4/examples/__init__.py

@@ -0,0 +1,50 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""krons Usage Examples
+
+This module provides practical, runnable examples demonstrating krons patterns
+with Claude Code integration.
+
+Multi-Agent Patterns (parallel Claude Code):
+    code_review_panel   - 3 specialist reviewers + moderator synthesis
+    tech_debate         - Adversarial debate with advocate/skeptic/pragmatist + judge
+
+Worker Patterns (declarative workflows):
+    validation_loop     - Self-correcting LLM generation with bounded retries
+    codegen_pipeline    - Code generation with error recovery workflow
+    research_agent      - Adaptive depth research with confidence-based routing
+
+Exchange Patterns (async message passing):
+    pipeline_router     - Multi-stage data processing pipeline
+    event_sourcing      - Event persistence, snapshots, and replay
+
+Specs Patterns (dynamic schema composition):
+    dynamic_response    - Runtime Pydantic model generation with validators
+
+Combined Patterns:
+    multi_agent_orchestration - Supervisor-worker coordination via Exchange + Worker
+
+Run any example:
+    uv run python examples/code_review_panel.py
+    uv run python examples/tech_debate.py
+    uv run python examples/validation_loop.py
+    # etc.
+"""
+
+__all__ = [
+    # Multi-agent patterns (featured)
+    "code_review_panel",
+    "tech_debate",
+    # Worker patterns
+    "validation_loop",
+    "codegen_pipeline",
+    "research_agent",
+    # Exchange patterns
+    "pipeline_router",
+    "event_sourcing",
+    # Specs patterns
+    "dynamic_response",
+    # Combined patterns
+    "multi_agent_orchestration",
+]