Metadata-Version: 2.5
Name: chatomon
Version: 0.1.0
Summary: Declare a chat agent once (instructions, knowledge and guardrail orbitals) and build it into native agent frameworks.
Project-URL: Homepage, https://chatomon.andromedalabs.io/
Project-URL: Documentation, https://chatomon.andromedalabs.io/
Project-URL: Repository, https://github.com/zazza123/chatomon
Project-URL: Issues, https://github.com/zazza123/chatomon/issues
Project-URL: Changelog, https://github.com/zazza123/chatomon/releases
Author-email: Andrea Zanini <andrea.zanini@andromedalabs.io>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent-framework,agents,google-adk,guardrails,langchain,llm,pydantic-ai
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
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: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: opentelemetry-api>=1.28
Requires-Dist: pydantic>=2.10
Provides-Extra: adk
Requires-Dist: google-adk<2.13,>=2.10; extra == 'adk'
Requires-Dist: opentelemetry-api>=1.40; extra == 'adk'
Provides-Extra: langchain
Requires-Dist: langchain<2,>=1.3; extra == 'langchain'
Provides-Extra: maf
Requires-Dist: agent-framework-core<2,>=1.19; extra == 'maf'
Provides-Extra: maf-foundry
Requires-Dist: agent-framework-foundry<2,>=1.13.1; extra == 'maf-foundry'
Provides-Extra: principled
Requires-Dist: orbitals<0.7,>=0.5; extra == 'principled'
Provides-Extra: pydantic-ai
Requires-Dist: pydantic-ai-slim<3,>=2.14; extra == 'pydantic-ai'
Provides-Extra: spectral
Requires-Dist: opentelemetry-sdk>=1.28; extra == 'spectral'
Requires-Dist: spectral-bridge<0.6,>=0.5; extra == 'spectral'
Requires-Dist: starlette<2,>=1.7; extra == 'spectral'
Requires-Dist: uvicorn<1,>=0.54; extra == 'spectral'
Provides-Extra: studio
Requires-Dist: opentelemetry-sdk>=1.28; extra == 'studio'
Requires-Dist: starlette<2,>=1.7; extra == 'studio'
Requires-Dist: uvicorn<1,>=0.54; extra == 'studio'
Description-Content-Type: text/markdown

<h1 align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/zazza123/chatomon/main/docs/public/assets/brand/hero-dark.svg">
    <img alt="chatomon" src="https://raw.githubusercontent.com/zazza123/chatomon/main/docs/public/assets/brand/hero-light.svg" width="420">
  </picture>
</h1>

Declare a chat agent once — its instructions, its knowledge and the **orbitals** (input/output guardrails) around it — and build it into a native agent of the framework you already use: PydanticAI, LangChain/LangGraph, Microsoft Agent Framework, or Google ADK.

> Status: alpha. The API can still change between minor versions (`0.x`).

## Install

```bash
pip install 'chatomon[pydantic-ai]'   # or 'chatomon[langchain]'
pip install 'chatomon[maf]'           # MAF core; add your provider's MAF client package
pip install 'chatomon[maf-foundry]'   # FoundryChatClient and FoundryAgent
pip install 'chatomon[adk]'           # Google ADK 2.10 to 2.12
pip install 'chatomon[principled]'    # Principled Intelligence ScopeGuard / ClaimExtractor orbitals
pip install 'chatomon[studio,pydantic-ai]'  # the local studio: chatomon studio module:atom
pip install 'chatomon[spectral,pydantic-ai]'  # the studio with its Spectral add-on: evaluation at scale
```

Both MAF connectors support input and output orbitals on non-streaming runs. The [MAF guide](https://chatomon.andromedalabs.io/connectors/maf/) covers local Foundry sessions and connector configuration.

## Quickstart

```python
from pydantic_ai.models.test import TestModel

from chatomon import Atom, Knowledge, OrbitalContext, Verdict, orbital
from chatomon.connectors.pydantic_ai import PydanticAIConnector


@orbital
def no_refunds(ctx: OrbitalContext) -> Verdict:
    if "refund" in ctx.message.lower():
        return Verdict.block(guidance="Explain that refunds are handled by email.")
    return Verdict.allow()


atom = Atom(
    name="speedypack",
    instructions="You are the customer assistant of SpeedyPack, a parcel courier.",
    knowledge=Knowledge("Opening hours: Monday to Friday, 9-18."),
    connector=PydanticAIConnector(TestModel(custom_output_text="Refunds are handled by email.")),
    input_orbitals=[no_refunds],
)
agent = atom.build()  # a native pydantic_ai.Agent
assert agent.run_sync("I want a refund").output == "Refunds are handled by email."
```

Replace `TestModel(...)` with a real model, for example `"openai:gpt-5"`.

To try an atom in the browser, run `chatomon studio speedypack.app:atom` and open the printed link: the studio shows every orbital deciding, turn by turn, and lets you tune the orbitals and copy the result back as code.

## Documentation

The documentation is at [chatomon.andromedalabs.io](https://chatomon.andromedalabs.io/). It covers concepts, orbitals, [connectors](https://chatomon.andromedalabs.io/connectors/), the studio, observability and deployment, plus the API reference generated from the code.

## Contributing

Bug reports, ideas and pull requests are welcome — start with
[`CONTRIBUTING.md`](https://github.com/zazza123/chatomon/blob/main/CONTRIBUTING.md). Security issues: see
[`SECURITY.md`](https://github.com/zazza123/chatomon/blob/main/SECURITY.md).
