Metadata-Version: 2.4
Name: forma-lang
Version: 0.1.0
Summary: Python runtime for the Forma language
Project-URL: Homepage, https://github.com/syndicalt/forma
Project-URL: Repository, https://github.com/syndicalt/forma
Author: Forma contributors
License-Expression: MIT
Keywords: agent,contracts,forma,runtime
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# forma-lang

Python runtime package for Forma task files.

The package exposes `FormaRuntime` for executing Forma source, `ModelProvider`
for custom adapters, `HttpJsonProvider` for HTTP JSON model endpoints,
`OpenAIResponsesProvider` for OpenAI Responses API execution, and
`StaticProvider` and `RecordingProvider` for deterministic tests of agent
blocks. The current runtime supports the MVP task shape used by the shared
conformance fixtures:

- deterministic `compute` blocks that produce a `message` from `user_name`
- `verify` checks for `message.length > 0` and `message.words <= 12`
- `agent` blocks executed through an explicit fake provider such as
  `StaticProvider`

```python
from forma import FormaRuntime, StaticProvider

runtime = FormaRuntime(
    model_provider=StaticProvider({"message": "Hello, Sam. Good to see you."})
)

result = runtime.run_source(source, input={"user_name": "Sam"}, source_name="task.forma")
```

Use `RecordingProvider` when tests need to assert which instruction, input,
permissions, and output contract the runtime sent to the provider.

`run_source` returns a `FormaResult` with `ok`, `output`, `trace`,
`diagnostics`, `verification`, and `error` fields.

For real agent execution, keep the provider key and model name in the host
program or environment, then pass a provider object to `FormaRuntime`. The
runtime calls `run_agent(instruction, values, permissions, tools, output,
schemas)` when it reaches the task's `agent` block; providers that only accept
the original four arguments still work. Providers call `tools.require("read")`
or another declared permission before host workspace actions. Use
`run_task(source, "task_name", input, source_name)` when source text contains
multiple tasks, or `run_file(path, "task_name", input)` when the contract lives
on disk.

## Local Checks

Run the Python package tests from the repository root:

```bash
python -m pytest packages/forma-python/tests -q
```

For workspace-level validation, also run:

```bash
corepack pnpm check
```
