Metadata-Version: 2.5
Name: mcparser
Version: 0.2.0a1
Summary: Uses LLM agents to perform dependency parsing, with an MCP server over CoNLL-U corpora.
Project-URL: Homepage, https://github.com/rbturnbull/mcparser
Project-URL: Documentation, https://rbturnbull.github.io/mcparser
Project-URL: Repository, https://github.com/rbturnbull/mcparser
Project-URL: Issues, https://github.com/rbturnbull/mcparser/issues
Project-URL: Changelog, https://github.com/rbturnbull/mcparser/blob/main/CHANGELOG.md
Author-email: Robert Turnbull <robert.turnbull@unimelb.edu.au>
License: Apache-2.0
License-File: LICENSE
Keywords: agents,conllu,dependency parsing,linguistics,llm,mcp,nlp,universal dependencies
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Text Processing :: Linguistic
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: genai-prices>=0.1
Requires-Dist: mcp>=2.3
Requires-Dist: pydantic-ai-slim[anthropic,mcp]>=2.56.0
Requires-Dist: pydantic>=2.10
Requires-Dist: pyyaml>=6.0
Requires-Dist: typer>=0.15
Provides-Extra: all-providers
Requires-Dist: pydantic-ai-slim[bedrock,google,groq,mistral,openai,openrouter,xai]>=2.56.0; extra == 'all-providers'
Provides-Extra: bedrock
Requires-Dist: pydantic-ai-slim[bedrock]>=2.56.0; extra == 'bedrock'
Provides-Extra: google
Requires-Dist: pydantic-ai-slim[google]>=2.56.0; extra == 'google'
Provides-Extra: groq
Requires-Dist: pydantic-ai-slim[groq]>=2.56.0; extra == 'groq'
Provides-Extra: mistral
Requires-Dist: pydantic-ai-slim[mistral]>=2.56.0; extra == 'mistral'
Provides-Extra: openai
Requires-Dist: pydantic-ai-slim[openai]>=2.56.0; extra == 'openai'
Provides-Extra: openrouter
Requires-Dist: pydantic-ai-slim[openrouter]>=2.56.0; extra == 'openrouter'
Provides-Extra: xai
Requires-Dist: pydantic-ai-slim[xai]>=2.56.0; extra == 'xai'
Description-Content-Type: text/x-rst

|logo| |text|

.. |logo| image:: https://raw.githubusercontent.com/rbturnbull/mcparser/main/docs/_static/mcparser.svg
   :alt: MCParser logo
   :height: 220px
   :align: middle

.. |text| image:: https://raw.githubusercontent.com/rbturnbull/mcparser/main/docs/_static/mcparser-text.svg
   :alt: MCParser
   :height: 220px
   :align: middle

=========================
MCParser
=========================

.. image:: https://github.com/rbturnbull/mcparser/actions/workflows/testing.yml/badge.svg
   :target: https://github.com/rbturnbull/mcparser/actions/workflows/testing.yml
   :alt: Tests

.. image:: https://img.shields.io/badge/license-Apache%202.0-blue.svg
   :target: https://github.com/rbturnbull/mcparser/blob/main/LICENSE
   :alt: Apache 2.0 licence

**Dependency parsing with a team of LLM agents.** MCParser annotates text in the
`Universal Dependencies <https://universaldependencies.org/>`_ CoNLL-U format
(segmentation, lemma, UPOS, XPOS, FEATS, HEAD, DEPREL and optionally enhanced
DEPS), using a treebank you trust, such as a UD training file, as the examples.

One agent looks after each CoNLL-U column, and a scorer gives every cell a
confidence. Cells the treebank makes near-certain are settled by plain code
without calling a model. The remaining low-confidence cells are refined over several
rounds. All access to the data goes through an `MCP <https://modelcontextprotocol.io>`_
server, so the same corpus tools also work from Claude Desktop and other
projects.

It is aimed at low-resource and historical languages, where a small treebank and
a capable LLM together beat either alone, and where you want to see *why* a cell
has the value it has. Every edit is logged with the agent that made it.

Installation
============

MCParser needs Python 3.11 or later.

.. code-block:: bash

   pip install --pre mcparser      # alpha release; or: uv tool install --prerelease allow mcparser
   export ANTHROPIC_API_KEY=...    # the default models are Anthropic's

From a clone of the repository: ``uv sync``, then prefix the commands below with ``uv run``.
Other model providers (OpenAI, Google, Bedrock, Groq, Mistral, xAI, OpenRouter) are
installed with extras, for example ``pip install "mcparser[openai]"``. See
`Models and providers <https://rbturnbull.github.io/mcparser/providers.html>`_.

