Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
223 lines (164 loc) · 7.83 KB

CONTRIBUTING.md

File metadata and controls

223 lines (164 loc) · 7.83 KB
Raw

Contributing to Open Agent Spec (OA) CLI

Thank you for your interest in contributing to OA CLI! This document provides guidelines and instructions for contributing.

Code of Conduct

By participating in this project, you agree to maintain a respectful and inclusive environment for everyone.

How to Contribute

Creating Agent Spec Files

The Open Agent Spec (OA) uses YAML files to define agent configurations. Use the canonical field open_agent_spec for the spec version (see README for the full schema). Here's how to create your own:

Basic Structure

open_agent_spec: "1.5.0"

agent:
  name: my-agent
  description: A fantastic agent that changes the world
  role: chat

intelligence:
  type: llm
  engine: openai
  endpoint: https://api.openai.com/v1
  model: gpt-4
  config:
    temperature: 0.7
    max_tokens: 1000

Required Fields

  1. open_agent_spec: Version of the OA specification (string, e.g. "1.0.9").

  2. agent section:

    • name: A unique identifier for your agent (kebab-case; will be converted to snake_case for Python)
    • description: A clear description of what your agent does
    • role: Optional free-form string; well-known values: analyst, reviewer, chat, retriever, planner, executor, commander, coordinator

  3. intelligence section:

    • engine: LLM provider (e.g. openai, anthropic, grok, cortex, codex, local, custom)
    • endpoint: The API endpoint for your LLM provider
    • model: The specific model to use (e.g. "gpt-4", "gpt-3.5-turbo")
    • config: Model-specific configuration
      • temperature: Controls randomness (0.0 to 1.0)
      • max_tokens: Maximum length of the response

Example Use Cases

  1. Trading Agent:
open_agent_spec: "1.5.0"

agent:
  name: market-analyzer
  description: An agent that analyzes market signals and provides trading recommendations
  role: analyst

intelligence:
  type: llm
  engine: openai
  endpoint: https://api.openai.com/v1
  model: gpt-4
  config:
    temperature: 0.3  # Lower temperature for more consistent outputs
    max_tokens: 2000  # Longer responses for detailed analysis
  1. Content Generator:
open_agent_spec: "1.5.0"

agent:
  name: content-creator
  description: An agent that generates creative content based on prompts
  role: chat

intelligence:
  type: llm
  engine: openai
  endpoint: https://api.openai.com/v1
  model: gpt-4
  config:
    temperature: 0.8  # Higher temperature for more creative outputs
    max_tokens: 1000

Best Practices

  1. Naming:

    • Use kebab-case for the agent name (e.g., market-analyzer)
    • Make names descriptive and unique
    • Avoid special characters

  2. Description:

    • Be clear and concise
    • Include the agent's primary purpose
    • Mention any key capabilities

  3. Configuration:

    • Adjust temperature based on task:
      • Lower (0.1-0.3) for analytical tasks
      • Higher (0.7-0.9) for creative tasks
    • Set max_tokens based on expected response length
    • Use appropriate model for your use case

  4. Validation:

    • Test your spec file with oa init --dry-run
    • Ensure all required fields are present
    • Check that values are of correct types

Adding a new template

Add a new YAML spec under oas_cli/templates/ (e.g. my-template.yaml). For scaffolding, reference it explicitly with oa init --spec path/to/your.yaml --output .... Overriding the templates directory (e.g. via an env var) is not currently supported. Document the template in the README “Built-in Templates” section.

Adding an agent-as-code example

To add a new .agents/ example to the repository:

  1. Create a YAML spec in .agents/ following the standard spec structure (see examples in that directory).
  2. Make sure open_agent_spec, agent, intelligence (including type: llm), tasks, and prompts are all present and valid.
  3. Validate with oa init --spec .agents/your-agent.yaml --output /tmp/test --dry-run.
  4. Document the agent in the table in docs/REFERENCE.md under “Agents as code”.

See the existing .agents/ci-failure-repair.yaml for a production-quality example that is wired into a GitHub Actions workflow.

Contributing Conformance Tests

The formal specification at spec/open-agent-spec-1.4.md defines what a conforming OA runtime MUST do. The conformance test suite at spec/conformance/cases/ operationalises those requirements — each test case validates a specific normative MUST/MUST NOT from the spec.

To add a conformance test:

  1. Identify the normative requirement (section number + MUST/MUST NOT keyword).
  2. Create a YAML case file under spec/conformance/cases/<category>/.
  3. The embedded spec MUST be self-contained and minimal — include only what the test needs.
  4. Mock responses MUST be provided — conformance tests MUST NOT make real API calls.
  5. Run the suite: python -m spec.conformance.harness.harness --adapter python --adapter node

See spec/conformance/README.md for the full test case format and category structure.

Key distinction: Conformance tests validate runtime behaviour against the spec, not implementation details. They should pass for any conforming OA runtime, not just the reference Python implementation.

Reporting Bugs

  • Check if the bug has already been reported in the Issues section
  • Use the bug report template
  • Include detailed steps to reproduce
  • Include expected and actual behavior
  • Add screenshots if applicable

Suggesting Features

  • Check if the feature has already been suggested
  • Use the feature request template
  • Explain the problem you're trying to solve
  • Describe your proposed solution
  • Include any relevant examples

Pull Requests

  1. Fork the repository
  2. Create a new branch (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Run tests: pytest tests/ (see Testing below)
  5. Commit your changes (git commit -m 'Add amazing feature')
  6. Push to the branch (git push origin feature/amazing-feature)
  7. Open a Pull Request

Development Setup

# Clone the repository
git clone https://github.com/prime-vector/open-agent-spec.git
cd open-agent-spec

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install development dependencies
pip install -e ".[dev]"

Code Style

  • Follow PEP 8 guidelines
  • Use type hints
  • Write docstrings for all functions and classes
  • Keep functions small and focused
  • Write meaningful commit messages

Testing

  • Run all tests: pytest tests/
  • Run conformance suite: python -m spec.conformance.harness.harness --adapter python
  • Write tests for new features; ensure all tests pass; maintain or improve test coverage.
  • Pytest marks: If you add a new test category, register the mark in pytest.ini (and optionally in pyproject.toml under [tool.pytest.ini_options] markers) so pytest -m <mark> works without "Unknown pytest.mark" warnings. Existing marks: contract, cortex, multi_engine, generator, integration, slow.
  • Spec version field: Use open_agent_spec (not spec_version) in YAML specs; this is the canonical field name used by the schema and code.

Documentation

  • Update README.md if needed
  • Add docstrings to new functions
  • Update any relevant documentation
  • Keep comments clear and helpful

Pull Request Process

  1. Fill in the PR template — What changed, Why, How tested.
  2. Update README.md and docs/ if your change affects user-facing behavior.
  3. Make sure CI passes (pytest tests/, ruff check ., ruff format --check .).
  4. One maintainer sign-off required for merge.

Questions?

Feel free to open an issue for any questions or concerns. We're here to help!

License

By contributing, you agree that your contributions will be licensed under the project's MIT License.