flatagents 0.4.1__py3-none-any.whl

flatagents/validation.py

@@ -0,0 +1,141 @@
+"""
+Schema validation for flatagent and flatmachine configurations.
+
+Uses JSON Schema validation against the bundled schemas.
+Validation errors are warnings by default to avoid breaking user configs.
+"""
+
+import json
+import warnings
+from importlib.resources import files
+from typing import Any, Dict, List, Optional, Union
+
+# Package containing bundled assets
+_ASSETS = files("flatagents.assets")
+
+
+class ValidationWarning(UserWarning):
+    """Warning for schema validation issues."""
+    pass
+
+
+def _load_schema(filename: str) -> Optional[Dict[str, Any]]:
+    """Load a JSON schema from bundled assets."""
+    try:
+        content = (_ASSETS / filename).read_text()
+        return json.loads(content)
+    except FileNotFoundError:
+        return None
+
+
+def _validate_with_jsonschema(config: Dict[str, Any], schema: Dict[str, Any]) -> List[str]:
+    """Validate config against JSON Schema using jsonschema library."""
+    try:
+        import jsonschema
+    except ImportError:
+        return []  # Skip validation if jsonschema not installed
+
+    errors = []
+    validator = jsonschema.Draft7Validator(schema)
+    for error in validator.iter_errors(config):
+        path = ".".join(str(p) for p in error.absolute_path) or "(root)"
+        errors.append(f"{path}: {error.message}")
+    return errors
+
+
+def validate_flatagent_config(
+    config: Dict[str, Any],
+    warn: bool = True,
+    strict: bool = False
+) -> List[str]:
+    """
+    Validate a flatagent configuration against the schema.
+
+    Args:
+        config: The configuration dictionary to validate
+        warn: If True, emit warnings for validation errors (default: True)
+        strict: If True, raise ValueError on validation errors (default: False)
+
+    Returns:
+        List of validation error messages (empty if valid)
+    """
+    schema = _load_schema("flatagent.schema.json")
+    if schema is None:
+        return []  # Schema not bundled, skip validation
+
+    errors = _validate_with_jsonschema(config, schema)
+
+    if errors:
+        if strict:
+            raise ValueError(
+                f"Flatagent config validation failed:\n" +
+                "\n".join(f"  - {e}" for e in errors)
+            )
+        elif warn:
+            warnings.warn(
+                f"Flatagent config has validation issues:\n" +
+                "\n".join(f"  - {e}" for e in errors),
+                ValidationWarning,
+                stacklevel=3
+            )
+
+    return errors
+
+
+def validate_flatmachine_config(
+    config: Dict[str, Any],
+    warn: bool = True,
+    strict: bool = False
+) -> List[str]:
+    """
+    Validate a flatmachine configuration against the schema.
+
+    Args:
+        config: The configuration dictionary to validate
+        warn: If True, emit warnings for validation errors (default: True)
+        strict: If True, raise ValueError on validation errors (default: False)
+
+    Returns:
+        List of validation error messages (empty if valid)
+    """
+    schema = _load_schema("flatmachine.schema.json")
+    if schema is None:
+        return []  # Schema not bundled, skip validation
+
+    errors = _validate_with_jsonschema(config, schema)
+
+    if errors:
+        if strict:
+            raise ValueError(
+                f"Flatmachine config validation failed:\n" +
+                "\n".join(f"  - {e}" for e in errors)
+            )
+        elif warn:
+            warnings.warn(
+                f"Flatmachine config has validation issues:\n" +
+                "\n".join(f"  - {e}" for e in errors),
+                ValidationWarning,
+                stacklevel=3
+            )
+
+    return errors
+
+
+def get_flatagent_schema() -> Optional[Dict[str, Any]]:
+    """Get the bundled flatagent JSON schema."""
+    return _load_schema("flatagent.schema.json")
+
+
+def get_flatmachine_schema() -> Optional[Dict[str, Any]]:
+    """Get the bundled flatmachine JSON schema."""
+    return _load_schema("flatmachine.schema.json")
+
+
+def get_asset(filename: str) -> str:
+    """Get the contents of a bundled asset file."""
+    return (_ASSETS / filename).read_text()
+
+
+def _get_asset_path(filename: str):
+    """Internal: Get a Traversable for a bundled asset file."""
+    return _ASSETS / filename

