andon-ai 0.1.0__tar.gz

andon_ai-0.1.0/.gitignore

@@ -0,0 +1,50 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+
+# Environment
+.env
+.env.*
+
+# IDE
+.vscode/*
+!.vscode/settings.json
+.idea/
+.claude/
+
+# OS
+.DS_Store
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Node (frontend)
+node_modules/
+web/dist/
+
+# Local storage data dirs for LocalFileService / LocalGitStore. Path
+# depends on cwd: ``./storage`` from project root, ``./storage`` from
+# backend/. Anchor each so we don't accidentally ignore Python
+# packages named ``storage`` (e.g. ``backend/src/connections/storage/``
+# for the S3 provider).
+/storage/
+/backend/storage/
+
+# Logfire
+.logfire/
+
+# Large test assets (downloaded on demand)
+backend/tests/assets/nvda-*
+
+# denials triage demo patient documents are generated locally from anonymized seed data.
+sdk/examples/denials_triage/andon/data/patient/
+
+# Local demo run state.
+.demo/
+sdk/examples/denials_triage/.demo/

andon_ai-0.1.0/AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

andon_ai-0.1.0/CLAUDE.md

@@ -0,0 +1,122 @@
+# CLAUDE.md
+
+Andon SDK is the public authoring surface for workflows, agents, tools,
+connections, and the CLI used to validate and deploy them.
+
+## Documentation Ownership
+
+- `README.md` is the release-facing introduction and tutorial. Keep its
+  examples small, executable, and limited to product capabilities offered to
+  authors.
+- `andon_dsl/docs/authoring.md` is the exact workspace-authoring contract
+  shipped in the wheel and printed by `andon docs`. Put DSL rules, durability
+  semantics, limits, and sharp edges there.
+- Platform tool stubs and their docstrings are the capability contract printed
+  by `andon tools`. Do not duplicate tool signatures or provider details in
+  the README or generated agent guidance.
+- `andon_dsl/workspace/template.py` seeds the workspace `andon/AGENTS.md`. Keep
+  that guide concise and route coding agents to `andon docs` and `andon tools`
+  for version-matched contracts.
+- `examples/` holds demo workspaces that live only in this repo; they are
+  excluded from the published package. Every example workflow must validate
+  and compile against the current SDK and be exercised by a test — fix or
+  delete an example rather than letting it drift.
+
+## Workflow Authoring
+
+- Keep `@workflow`, `@step`, `@tool`, and `Agent(...)` declarations at module
+  scope. Agent declarations must be direct module-level assignments like
+  `extractor = Agent(...)` so deploy-time discovery can give them stable
+  identities.
+- Workflow bodies describe durable orchestration. Use `branch(...)`, `map(...)`,
+  `loop(...)`, `wait_for_event(...)`, and `run_workflow(...)` for control flow;
+  put normal Python branching, loops, parsing, and API glue inside `@step`
+  bodies.
+- Agent prompt templates are Handlebars over the typed `inputs` object
+  (computed fields included): `{{claim.patient.name}}` paths, `{{#if}}` /
+  `{{#each}}` blocks, and the `{{json field}}` helper for embedding a field
+  as pretty-printed JSON. Rendering is strict (a missing path fails the
+  run). Statically known call-site templates are validated against the
+  agent's `input_type` during deploy; every rendered template is validated
+  again at dispatch. The contract lives in `andon_dsl.agents.templates`.
+  Agent calls accept the same text/image/document `Prompt` shape as
+  `ctx.prompt`; rendering applies to text parts. Do not use Python
+  `str.format` braces in agent prompts; write a literal `{{` as `\{{`.
+- `Agent(output_type=...)` and `Agent(output_schema_field=...)` are mutually
+  exclusive. `output_schema_field` names an input field whose value is a JSON
+  Schema dict for the full agent output. `output_type` may be a union; prefer a
+  discriminated union when variants share fields.
+- `output_validators=[fn]` functions receive `(inputs, output)` after type or
+  schema validation. Raise `AgentRetryError` when the model should repair the
+  output. Return a replacement output to normalize it, or `None` to keep the
+  current value. Ordinary exceptions, including `ValueError`, are treated as
+  validator bugs and fail the run. Validators should be deterministic in
+  `(inputs, output)` because validation may re-run against a cached model
+  response during replay.
+- Error types mean different things: `AgentRetryError` is feedback to the model
+  for tool calls and output validators; `StepRetryError` consumes the step
+  retry budget; `UserReadableError` fails with a user-safe message; ordinary
+  exceptions are internal failures. Use a typed agent result for expected
+  recoverable outcomes; `UserReadableError` is a terminal run failure rather
+  than step-level fallback control flow.
+- `Agent(code_mode=True)` loads typed cell inputs through `get_inputs()` and
+  finalizes through `SUBMIT(result=...)`. Injected tools are keyword-only;
+  await those rendered as `async def` in the `run_code` catalog.
+  `get_inputs()` and `SUBMIT(...)` are synchronous. A plain text answer is not
+  a final structured result. `SUBMIT` runs declared type/schema checks
+  immediately; custom output validators run after submission while the agent
+  can still retry.
+- Deployed workflow execution validates declared output contracts in the
+  sandbox, where the original user classes and validators exist. Runtime code
+  outside the artifact may see metadata-only specs for deployed tools and
+  validators, not live Python callables.
+
+## Tools And Files
+
+- Use `@tool` for model-callable helpers. Tool bodies should raise
+  `AgentRetryError` only for bad model-supplied arguments the model can
+  repair (malformed input, an id the model invented). A legitimate miss
+  ("no catalog entry for this code") is a result, not an error: return an
+  empty list or `None` and put "an empty result is the final answer — do
+  not retry" guidance in the docstring. Retry feedback is budgeted by
+  `Agent(retries=N)`; a raise that fires on valid data can exhaust the
+  budget and fail the run on a normal domain outcome. Rule of thumb: an
+  `AgentRetryError` should be unreachable for a well-behaved model
+  operating on valid data.
+- Platform tools in `andon_dsl.tools` are SDK stubs; their implementations run
+  in the platform runtime. Keep user-authored workflow logic in the workflow
+  package, not in platform stubs.
+- Give agents `web_search`/`web_fetch` for web browsing. Use
+  `fetch_to_file_ref` when an external URL must become a `FileRef` for
+  document tools or later workflow steps. Large payload spillover belongs in
+  runtime payload handling, not in web browsing stubs.
+- Put document `FileRef` fields on the agent's typed inputs. A `FileRef`
+  renders as its `andon://...` URI in prompt templates and context blocks;
+  tell the model to pass that URI unchanged to typed tool arguments such as
+  `read_document(file=...)`. File metadata and bytes stay behind the runtime
+  reference. Keep the workflow and agent fields typed as `FileRef`; the CLI
+  accepts local paths at those schema positions and uploads them before run
+  creation.
+- `StrategyFile(...)` paths resolve relative to the file that defines the
+  agent and must point to markdown files under `andon/prompts`.
+
+## Validation
+
+- Promote invariants into the SDK-time validator whenever the artifact tree
+  carries enough information to check them.
+- Keep executable-body validation source-only. Resolve step/tool names with
+  Python lexical scoping, require workspace imports to resolve inside the
+  deployed tree, reject wildcard and platform-internal imports, and leave
+  third-party package availability to `andon.toml` `[sandbox] packages`.
+- Workflow primitives run only in `@workflow` bodies. User-authored `@step`
+  and `@tool` contexts expose `connect`, `prompt`, artifact I/O, and document
+  reads; validate direct context-member calls against that runtime surface.
+- Extend learning and evaluation capabilities through compile-discovered named
+  code artifacts or platform stores keyed by structured definition, call-site,
+  and execution references. Keep domain semantics such as metrics, confidence,
+  verdicts, corrections, and datasets out of workflow IR node types.
+- Keep source coordinates on validation errors: file, module path, binding or
+  function name, and line.
+- When a step or tool footgun recurs, constrain its body shape at validation
+  time or add an explicit DSL primitive instead of leaving it to fail in the
+  sandbox.

andon_ai-0.1.0/PKG-INFO

@@ -0,0 +1,244 @@
+Metadata-Version: 2.4
+Name: andon-ai
+Version: 0.1.0
+Summary: Andon SDK and CLI for authoring, deploying, and running workflows
+Requires-Python: >=3.13
+Requires-Dist: httpx>=0.28
+Requires-Dist: packaging>=24.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: typing-extensions>=4.15
+Description-Content-Type: text/markdown
+
+# Andon SDK and CLI (`andon-ai`)
+
+Andon is a Python SDK for building durable, document-centric workflows with
+typed steps, LLM agents, human review, and integrations. Authors define the
+workflow; the Andon platform handles execution, checkpointing, files, and
+operations.
+
+Installing `andon-ai` provides the `andon` command and the `andon_dsl` Python
+package. Python 3.13 or newer and [uv](https://docs.astral.sh/uv/) are required.
+
+## Create a workspace
+
+Start in an empty directory:
+
+```bash
+mkdir claims-workflow
+cd claims-workflow
+uvx andon-ai init
+uv sync
+```
+
+`andon init` creates `andon.toml`, a deployable `andon/` package, a sample
+workflow and test, and local project configuration. It preserves files that
+already exist, so an empty directory is the supported starting point.
+
+The generated `AGENTS.md` routes coding agents to the authoring contract and
+tool catalog that match the installed SDK.
+
+## Build an email workflow
+
+This workflow reads unread Gmail messages, summarizes them with an agent, and
+emails the digest. Save it as `andon/workflows/inbox.py`:
+
+```python
+from dataclasses import dataclass
+
+from andon_dsl.agents import Agent, StepContext
+from andon_dsl.integrations import EmailFilter, EmailMessage, Gmail
+from andon_dsl.workflows import map, step, workflow
+
+
+@dataclass
+class InboxInput:
+    recipient: str
+    limit: int = 10
+
+
+@dataclass
+class EmailSummary:
+    sender: str
+    subject: str
+    summary: str
+
+
+summarizer = Agent(
+    model_family="small",
+    input_type=EmailMessage,
+    output_type=EmailSummary,
+    system_instructions="Summarize inbound email clearly and concisely.",
+)
+
+
+@step(connections=["gmail"])
+async def read_inbox(ctx: StepContext, input: InboxInput) -> list[EmailMessage]:
+    gmail = await ctx.connect(Gmail, "gmail")
+    return await gmail.list_messages(
+        filter=EmailFilter(is_unread=True),
+        limit=input.limit,
+    )
+
+
+@step
+async def summarize(message: EmailMessage) -> EmailSummary:
+    return await summarizer(
+        "Summarize this email from {{sender}}.\n"
+        "Subject: {{subject}}\n\n"
+        "{{body_text}}",
+        inputs=message,
+    )
+
+
+@step(connections=["gmail"])
+async def send_digest(
+    ctx: StepContext,
+    recipient: str,
+    summaries: list[EmailSummary],
+) -> str:
+    gmail = await ctx.connect(Gmail, "gmail")
+    body = "\n\n".join(
+        f"{item.subject} — {item.sender}\n{item.summary}" for item in summaries
+    )
+    return await gmail.send(
+        to=[recipient],
+        subject="Andon inbox digest",
+        body=body or "No unread messages.",
+    )
+
+
+@workflow()
+def process_inbox(input: InboxInput) -> str:
+    messages = read_inbox(input)
+    summaries = map(summarize, messages)
+    return send_digest(input.recipient, summaries)
+```
+
+Declare the workflow in `andon.toml`:
+
+```toml
+[[workflows]]
+name = "process_inbox"
+path = "andon/workflows/inbox.py"
+```
+
+The connection name passed to `ctx.connect()` refers to Gmail credentials
+configured for the current Andon organization. The same name must appear in
+the step's `connections=[...]` allow-list.
+
+## Core concepts
+
+- **Workflows** are declarative graphs of steps and control-flow primitives.
+  Their bodies are traced during deployment and do not run as ordinary Python
+  during workflow execution.
+- **Steps** are typed Python functions and the durability boundary. Successful
+  results are checkpointed; external side effects should be safe to repeat if
+  an interrupted attempt runs again.
+- **Agents** are typed LLM-powered components declared at module scope and
+  awaited inside steps. Runtime prompts are Handlebars templates over the
+  agent's typed inputs.
+- **Tools and toolsets** give agents explicitly selected capabilities. Andon
+  provides platform tools and curated toolsets, and authors can define their
+  own model-callable functions with `@tool`.
+- **Connections** provide typed access to organization-configured email through
+  the Gmail protocol without exposing credentials to workflow code.
+- **FileRef** values represent uploaded files and generated artifacts. Keep
+  documents and large intermediate outputs behind `FileRef` rather than
+  passing their bytes or full text through step results.
+
+Workflow bodies use primitives such as `map`, `parallel`, `branch`, `loop`,
+`wait_for_event`, `wait_for_review`, `sleep`, and `run_workflow`. Put ordinary
+Python branching, iteration, parsing, and integration glue inside steps.
+
+## Tools and toolsets
+
+Platform tools and curated toolsets are imported from `andon_dsl.tools` and
+opted into an agent through `tools=[...]`. Authors can combine them with their
+own `@tool` functions:
+
+```python
+from andon_dsl.agents import Agent
+from andon_dsl.tools import tool
+from andon_dsl.tools.toolsets import document_analysis
+
+
+@tool
+def normalize_vendor_name(name: str) -> str:
+    """Return a normalized vendor name for matching."""
+    return " ".join(name.lower().split())
+
+
+analyst = Agent(
+    tools=[*document_analysis.tools, normalize_vendor_name],
+)
+```
+
+The installed SDK is the source of truth for platform capabilities:
+
+```bash
+uv run andon tools         # print tools, toolsets, signatures, and descriptions
+uv run andon tools --json  # emit the same catalog as structured JSON
+```
+
+## Validate, deploy, and run
+
+An organization admin creates API keys in the console's
+[Settings page](https://app.andonai.com/settings). Keys carry a role:
+`admin` keys can deploy and activate; `operator` keys can start and watch
+runs. Expose the key to the CLI:
+
+```bash
+export ANDON_API_KEY="ak-..."
+```
+
+The CLI uses `https://app.andonai.com/` by default. Set `ANDON_API_URL` only
+when targeting a different Andon environment.
+
+```bash
+uv run andon validate
+uv run pytest
+uv run andon deploy --no-activate
+uv run andon run process_inbox \
+  --deployment-id <deployment-id> \
+  --input-json '{"recipient":"ops@example.com","limit":10}'
+uv run andon runs watch <run-id>
+```
+
+`andon validate` performs local manifest and static source validation.
+`andon deploy` publishes the full local `andon.toml` plus `andon/` snapshot,
+compiles and type-checks its workflows, and activates the deployment unless
+`--no-activate` is passed. Publishing replaces the remote workspace snapshot,
+so remote files absent from the local tree are deleted.
+
+`andon run` starts a deployed workflow. Local paths supplied at typed
+`FileRef` input positions are uploaded before run creation.
+
+## Authoring reference
+
+Use the references bundled with the installed SDK before editing a workspace:
+
+```bash
+uv run andon docs
+uv run andon tools
+```
+
+Here `uv run` executes a command in the workspace environment, while
+`andon docs` prints the complete, version-matched authoring contract to the
+terminal. It is separate from `andon run <workflow>`, which starts a workflow
+run.
+
+The authoring contract covers workflow restrictions, primitives, durable
+identity, retries, agent settings, files, reference data, testing, and other
+sharp edges. The generated `andon/AGENTS.md` points coding agents to this
+contract and the installed tool catalog.
+
+## Public imports
+
+| Package | Purpose |
+|---|---|
+| `andon_dsl.workflows` | Workflow and step decorators plus control-flow primitives. |
+| `andon_dsl.agents` | Agent declarations, prompt content, contexts, model settings, and usage limits. |
+| `andon_dsl.tools` | User-authored tools and platform tool stubs; curated bundles live in `andon_dsl.tools.toolsets`. |
+| `andon_dsl.resources` | `FileRef`, document result types, reference data helpers, and schema extensions. |
+| `andon_dsl.integrations` | The Gmail connection protocol and shared email types for `ctx.connect()`. |
+| `andon_dsl.errors` | Public authoring and execution error types. |

andon_ai-0.1.0/README.md

@@ -0,0 +1,233 @@
+# Andon SDK and CLI (`andon-ai`)
+
+Andon is a Python SDK for building durable, document-centric workflows with
+typed steps, LLM agents, human review, and integrations. Authors define the
+workflow; the Andon platform handles execution, checkpointing, files, and
+operations.
+
+Installing `andon-ai` provides the `andon` command and the `andon_dsl` Python
+package. Python 3.13 or newer and [uv](https://docs.astral.sh/uv/) are required.
+
+## Create a workspace
+
+Start in an empty directory:
+
+```bash
+mkdir claims-workflow
+cd claims-workflow
+uvx andon-ai init
+uv sync
+```
+
+`andon init` creates `andon.toml`, a deployable `andon/` package, a sample
+workflow and test, and local project configuration. It preserves files that
+already exist, so an empty directory is the supported starting point.
+
+The generated `AGENTS.md` routes coding agents to the authoring contract and
+tool catalog that match the installed SDK.
+
+## Build an email workflow
+
+This workflow reads unread Gmail messages, summarizes them with an agent, and
+emails the digest. Save it as `andon/workflows/inbox.py`:
+
+```python
+from dataclasses import dataclass
+
+from andon_dsl.agents import Agent, StepContext
+from andon_dsl.integrations import EmailFilter, EmailMessage, Gmail
+from andon_dsl.workflows import map, step, workflow
+
+
+@dataclass
+class InboxInput:
+    recipient: str
+    limit: int = 10
+
+
+@dataclass
+class EmailSummary:
+    sender: str
+    subject: str
+    summary: str
+
+
+summarizer = Agent(
+    model_family="small",
+    input_type=EmailMessage,
+    output_type=EmailSummary,
+    system_instructions="Summarize inbound email clearly and concisely.",
+)
+
+
+@step(connections=["gmail"])
+async def read_inbox(ctx: StepContext, input: InboxInput) -> list[EmailMessage]:
+    gmail = await ctx.connect(Gmail, "gmail")
+    return await gmail.list_messages(
+        filter=EmailFilter(is_unread=True),
+        limit=input.limit,
+    )
+
+
+@step
+async def summarize(message: EmailMessage) -> EmailSummary:
+    return await summarizer(
+        "Summarize this email from {{sender}}.\n"
+        "Subject: {{subject}}\n\n"
+        "{{body_text}}",
+        inputs=message,
+    )
+
+
+@step(connections=["gmail"])
+async def send_digest(
+    ctx: StepContext,
+    recipient: str,
+    summaries: list[EmailSummary],
+) -> str:
+    gmail = await ctx.connect(Gmail, "gmail")
+    body = "\n\n".join(
+        f"{item.subject} — {item.sender}\n{item.summary}" for item in summaries
+    )
+    return await gmail.send(
+        to=[recipient],
+        subject="Andon inbox digest",
+        body=body or "No unread messages.",
+    )
+
+
+@workflow()
+def process_inbox(input: InboxInput) -> str:
+    messages = read_inbox(input)
+    summaries = map(summarize, messages)
+    return send_digest(input.recipient, summaries)
+```
+
+Declare the workflow in `andon.toml`:
+
+```toml
+[[workflows]]
+name = "process_inbox"
+path = "andon/workflows/inbox.py"
+```
+
+The connection name passed to `ctx.connect()` refers to Gmail credentials
+configured for the current Andon organization. The same name must appear in
+the step's `connections=[...]` allow-list.
+
+## Core concepts
+
+- **Workflows** are declarative graphs of steps and control-flow primitives.
+  Their bodies are traced during deployment and do not run as ordinary Python
+  during workflow execution.
+- **Steps** are typed Python functions and the durability boundary. Successful
+  results are checkpointed; external side effects should be safe to repeat if
+  an interrupted attempt runs again.
+- **Agents** are typed LLM-powered components declared at module scope and
+  awaited inside steps. Runtime prompts are Handlebars templates over the
+  agent's typed inputs.
+- **Tools and toolsets** give agents explicitly selected capabilities. Andon
+  provides platform tools and curated toolsets, and authors can define their
+  own model-callable functions with `@tool`.
+- **Connections** provide typed access to organization-configured email through
+  the Gmail protocol without exposing credentials to workflow code.
+- **FileRef** values represent uploaded files and generated artifacts. Keep
+  documents and large intermediate outputs behind `FileRef` rather than
+  passing their bytes or full text through step results.
+
+Workflow bodies use primitives such as `map`, `parallel`, `branch`, `loop`,
+`wait_for_event`, `wait_for_review`, `sleep`, and `run_workflow`. Put ordinary
+Python branching, iteration, parsing, and integration glue inside steps.
+
+## Tools and toolsets
+
+Platform tools and curated toolsets are imported from `andon_dsl.tools` and
+opted into an agent through `tools=[...]`. Authors can combine them with their
+own `@tool` functions:
+
+```python
+from andon_dsl.agents import Agent
+from andon_dsl.tools import tool
+from andon_dsl.tools.toolsets import document_analysis
+
+
+@tool
+def normalize_vendor_name(name: str) -> str:
+    """Return a normalized vendor name for matching."""
+    return " ".join(name.lower().split())
+
+
+analyst = Agent(
+    tools=[*document_analysis.tools, normalize_vendor_name],
+)
+```
+
+The installed SDK is the source of truth for platform capabilities:
+
+```bash
+uv run andon tools         # print tools, toolsets, signatures, and descriptions
+uv run andon tools --json  # emit the same catalog as structured JSON
+```
+
+## Validate, deploy, and run
+
+An organization admin creates API keys in the console's
+[Settings page](https://app.andonai.com/settings). Keys carry a role:
+`admin` keys can deploy and activate; `operator` keys can start and watch
+runs. Expose the key to the CLI:
+
+```bash
+export ANDON_API_KEY="ak-..."
+```
+
+The CLI uses `https://app.andonai.com/` by default. Set `ANDON_API_URL` only
+when targeting a different Andon environment.
+
+```bash
+uv run andon validate
+uv run pytest
+uv run andon deploy --no-activate
+uv run andon run process_inbox \
+  --deployment-id <deployment-id> \
+  --input-json '{"recipient":"ops@example.com","limit":10}'
+uv run andon runs watch <run-id>
+```
+
+`andon validate` performs local manifest and static source validation.
+`andon deploy` publishes the full local `andon.toml` plus `andon/` snapshot,
+compiles and type-checks its workflows, and activates the deployment unless
+`--no-activate` is passed. Publishing replaces the remote workspace snapshot,
+so remote files absent from the local tree are deleted.
+
+`andon run` starts a deployed workflow. Local paths supplied at typed
+`FileRef` input positions are uploaded before run creation.
+
+## Authoring reference
+
+Use the references bundled with the installed SDK before editing a workspace:
+
+```bash
+uv run andon docs
+uv run andon tools
+```
+
+Here `uv run` executes a command in the workspace environment, while
+`andon docs` prints the complete, version-matched authoring contract to the
+terminal. It is separate from `andon run <workflow>`, which starts a workflow
+run.
+
+The authoring contract covers workflow restrictions, primitives, durable
+identity, retries, agent settings, files, reference data, testing, and other
+sharp edges. The generated `andon/AGENTS.md` points coding agents to this
+contract and the installed tool catalog.
+
+## Public imports
+
+| Package | Purpose |
+|---|---|
+| `andon_dsl.workflows` | Workflow and step decorators plus control-flow primitives. |
+| `andon_dsl.agents` | Agent declarations, prompt content, contexts, model settings, and usage limits. |
+| `andon_dsl.tools` | User-authored tools and platform tool stubs; curated bundles live in `andon_dsl.tools.toolsets`. |
+| `andon_dsl.resources` | `FileRef`, document result types, reference data helpers, and schema extensions. |
+| `andon_dsl.integrations` | The Gmail connection protocol and shared email types for `ctx.connect()`. |
+| `andon_dsl.errors` | Public authoring and execution error types. |

andon_ai-0.1.0/andon_cli/__init__.py

@@ -0,0 +1,7 @@
+"""Andon workflow authoring CLI."""
+
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

andon_ai-0.1.0/andon_cli/__main__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from andon_cli.main import entrypoint
+
+entrypoint()