Quick start
===========

.. code-block:: bash

   # 1. Raw text (one sentence per line, or YAML with 'text' fields) -> CoNLL-U with a frequency baseline
   mcparser init input.txt -o pred.conllu -s ud-train.conllu

   # 2. Try one sentence first to see what it costs
   mcparser run pred.conllu -s ud-train.conllu --sentence SENT_ID --rounds 1

   # 3. Annotate everything, stopping at a spending limit (run again to continue)
   mcparser run pred.conllu -s ud-train.conllu --rounds 3 --max-cost 20

   # 4. Compare with gold annotation using the CoNLL 2018 metrics
   mcparser evaluate pred.conllu gold.conllu

``-s`` names the trusted CoNLL-U files (read-only examples). The prediction file is
edited in place and every run can be resumed. ``mcparser settings`` prints all settings
(models for each role, confidence threshold, rounds, batch sizes, cost limit).

How well does it work?
======================

On 100 held-out Ancient Greek (PROIEL) dev sentences, annotated from raw tokens with
the default models (Opus 5.5 for segmentation, lemma and syntax, Sonnet 5.5 for UPOS,
FEATS and scoring, Haiku 5.5 for XPOS) in two rounds, scored by the official
CoNLL 2018 script's metrics:

=========  ======  ======  ======  =======  ======  ======  ======
UPOS       XPOS    UFeats  Lemmas  UAS      LAS     CLAS    MLAS
=========  ======  ======  ======  =======  ======  ======  ======
97.95      97.87   94.18   99.02   92.04    89.09   87.18   77.56
=========  ======  ======  ======  =======  ======  ======  ======

The run cost about $7.80 ($0.078 per sentence, $0.006 per word). Cost per sentence
depends on language and length; it is roughly $0.03 to $0.12 with Sonnet for the strong
roles and one round. Differences of about 1.5 points on a hundred sentences are noise.
Results on four complete dev files, the cost breakdown and the caveats are in
`Results <https://rbturnbull.github.io/mcparser/results.html>`_.

Using it from Claude Desktop
============================

.. code-block:: bash

   mcparser mcp config -s train=ud-train.conllu -s pred=pred.conllu:rw

prints the ``mcpServers`` entry to add to ``claude_desktop_config.json``. Sources
are ``[NAME=]PATH[:ro|rw[:CONFIDENCE]]``: read-only sources hold trusted examples and
writable sources hold predictions. ``mcparser mcp serve`` runs the server directly
(stdio or streamable HTTP; ``--read-only`` removes the editing tools).

From Python
===========

.. code-block:: python

   import anyio
   from mcparser.agents.team import AgentTeam
   from mcparser.corpus import CorpusStore
   from mcparser.pipeline import Pipeline
   from mcparser.settings import Settings

   store = CorpusStore()
   store.add_source("train", "train.conllu")
   store.add_source("pred", "pred.conllu", mode="rw")
   settings = Settings(rounds=2, max_cost=20)
   team = AgentTeam(store, "pred", settings)
   report = anyio.run(Pipeline(store, "pred", team, settings).run)

The corpus store (search, validation, editing, confidence) is also usable without any
agents or model. See the `API reference <https://rbturnbull.github.io/mcparser/api.html>`_.

Limitations
===========

- LLM output varies from run to run, and the agents inherit the treebank's own
  inconsistencies. Check a sample of the output before relying on it, and use the
  confidence scores to decide what to review by hand.
- Cost grows with the number of words, and long sentences are expensive. Use
  ``--max-sentences``, ``--sentence`` and ``--max-cost`` while you tune a setup.
- Only the Anthropic models have been tested in real runs. Other providers are
  supported through pydantic-ai but are untested here.
- The tokeniser in ``init`` is simple (whitespace and punctuation). Clitics and
  multiword tokens are left to the segmentation agent.

Documentation
=============

Full documentation: https://rbturnbull.github.io/mcparser (build it locally with
``uv run --group docs sphinx-build -W docs docs/_build/html``). Design notes for contributors are in
``AGENTS.md``, and changes in ``CHANGELOG.md``.

Contributing
============

.. code-block:: bash

   uv sync --all-groups
   uv run pytest        # the tests never call a model; 100% line and branch coverage is required

See ``CONTRIBUTING.md``. Please report bugs and ideas on the issue tracker.

Licence
=======

Apache 2.0, see ``LICENSE``. The vendored CoNLL 2018 evaluation script in ``tests/official/``
is under the Mozilla Public Licence 2.0.