flatagents-0.4.1.dist-info/METADATA

@@ -0,0 +1,310 @@
+Metadata-Version: 2.4
+Name: flatagents
+Version: 0.4.1
+Summary: A lightweight framework for building LLM-powered agents and composable state machines with pluggable backends.
+Project-URL: Homepage, https://github.com/memgrafter/flatagents
+Project-URL: Repository, https://github.com/memgrafter/flatagents
+Project-URL: Issues, https://github.com/memgrafter/flatagents/issues
+Author-email: memgrafter@gmail.com
+License-Expression: Apache-2.0
+Keywords: agents,ai,aisuite,framework,litellm,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: aiofiles
+Requires-Dist: httpx
+Requires-Dist: jinja2
+Requires-Dist: pyyaml
+Provides-Extra: aisuite
+Requires-Dist: aisuite[all]; extra == 'aisuite'
+Provides-Extra: all
+Requires-Dist: aisuite[all]; extra == 'all'
+Requires-Dist: cel-python; extra == 'all'
+Requires-Dist: jsonschema>=4.0; extra == 'all'
+Requires-Dist: litellm; extra == 'all'
+Requires-Dist: opentelemetry-api>=1.20.0; extra == 'all'
+Requires-Dist: opentelemetry-exporter-otlp>=1.20.0; extra == 'all'
+Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'all'
+Provides-Extra: cel
+Requires-Dist: cel-python; extra == 'cel'
+Provides-Extra: gcp
+Requires-Dist: aisuite[all]; extra == 'gcp'
+Requires-Dist: cel-python; extra == 'gcp'
+Requires-Dist: google-cloud-firestore>=2.11.0; extra == 'gcp'
+Requires-Dist: jsonschema>=4.0; extra == 'gcp'
+Requires-Dist: litellm; extra == 'gcp'
+Requires-Dist: opentelemetry-api>=1.20.0; extra == 'gcp'
+Requires-Dist: opentelemetry-exporter-otlp>=1.20.0; extra == 'gcp'
+Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'gcp'
+Provides-Extra: litellm
+Requires-Dist: litellm; extra == 'litellm'
+Provides-Extra: local
+Requires-Dist: aisuite[all]; extra == 'local'
+Requires-Dist: cel-python; extra == 'local'
+Requires-Dist: jsonschema>=4.0; extra == 'local'
+Requires-Dist: litellm; extra == 'local'
+Requires-Dist: opentelemetry-api>=1.20.0; extra == 'local'
+Requires-Dist: opentelemetry-exporter-otlp>=1.20.0; extra == 'local'
+Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'local'
+Provides-Extra: metrics
+Requires-Dist: opentelemetry-api>=1.20.0; extra == 'metrics'
+Requires-Dist: opentelemetry-exporter-otlp>=1.20.0; extra == 'metrics'
+Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'metrics'
+Provides-Extra: validation
+Requires-Dist: jsonschema>=4.0; extra == 'validation'
+Description-Content-Type: text/markdown
+
+# FlatAgents
+
+Define LLM agents in YAML. Run them anywhere.
+
+**For LLM/machine readers:** see [MACHINES.md](./MACHINES.md) for comprehensive reference.
+
+## Why?
+
+- **Composition over inheritance** — compose stateless agents and checkpointable machines
+- **Compact structure** — easy for LLMs to read and generate
+- **Simple hook interfaces** — escape hatches without complexity; webhook ready
+- **Inspectable** — every agent and machine is readable config
+- **Language-agnostic** — reduce code in any particular runtime
+- **Common TypeScript interface** — single schema for agents, single schema for machines
+- **Limitations** — machine topologies can get complex at scale
+
+*Inspired by Kubernetes manifests and character card specifications.*
+
+## Core Concepts
+
+Use machines to write flatagents and flatmachines, they are designed for LLMs.
+
+| Term | What it is |
+|------|------------|
+| **FlatAgent** | A single LLM call: model + prompts + output schema |
+| **FlatMachine** | A state machine that orchestrates multiple agents, actions, and state machines |
+
+Use FlatAgent alone for simple tasks. Use FlatMachine when you need multi-step workflows, branching, or error handling.
+
+## Examples
+
+| Example | What it demonstrates |
+|---------|---------------------|
+| [helloworld](./sdk/python/examples/helloworld) | Minimal setup — single agent, single state machine |
+| [writer_critic](./sdk/python/examples/writer_critic) | Multi-agent loop — writer drafts, critic reviews, iterates |
+| [story_writer](./sdk/python/examples/story_writer) | Multi-step creative workflow with chapter generation |
+| [human_in_loop](./sdk/python/examples/human_in_loop) | Pause execution for human approval via hooks |
+| [error_handling](./sdk/python/examples/error_handling) | Error recovery and retry patterns at state machine level |
+| [dynamic_agent](./sdk/python/examples/dynamic_agent) | On-the-fly agent generation from runtime context |
+| [character_card](./sdk/python/examples/character_card) | Loading agent config from character card format |
+| [mdap](./sdk/python/examples/mdap) | MDAP voting execution — multi-sample consensus |
+| [gepa_self_optimizer](./sdk/python/examples/gepa_self_optimizer) | Self-optimizing prompts via reflection and critique |
+| [research_paper_analysis](./sdk/python/examples/research_paper_analysis) | Document analysis with structured extraction |
+| [multi_paper_synthesizer](./sdk/python/examples/multi_paper_synthesizer) | Cross-document synthesis with dynamic machine launching |
+| [support_triage_json](./sdk/python/examples/support_triage_json) | JSON input/output with classification pipeline |
+| [parallelism](./sdk/python/examples/parallelism) | Parallel machines, dynamic foreach, fire-and-forget launches |
+
+## Quick Start
+
+```bash
+pip install flatagents[all]
+```
+
+```python
+from flatagents import FlatAgent
+
+agent = FlatAgent(config_file="reviewer.yml")
+result = await agent.call(query="Review this code...")
+print(result.output)
+```
+
+## Example Agent
+
+**reviewer.yml**
+```yaml
+spec: flatagent
+spec_version: "0.0.0"
+
+data:
+  name: code-reviewer
+
+  model:
+    provider: openai
+    name: gpt-4
+    temperature: 0.3
+
+  system: |
+    You are a senior code reviewer. Analyze code for bugs, 
+    style issues, and potential improvements.
+
+  user: |
+    Review this code:
+    {{ input.code }}
+
+  output:
+    issues:
+      type: list
+      items:
+        type: str
+      description: "List of issues found"
+    rating:
+      type: str
+      enum: ["good", "needs_work", "critical"]
+      description: "Overall code quality"
+```
+
+**What the fields mean:**
+
+- **spec/spec_version** — Format identifier and version
+- **data.name** — Agent identifier
+- **data.model** — LLM provider, model name, and parameters
+- **data.system** — System prompt (sets behavior)
+- **data.user** — User prompt template (uses Jinja2, `{{ input.* }}` for runtime values)
+- **data.output** — Structured output schema (the runtime extracts these fields)
+
+## Output Types
+
+```yaml
+output:
+  answer:      { type: str }
+  count:       { type: int }
+  score:       { type: float }
+  valid:       { type: bool }
+  raw:         { type: json }
+  items:       { type: list, items: { type: str } }
+  metadata:    { type: object, properties: { key: { type: str } } }
+```
+
+Use `enum: [...]` to constrain string values.
+
+## Multi-Agent Workflows
+
+For orchestration, use FlatMachine ([full docs in MACHINES.md](./MACHINES.md)):
+
+```python
+from flatagents import FlatMachine
+
+machine = FlatMachine(config_file="workflow.yml")
+result = await machine.execute(input={"query": "..."})
+```
+
+FlatMachine provides: state transitions, conditional branching, loops, retry with backoff, and error recovery—all in YAML.
+
+## Features
+
+- Checkpoint and restore
+- Python SDK (TypeScript SDK in progress)
+- [MACHINES.md](./MACHINES.md) — LLM-optimized reference docs
+- Decider agents and machines
+- On-the-fly agent and machine definitions
+- Webhook hooks for remote state machine handling
+- Metrics and logging
+- Error recovery and exception handling at the state machine level
+- Parallel machine execution (`machine: [a, b, c]`)
+- Dynamic parallelism with `foreach`
+- Fire-and-forget launches for background tasks
+
+## Planned
+
+- Distributed execution — cross-network machine peering, inter-machine strategies
+- SQL persistence backend
+- TypeScript SDK
+- `max_depth` config to limit machine launch nesting
+- Checkpoint pruning to prevent storage explosion
+- `$root/` path prefix — resolve agent/machine refs from workspace root, not config dir
+- Input size validation — warn when prompt exceeds model context window
+- Serialization warnings — flag non-JSON-serializable context values before checkpoint
+
+## Specs
+
+TypeScript definitions are the source of truth:
+- [`flatagent.d.ts`](./flatagent.d.ts)
+- [`flatmachine.d.ts`](./flatmachine.d.ts)
+
+## Python SDK
+
+```bash
+pip install flatagents[litellm]
+```
+
+### LLM Backends
+
+```python
+from flatagents import LiteLLMBackend, AISuiteBackend
+
+# LiteLLM (default)
+agent = FlatAgent(config_file="agent.yml")
+
+# AISuite
+backend = AISuiteBackend(model="openai:gpt-4o")
+agent = FlatAgent(config_file="agent.yml", backend=backend)
+```
+
+### Hooks
+
+Extend machine behavior with Python hooks:
+
+```python
+from flatagents import FlatMachine, MachineHooks
+
+class CustomHooks(MachineHooks):
+    def on_state_enter(self, state: str, context: dict) -> dict:
+        context["entered_at"] = time.time()
+        return context
+
+    def on_action(self, action: str, context: dict) -> dict:
+        if action == "fetch_data":
+            context["data"] = fetch_from_api()
+        return context
+
+machine = FlatMachine(config_file="machine.yml", hooks=CustomHooks())
+```
+
+**Available hooks**: `on_machine_start`, `on_machine_end`, `on_state_enter`, `on_state_exit`, `on_transition`, `on_error`, `on_action`
+
+### Execution Types
+
+```yaml
+execution:
+  type: retry              # retry | parallel | mdap_voting
+  backoffs: [2, 8, 16, 35] # Seconds between retries
+  jitter: 0.1              # ±10% random variation
+```
+
+| Type | Use Case |
+|------|----------|
+| `default` | Single call |
+| `retry` | Rate limit handling with backoff |
+| `parallel` | Multiple samples (`n_samples`) |
+| `mdap_voting` | Consensus voting (`k_margin`, `max_candidates`) |
+
+### Schema Validation
+
+```python
+from flatagents import validate_flatagent_config, validate_flatmachine_config
+
+warnings = validate_flatagent_config(config)
+warnings = validate_flatmachine_config(config)
+```
+
+### Logging & Metrics
+
+```python
+from flatagents import setup_logging, get_logger
+
+setup_logging(level="INFO")  # Respects FLATAGENTS_LOG_LEVEL env var
+logger = get_logger(__name__)
+```
+
+**Env vars**: `FLATAGENTS_LOG_LEVEL` (`DEBUG`/`INFO`/`WARNING`/`ERROR`), `FLATAGENTS_LOG_FORMAT` (`standard`/`json`/`simple`)
+
+For OpenTelemetry metrics:
+
+```bash
+pip install flatagents[metrics]
+export FLATAGENTS_METRICS_ENABLED=true
+```

