Skip to main content

grain-sdk

Python SDK for Grain — a structured data format for describing AI agents.

Install

pip install grain-sdk

Usage

from grain import Grain

# Load from file
agent = Grain.load("./my-agent.agent.yaml")

# Generate system prompt
prompt = agent.to_prompt()

# Channel-specific prompt
slack_prompt = agent.to_prompt("slack")

# Clean YAML for LLM consumption (strips metadata)
yaml = agent.to_string()

Create programmatically

from grain import Grain

agent = (
    Grain.create("my-bot", name="My Bot", description="Does helpful things")
    .set_personality("warmth", 0.8)
    .set_personality("confidence", 0.9)
    .add_rule({
        "id": "always-greet",
        "condition": {"type": "always"},
        "action": {"type": "respond-with-style", "style": {"warmth": 0.9}},
    })
    .add_boundary({
        "description": "Never share internal data",
        "category": "data",
        "enforcement": "hard",
        "onViolation": "refuse",
    })
    .add_tool({"id": "search", "usage": "Search knowledge base"})
)

print(agent.to_prompt())

Immutable mutations

Every method returns a new Grain — the original is never modified.

base = Grain.create("my-bot")
with_rule = base.add_rule({"id": "r1", "condition": {"type": "always"}, "action": {"type": "require-confirmation"}})

len(base.rules)       # 0
len(with_rule.rules)  # 1

With any LLM provider

from grain import Grain
from openai import OpenAI

agent = Grain.load("./my-agent.agent.yaml")
client = OpenAI()

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": agent.to_prompt()},
        {"role": "user", "content": "Hello!"}
    ]
)

Merge and diff

a = Grain.create("bot-a").set_personality("warmth", 0.3)
b = Grain.create("bot-b").set_personality("warmth", 0.9)

merged = a.merge(b)   # b wins on conflicts
changes = a.diff(b)    # {"voice.personality.warmth": {"before": 0.3, "after": 0.9}}

Minimal Spec

specVersion: "1.0"
id: my-bot
version: 1.0.0
meta:
  name: My Bot
  description: Does helpful things

API

Constructors

  • Grain.create(id, *, name=None, description="") — Create with defaults
  • Grain.from_string(yaml_or_json) — Parse from string
  • Grain.load(file_path) — Load from file
  • Grain.of(spec_dict) — Wrap a plain dict

Mutations (return new Grain)

  • add_rule(rule) / remove_rule(id) / add_rules(rules)
  • add_boundary(b) / remove_boundary(desc) / add_boundaries(bs)
  • add_tool(t) / remove_tool(name) / add_tools(ts)
  • add_skill(s) / remove_skill(name) / add_skills(ss)
  • add_expertise(domain, proficiency) / remove_expertise(domain)
  • set_personality(dim, value) — validates 0-1 range
  • set(path, value) / get(path) — generic deep access
  • merge(other) — deep merge, other wins

Properties

  • id, name, version — scalars
  • personality, rules, boundaries, tools, skills, expertise — copies
  • data — raw dict
  • is_valid — boolean

Queries

  • has_rule(id), has_tool(name), has_skill(name)

Output

  • to_string(channel=None) — Clean YAML for LLMs (strips metadata)
  • to_prompt(channel=None) — Natural language system prompt
  • to_yaml() — Full YAML with all metadata
  • to_json() — Full JSON
  • validate() — Returns list[ValidationError]
  • diff(other) — Structural diff

Presets

  • Presets.personality["professional"]
  • Presets.personality["friendly"]
  • Presets.personality["expert"]
  • Presets.personality["creative"]
  • Presets.personality["executor"]

License

MIT

Metadata

Release files for grain-sdk 0.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for grain-sdk 0.2.1
File Size Uploaded Provenance Actions
grain_sdk-0.2.1.tar.gz 23.4 kB Without provenance Details for grain_sdk-0.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for grain-sdk 0.2.1
File Interpreter ABI Platform Actions
grain_sdk-0.2.1-py3-none-any.whl Python 3 none any Details for grain_sdk-0.2.1-py3-none-any.whl

Total release size: 44.4 kB

Release files / grain_sdk-0.2.1.tar.gz

Download URL grain_sdk-0.2.1.tar.gz
Size 23.4 kB
Tags Source
SHA-256 checksum
How to use checksums
36c7d25c74b440eaa25a8088edec9dc0a3f567189b8f654a140d122e739e21d9
BLAKE2b-256 checksum
How to use checksums
e61064f9ed5d3186ba5ca967bcd6032634ebabe8122b7612f35cdb9a4bf55993
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.3

Release files / grain_sdk-0.2.1-py3-none-any.whl

Download URL grain_sdk-0.2.1-py3-none-any.whl
Size 21.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6bc57e62382d7442944d58f82b6a9ca2eddb8841ffcb11ae5dc8a2474ef44931
BLAKE2b-256 checksum
How to use checksums
b9cee285d123e5a581b99d48c7b167dffa228019e462d88232fb6f2c38167fef
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.3

Security for grain-sdk 0.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page