Quickstart
==========

Install
-------

For package usage:

.. code-block:: bash

   pip install oas2mcp

For local development:

.. code-block:: bash

   pdm install -G test -G docs -G cli

The ``cli`` group includes the in-memory LangGraph API server extras required
for ``langgraph dev``.

Environment
-----------

Copy the example env file and set the values you need:

.. code-block:: bash

   cp .env.example .env

Required for the agent pipeline:

- ``OPENAI_API_KEY``

Optional for LangSmith tracing and LangGraph deployment:

- ``LANGSMITH_TRACING=true``
- ``LANGSMITH_API_KEY``
- ``LANGSMITH_PROJECT``
- ``LANGSMITH_WORKSPACE_ID``
- ``LANGSMITH_DEPLOYMENT_NAME``
- ``LANGSMITH_ENDPOINT`` for self-hosted LangSmith only

Optional for live upstream FastMCP calls:

- ``UPSTREAM_BEARER_TOKEN``
- ``UPSTREAM_API_KEY``
- ``UPSTREAM_API_KEY_HEADER``

Test
----

.. code-block:: bash

   pdm run pytest

Manual smoke checks
-------------------

Formal coverage now lives in ``tests/``. The scripts remain available for interactive inspection:

.. code-block:: bash

   pdm run python scripts/test_catalog_surface_planner_agent.py
   pdm run python scripts/test_orchestrator.py
   pdm run python scripts/test_fastmcp_bootstrap.py
   pdm run python scripts/test_fastmcp_server.py
   pdm run python scripts/test_fastmcp_client.py

LangGraph deployment
--------------------

The repository includes deployable graph entrypoints in
``src/oas2mcp/deploy/langgraph_app.py`` and a deployment config at
``config/langgraph.json``.

Run the LangGraph CLI commands from the repository root so the config's
``./src`` and ``./.env`` paths resolve correctly.

Install the CLI group:

.. code-block:: bash

   pdm install -G cli

Run the LangGraph dev server locally:

.. code-block:: bash

   pdm run langgraph dev --config config/langgraph.json --no-browser

The configured graphs are:

- ``enhance_catalog`` for the in-memory summarize/enhance/surface-planning pipeline
- ``enhance_and_export_catalog`` for the export pipeline that returns written artifact paths

Validate the deployment config:

.. code-block:: bash

   pdm run langgraph validate --config config/langgraph.json

Build or deploy with the LangGraph CLI:

.. code-block:: bash

   pdm run langgraph build --config config/langgraph.json -t oas2mcp
   pdm run langgraph deploy --config config/langgraph.json

Release workflow
----------------

The publishing flow is tag-driven. The local helper cuts a verified release
commit and annotated tag; the GitHub Actions release workflow then validates,
builds, publishes to PyPI, and creates the GitHub Release.

Cut the next local release in one command:

.. code-block:: bash

   pdm run release_cut_patch

You can replace ``patch`` with ``minor`` or ``major``. The helper:

- requires a clean worktree before starting
- updates the tracked version files together
- refreshes ``pdm.lock``
- runs ``pdm run release_check``
- creates the release commit
- creates the annotated ``vX.Y.Z`` tag

Push the commit and tag explicitly after the helper succeeds:

.. code-block:: bash

   git push origin main
   git push origin vX.Y.Z

Pushing the tag triggers ``.github/workflows/release.yml``, which:

- verifies the tag matches ``pyproject.toml``
- runs tests
- builds docs
- builds distributions
- publishes to PyPI
- creates the GitHub Release and attaches ``dist/*``