flatagents-0.4.1.dist-info/RECORD

@@ -0,0 +1,28 @@
+flatagents/__init__.py,sha256=pOSyQ5XS3iX-HkLRLsqQAUSEYHRg4a7z2X6TASSf-EQ,2957
+flatagents/actions.py,sha256=B5rkNVJ9M4GV0xRYJxpXSjbAe_oJpZyc-Ik5ImFqcHg,7851
+flatagents/backends.py,sha256=RAeeL_m9AzE705oaVxezHG82r9Ix_iNSPvgHMpBSzWI,6061
+flatagents/baseagent.py,sha256=YxVNK_P7S4kOQlOAcb_uoloM1oSEuNvSs6VybsqGqJI,30843
+flatagents/execution.py,sha256=wXjmS9RD9JVbhIzaDSO11B1OnNNtFUbQpokiZsnMcsI,14401
+flatagents/flatagent.py,sha256=-fbx2CezKOahOtgR-nQU40b8bcaNko5-dVyQoVD3IU8,25621
+flatagents/flatmachine.py,sha256=4FQmY54gbtJ8SRSOI93GLsCeEYjvpdBO6ij9NvdgNqc,44288
+flatagents/hooks.py,sha256=Kx96ARxZs-5s7foOpy4IKb2trVx92vzAzVjEsX0hqGQ,12042
+flatagents/locking.py,sha256=QjIknWB2FX0Yr3sAPlkweigPNUgKyUcnKLO-756TZFI,2127
+flatagents/monitoring.py,sha256=GYmibtNFwY0lFi61HdqO9JfKMw4MEcOsyvFBlO2Pycw,13149
+flatagents/persistence.py,sha256=ARHvxidHBTTKr_FB-XLvyE7QLSxXxseodTYNDj-z6M4,7541
+flatagents/utils.py,sha256=iEA-XTN-90IORjWq-v-Xl8_uD70eihbYMmZkx--4IFw,1115
+flatagents/validation.py,sha256=rp19cz6Zlbce_yMqw3YJ5KMSuMjQnoCCJ-DV62zDyU0,4166
+flatagents/assets/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+flatagents/assets/flatagent.d.ts,sha256=XMi4VZUB7yCV4GuYF7dD4RrsWpCg3S6hPoWe3xqJHJA,5818
+flatagents/assets/flatagent.schema.json,sha256=IjkBIMI6uWNcRD98Aqz4ncGpXA9Y3HZC_Qh0-Z2C_TU,4333
+flatagents/assets/flatagent.slim.d.ts,sha256=7QlSeDQYVaVXvo_wCxL_apU6-GnsXXe1KbW3vlsAupU,1321
+flatagents/assets/flatmachine.d.ts,sha256=J1qRTInuko8GZHowQIehKWVkpTKS4GTxOVjej_hNdPs,10910
+flatagents/assets/flatmachine.schema.json,sha256=B2NRmMNUTRDTneaTcXE1gfy97T35n-mFQMGwHuaDg3c,11175
+flatagents/assets/flatmachine.slim.d.ts,sha256=_vTzpLuN3e_3iHQKMK-EfoXw9zxqLeiyfV_j_1wnNgg,2636
+flatagents/expressions/__init__.py,sha256=kk7P97dtcuJ1C0XCvZSkyO8VOBTbwr3Lyi6b8gTIXgo,1683
+flatagents/expressions/cel.py,sha256=yklm062UTG8G2a1-IZfU8A2XtcK48Qmc0AhbJICN1Ac,3127
+flatagents/expressions/simple.py,sha256=zLZHcRXb62qITAomMxOedfCvIthxVSyIH5MtNesFrIc,5774
+flatagents/gcp/__init__.py,sha256=YYtC7H24q624x9r6zdDpsDCTk1O5zzls8WmGiAOqZxc,537
+flatagents/gcp/firestore.py,sha256=qmNMgoBQp6AzUsY5kHAKmfd1qSlhCX0JRSNdHX60g1A,7229
+flatagents-0.4.1.dist-info/METADATA,sha256=AAkacvwHxnubpJTVejG0TMg_7A9xHzs2C5E3Px2fe7w,10732
+flatagents-0.4.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+flatagents-0.4.1.dist-info/RECORD,,

flatagents-0.4.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any