Metadata-Version: 2.4
Name: octools
Version: 1.2.0rc2
Summary: OpsCogs standard interface for AI agent tools: the OCTool descriptor, result envelopes, conformance validator, and vendor-neutral converters.
Author-email: "OpsCogs Inc." <support@opscogs.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/opscogs/octools
Project-URL: Documentation, https://octools.docs.opscogs.com
Project-URL: Source, https://github.com/opscogs/octools
Project-URL: Changelog, https://github.com/opscogs/octools/blob/main/CHANGELOG.md
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.12.0
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: pydantic<3,>=2.12
Provides-Extra: dev
Requires-Dist: build==1.6.1; extra == "dev"
Requires-Dist: ruff==0.16.9; extra == "dev"
Requires-Dist: black==26.5.1; extra == "dev"
Requires-Dist: mypy==2.3.1; extra == "dev"
Provides-Extra: doc
Requires-Dist: mkdocs-material==9.7.7; extra == "doc"
Requires-Dist: mkdocs-awesome-pages-plugin==2.10.1; extra == "doc"
Requires-Dist: mkdocs-macros-plugin==1.5.0; extra == "doc"
Provides-Extra: test
Requires-Dist: pytest==9.1.1; extra == "test"
Requires-Dist: pytest-cov==7.1.0; extra == "test"
Provides-Extra: all
Requires-Dist: octools[dev,doc,test]; extra == "all"
Dynamic: license-file

# octools

[![PyPI](https://img.shields.io/pypi/v/octools)](https://pypi.org/project/octools/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/opscogs/octools/blob/main/LICENSE)

OpsCogs standard interface for AI agent tools: the `OCTool` descriptor,
the result envelopes every tool returns, a conformance validator, and
pure-dict converters to the MCP and Anthropic tool shapes. A library
describes each capability once; any agent runtime registers it without
re-expressing it by hand.

A TypeScript package, [`@opscogs/octools`](https://www.npmjs.com/package/@opscogs/octools),
implements the same contract.

## Install

Python 3.12 or newer and pydantic 2.12 or newer (the only dependency).

```sh
pip install octools
```

## Quick start

Describe the arguments and result as pydantic models, wrap the function
in an `OCTool`, and list the tools from `all_tools()`:

```python
from pydantic import BaseModel, Field
from octools import (
    OCTool,
    RecordsEnvelope,
    input_schema_for,
    records_schema,
    to_mcp_tool,
)


class EchoArgs(BaseModel):
    values: list[str] = Field(description="Strings to echo back, one record each.")


class EchoRecord(BaseModel):
    value: str = Field(description="The echoed string.")
    position: int = Field(description="Zero-based position in the input.")


def echo_records(_dependency, *, values: list[str]) -> dict:
    records = [EchoRecord(value=v, position=i) for i, v in enumerate(values)]
    return RecordsEnvelope[EchoRecord](
        records=records, count=len(records), truncated=False
    ).model_dump(mode="json")


ECHO_RECORDS = OCTool(
    name="echo_records",
    description="Return each input string as one record with its position. Use it to check a tool round-trip. Returns a records envelope.",
    input_schema=input_schema_for(EchoArgs),
    output_schema=records_schema(EchoRecord),
    func=echo_records,
    access="local",
)


def all_tools() -> tuple[OCTool, ...]:
    return (ECHO_RECORDS,)


mcp_entry = to_mcp_tool(ECHO_RECORDS)
```

In your test suite, `assert validate_provider(my_tools) == []` lists every
conformance finding. List a provider from the command line with
`octools list my_tools`; `octools list octools.example` lists the built-in
demo provider.

## Links

- [Documentation](https://octools.docs.opscogs.com)
- [Source and issues](https://github.com/opscogs/octools)
- [Changelog](https://github.com/opscogs/octools/blob/main/CHANGELOG.md)

## License

MIT. See [LICENSE](https://github.com/opscogs/octools/blob/main/LICENSE). The OpsCogs name and logos are
not covered by that license; see [NOTICE](https://github.com/opscogs/octools/blob/main/NOTICE).
