flatmachines 1.0.0__py3-none-any.whl

flatmachines-1.0.0.dist-info/METADATA

@@ -0,0 +1,390 @@
+Metadata-Version: 2.4
+Name: flatmachines
+Version: 1.0.0
+Summary: State machine orchestration for agent workflows.
+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,llm,orchestration,state-machine,workflow
+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: all
+Requires-Dist: cel-python; extra == 'all'
+Requires-Dist: flatagents>=0.10.0; extra == 'all'
+Requires-Dist: jsonschema>=4.0; 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'
+Requires-Dist: smolagents; extra == 'all'
+Provides-Extra: cel
+Requires-Dist: cel-python; extra == 'cel'
+Provides-Extra: flatagents
+Requires-Dist: flatagents>=0.10.0; extra == 'flatagents'
+Provides-Extra: local
+Requires-Dist: cel-python; extra == 'local'
+Requires-Dist: flatagents>=0.10.0; extra == 'local'
+Requires-Dist: jsonschema>=4.0; 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'
+Requires-Dist: smolagents; 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: smolagents
+Requires-Dist: smolagents; extra == 'smolagents'
+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.*
+
+## Versioning
+
+All specs (`flatagent.d.ts`, `flatmachine.d.ts`, `profiles.d.ts`) and SDKs (Python, JS) use **lockstep versioning**. A single version number applies across the entire repository.
+
+## 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/examples/helloworld/python) | Minimal setup — single agent, single state machine |
+| [writer_critic](./sdk/examples/writer_critic/python) | Multi-agent loop — writer drafts, critic reviews, iterates |
+| [story_writer](./sdk/examples/story_writer/python) | Multi-step creative workflow with chapter generation |
+| [human-in-the-loop](./sdk/examples/human-in-the-loop/python) | Pause execution for human approval via hooks |
+| [error_handling](./sdk/examples/error_handling/python) | Error recovery and retry patterns at state machine level |
+| [dynamic_agent](./sdk/examples/dynamic_agent/python) | On-the-fly agent generation from runtime context |
+| [character_card](./sdk/examples/character_card/python) | Loading agent config from character card format |
+| [mdap](./sdk/examples/mdap/python) | MDAP voting execution — multi-sample consensus |
+| [gepa_self_optimizer](./sdk/examples/gepa_self_optimizer/python) | Self-optimizing prompts via reflection and critique |
+| [research_paper_analysis](./sdk/examples/research_paper_analysis/python) | Document analysis with structured extraction |
+| [multi_paper_synthesizer](./sdk/examples/multi_paper_synthesizer/python) | Cross-document synthesis with dynamic machine launching |
+| [support_triage_json](./sdk/examples/support_triage_json/python) | JSON input/output with classification pipeline |
+| [distributed_worker](./sdk/examples/distributed_worker/python) | Worker pool with registration + work backends, scaling, stale worker reaping |
+| [parallelism](./sdk/examples/parallelism/python) | 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: "1.0.0"
+
+data:
+  name: code-reviewer
+
+  model: "smart-expensive"  # Reference profile from profiles.yml
+
+  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** — Profile name, inline config, or profile with overrides
+- **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)
+
+## Model Profiles
+
+Centralize model configurations in `profiles.yml` and reference them by name:
+
+**profiles.yml**
+```yaml
+spec: flatprofiles
+spec_version: "1.0.0"
+
+data:
+  model_profiles:
+    fast-cheap:
+      provider: cerebras
+      name: zai-glm-4.6
+      temperature: 0.6
+      max_tokens: 2048
+
+    smart-expensive:
+      provider: anthropic
+      name: claude-3-opus-20240229
+      temperature: 0.3
+      max_tokens: 4096
+
+  default: fast-cheap      # Fallback when agent has no model
+  # override: smart-expensive  # Uncomment to force all agents
+```
+
+**Agent usage:**
+```yaml
+# String shorthand — profile lookup
+model: "fast-cheap"
+
+# Profile with overrides
+model:
+  profile: "fast-cheap"
+  temperature: 0.9
+
+# Inline config (no profile)
+model:
+  provider: openai
+  name: gpt-4
+  temperature: 0.3
+```
+
+Resolution order (low → high): default profile → named profile → inline overrides → override profile
+
+## 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.
+
+## Distributed Worker Pattern
+
+FlatAgents includes `DistributedWorkerHooks` plus `RegistrationBackend`/`WorkBackend` implementations (SQLite in the reference SDK) to build worker pools.
+
+Typical topology:
+- **Checker**: `get_pool_state` → `calculate_spawn` → `spawn_workers` (requires `worker_config_path` in context or override in hooks)
+- **Worker**: `register_worker` → `claim_job` → process → `complete_job`/`fail_job` → `deregister_worker`
+- **Reaper**: `list_stale_workers` → `reap_stale_workers`
+
+See [distributed_worker](./sdk/examples/distributed_worker/python) for a runnable demo.
+
+## 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
+- Distributed worker orchestration (registration/work backends, scaling hooks, stale worker reaping)
+
+## Planned
+
+- Distributed execution backends (Redis/Postgres) + cross-network peering 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)
+- [`profiles.d.ts`](./profiles.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
+```
+
+Metrics are enabled by default and print to stdout every 5s. Redirect to file or use OTLP for production:
+
+```bash
+# Metrics print to stdout by default
+python your_script.py
+
+# Save to file
+python your_script.py >> metrics.log 2>&1
+
+# Disable if needed
+FLATAGENTS_METRICS_ENABLED=false python your_script.py
+
+# Send to OTLP collector for production
+OTEL_METRICS_EXPORTER=otlp \
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 \
+python your_script.py
+```
+
+**Env vars for metrics**:
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `FLATAGENTS_METRICS_ENABLED` | `true` | Enable OpenTelemetry metrics |
+| `OTEL_METRICS_EXPORTER` | `console` | `console` (stdout) or `otlp` (production) |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | — | OTLP collector endpoint |
+| `OTEL_METRIC_EXPORT_INTERVAL` | `5000` / `60000` | Export interval in ms (5s for console, 60s for otlp) |
+| `OTEL_SERVICE_NAME` | `flatagents` | Service name in metrics |

flatmachines-1.0.0.dist-info/RECORD

@@ -0,0 +1,41 @@
+flatmachines/__init__.py,sha256=f_VWD4IclVHT4ltyT0CzWAgROf9trnAQwSa7kkuQPAc,3122
+flatmachines/actions.py,sha256=nGIU0YvxOQPTwXYII3O2jPgEfvzfO2ugXGFz7TErryM,13390
+flatmachines/agents.py,sha256=c_3bb2jtsreMrqVfsrCjVIpF19bXYbx0rq2WjMG1bKA,3898
+flatmachines/backends.py,sha256=RAeeL_m9AzE705oaVxezHG82r9Ix_iNSPvgHMpBSzWI,6061
+flatmachines/distributed.py,sha256=yNJVVYWVuAn8DXTN7xcuGRh4YT2ItNkFMRGvrFaMgoI,29520
+flatmachines/distributed_hooks.py,sha256=hNGnFV9rEv2bmvxqlQqdgsk-1cKb_UKkNRaPvHfFoNU,12783
+flatmachines/execution.py,sha256=e_czNVCMk3lfGdRN0dWBckPUjPskXbHVTBu_iNwB1Do,21568
+flatmachines/flatmachine.py,sha256=HGA8LE5XGi0xxyFbNERAG-Lwed3OggGqksi7j7HB2M8,47591
+flatmachines/hooks.py,sha256=be5pBjPiNZX7GcD35z-TOwU8r4tPj-tF9e0W7siD9d0,12079
+flatmachines/locking.py,sha256=QjIknWB2FX0Yr3sAPlkweigPNUgKyUcnKLO-756TZFI,2127
+flatmachines/monitoring.py,sha256=nFk4LVl7lxoJDOwrDMqtrW26R1JBFJ1BuXbJ7BbZuHQ,18954
+flatmachines/persistence.py,sha256=yta-tJ8gLNSgQvftyrUvBPztxsWaQOod1lUdaHzWLDk,8012
+flatmachines/run.py,sha256=AyBGkvjzV5CEq2JepY4RrL2NNfpkSbfO7IWjH9QZfAY,2940
+flatmachines/utils.py,sha256=RurktZqJPi3k7hUIWPeohdhTmXvH7P9Eq2iHK10MVxg,4902
+flatmachines/validation.py,sha256=HoMBD2nA6TJA5vcBpxuJ9jzGYgSTzuKLBqOuSaSodOc,2173
+flatmachines/adapters/__init__.py,sha256=dX-xTz-fgvaPyU8fhgW3-YQVqlURNrS1UKZ8poSRlGQ,945
+flatmachines/adapters/flatagent.py,sha256=DT4RwUBIEub0FWzoEhpJSsy40-nNYRvQo7NVKdjrtZY,2734
+flatmachines/adapters/pi_agent_bridge.py,sha256=zC8zICFJkEdfESvgEVVryRiAXV4rMegs-B9VbmZheSA,3999
+flatmachines/adapters/pi_agent_runner.mjs,sha256=zkIgGbkU5gtAmrwmJSOTpzSesQhDZQdHM7RWBBqss30,2688
+flatmachines/adapters/smolagents.py,sha256=kM1vLT2GeYce6XFMrtJzErH82xIV37UMxo7pE8AhlHA,4506
+flatmachines/assets/MACHINES.md,sha256=COdsS69X8_CPMZxl-5XqKVPk-TigueM6bKBgvcQwykY,4604
+flatmachines/assets/README.md,sha256=qJu4dCGpDP-uilFBY8PdWHLJ6E1UfvA5oILu08ly6Jo,432
+flatmachines/assets/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+flatmachines/assets/flatagent.d.ts,sha256=ySivpR-8zoKYWSRRlKOIXSvXr8Hq6Vli77yJADCNZO4,7012
+flatmachines/assets/flatagent.schema.json,sha256=r9xii0Bu5pIS-93i4JwlxgK-0LaFkcIruQgpUUSz9sw,5558
+flatmachines/assets/flatagent.slim.d.ts,sha256=Akgv7VCMrTJQBa_TQvXaKyE3tCBXcsX55I4m52apSA4,1505
+flatmachines/assets/flatagents-runtime.d.ts,sha256=45YJYcbKLJG1PlgXVG3cB-esyWceY_ztO9hO3hwSuvM,15499
+flatmachines/assets/flatagents-runtime.schema.json,sha256=qQGnLY_JBSHPo_hlHvyzzRb4Z0oIBJlVN-wkol2alkY,10300
+flatmachines/assets/flatagents-runtime.slim.d.ts,sha256=LCVW_hiumG4Mh7vd97EcRX4Ymt1sB1mMN8SzOe32FeI,6159
+flatmachines/assets/flatmachine.d.ts,sha256=eOLw6X6ddIJvMJU9qOExiU4tPDDsOCjKjwQWXD1Bo9o,12213
+flatmachines/assets/flatmachine.schema.json,sha256=t-lVb343vZohbrLiKDdSbgnBXk8HFQ4NqQ9pvhSH6yg,13198
+flatmachines/assets/flatmachine.slim.d.ts,sha256=kpbMP2hDbzaibpKi6rop5ZOorL-kWepBMcNE7mjyggw,2921
+flatmachines/assets/profiles.d.ts,sha256=cY_7Rgpqb7kJwGo2VJTrCWzLqB32uJS6SwLI84Tu0I0,4109
+flatmachines/assets/profiles.schema.json,sha256=lLvt2rP9MlSLmzR98Kqa4QdntStmW9xHJbvQsD5rdu4,1920
+flatmachines/assets/profiles.slim.d.ts,sha256=MUXEstEAlX8nEumqOtp902SxUpii23oxndgf685nguc,670
+flatmachines/expressions/__init__.py,sha256=b37KlVgmCbKTj4Hz2_koGEIouZSaXy0jcSa7hw0rTXM,1685
+flatmachines/expressions/cel.py,sha256=W2bQa6D27VYfYWZ5VA5MLbXww7CA7zSBYfezE3pRvWE,3131
+flatmachines/expressions/simple.py,sha256=zLZHcRXb62qITAomMxOedfCvIthxVSyIH5MtNesFrIc,5774
+flatmachines-1.0.0.dist-info/METADATA,sha256=SzKtoxqsJpl1whDfhAY3Oet4e73sEDSc7_qkdM7dLqQ,13261
+flatmachines-1.0.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+flatmachines-1.0.0.dist-info/RECORD,,

flatmachines-1.0.0.dist-info/WHEEL

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