Skip to content

agent_spec.md

Latest commit

 

History

History
93 lines (81 loc) · 2.81 KB

agent_spec.md

File metadata and controls

93 lines (81 loc) · 2.81 KB

Coding Agent Specification — PDL v5.1 MVP (Predictor)

This specification assumes the agent has ONLY the contents of this repository.

Goal

Produce a runnable MVP that:

  • Loads and validates a PDL v5.1 YAML design
  • Executes intents (series of related prompts)
  • Supports sequential + parallel intent chaining via next
  • Exposes:
    • CLI commands (run/serve/validate/models)
    • Server API (runs lifecycle)
    • Logs accessible by REST and streamable by WebSocket
    • HTML preview UI that renders intents and can run them

Working agreements

  • Keep files concise and executable.
  • Prefer clarity over abstraction.
  • Maintain backward compatibility with PDL v5.1 schema.
  • After every change, run:
    • python scripts/validate_spec.py specs/app.mock.yaml
    • python scripts/smoke_test.py
    • python scripts/smoke_server.py (if network ports allowed)
    • python -m unittest -q

Step-by-step build plan

Step 1 — Create the project tree

pdl/
  __init__.py
  __main__.py
  cli.py
  server.py
  core/
    __init__.py
    loader.py
    schema.py
    model_adapter.py
    engine.py
    run_manager.py
  logging/
    __init__.py
    logstore.py
  web/
    templates/preview.html
    static/{preview.js,preview.css}
  schema/
    pdl_v5_1.schema.yaml
specs/{app.yaml,app.mock.yaml}
docs/{supported_models.md,validation_checklist.md}
scripts/{validate_spec.py,smoke_test.py,smoke_server.py,make_zip.py}
tests/test_engine_basic.py

Step 2 — Schema validation (non-negotiable)

  • JSON Schema validation via jsonschema
  • Uniqueness of intent ids
  • next references must exist

Step 3 — Model adapters

  • mock: deterministic, always available
  • ollama: POST /api/generate, stream:false, GET /api/tags
  • openai: POST /v1/responses (Responses API), GET /models
  • custom: model.interface.{endpoint, headers, request_template, response_path}

Step 4 — Engine

  • entry_intent defaults to intents[0].id
  • Sequential: next string → run next intent with updated context
  • Parallel: next list → asyncio.gather, merge outputs
  • Log every intent begin/end, each prompt step, model response (truncated)

Step 5 — LogStore

  • Per-run log list (REST callable)
  • Queue subscriptions (WebSocket streamable)
  • Sentinel: [RUN][DONE] ends the stream

Step 6 — Server

  • POST /runs → background task, returns run_id
  • GET /runs/{run_id} → status/result polling
  • WS /runs/{run_id}/logs/stream → live log streaming
  • GET /preview → Jinja2 HTML preview

Step 7 — CLI

  • validate / run / serve / models

Iteration loop (use verbatim)

  1. Restate the requested change as a single sentence.
  2. Update schema + mock spec first.
  3. Implement minimal code changes.
  4. Run: validate → smoke_test → unittest → smoke_server.
  5. Update docs if behavior changed.
  6. Confirm mock mode still works without external dependencies.