# PRAXO-CORE Perl Core

PRAXO-CORE is an embeddable, MIT-licensed agent framework. This distribution is
its native Perl Core: an agent loop with tool registration and dispatch, policy
hooks, typed events, memory, checkpoints, context budgets, middleware, OTel and Harmovela sinks, MCP, retriever and synchronous delegation seams, JSON
Schema validation, and plugin manifest parsing.

The normative contract is [`spec/`](../../spec/README.md); Go remains the
reference implementation.

- `SPEC_VERSION`: `0.2.0`
- Core version: `0.4.0`
- Tier: core
- License: MIT
- Dependencies: Perl core modules only (`JSON::PP`, `File::Spec`, `Cwd`)

## Registry and Coding-Agent Entry

- Registry introduction: [REGISTRY.md](https://github.com/axisvela/praxo-core/blob/main/language/perl/REGISTRY.md)
- Machine-readable entry: [llms.txt](https://github.com/axisvela/praxo-core/blob/main/language/perl/llms.txt) and [llms.md](https://github.com/axisvela/praxo-core/blob/main/language/perl/llms.md)
- Coding-agent contract: [docs/getting-started/coding-agents.md](https://github.com/axisvela/praxo-core/blob/main/docs/getting-started/coding-agents.md)
- Registry: [CPAN (MetaCPAN index)](https://metacpan.org/dist/Praxo-Core)

## Scope

The Core implements all eleven vector groups: toolcall, JSON Schema, plugin,
memory, event, stream, checkpoint, policy, context, middleware, and the agent
loop. It includes a public API snapshot and a dependency-free test runner.

The distribution root package is `Praxo::Core`; `Praxo::Agent` and the other
modules remain available.

## Build and test

```bash
perl language/perl/conformance/run.pl
perl language/perl/api-snapshot.pl --check
perl language/perl/tests/run.pl
```

## Quickstart

```perl
use lib 'language/perl/lib';
use Praxo::Models ();
use Praxo::Agent ();

my $model = Praxo::Agent::StaticModel->new('hello');
my $options = Praxo::Agent::AgentOptions->new($model);
my $result = Praxo::Agent::run_agent(
    $options,
    Praxo::Models::session(id => 'demo'),
    'hello',
);
print $result->{output};
```

Tools register on the options object:

```perl
use Praxo::Agent ();

my $registry = Praxo::Agent::ToolRegistry->new;
$registry->register(Praxo::Agent::FuncTool->new('echo', 'Echo arguments', sub {
    return $_[0];
}));

my $options = Praxo::Agent::AgentOptions->new($model);
$options->{tools} = $registry;
$options->{max_steps} = 8;
```

## OpenAI-Compatible Model

```perl
use Praxo::Adapters::OpenAICompatible ();

my $model = Praxo::Adapters::OpenAICompatible->new(
    base_url => 'https://api.openai.com/v1',
    model => 'gpt-4o-mini',
    api_key => $ENV{PRAXO_API_KEY},
);
my $options = Praxo::Agent::AgentOptions->new($model);
```

The adapter uses non-streaming `POST /chat/completions`, maps tool calls and
usage, and passes `tool_choice`, `response_format`, and `temperature` through.
It uses core `HTTP::Tiny` and `JSON::PP`; no provider SDK is required.

## Anthropic and Gemini Models

```perl
use Praxo::Adapters::Anthropic ();
use Praxo::Adapters::Gemini ();

my $claude = Praxo::Adapters::Anthropic->new(
    model => 'claude-sonnet-4-5',
    api_key => $ENV{ANTHROPIC_API_KEY},
);
my $gemini = Praxo::Adapters::Gemini->new(
    model => 'gemini-2.5-pro',
    api_key => $ENV{GEMINI_API_KEY},
);
```

Both adapters accept a `transport` callback for deterministic tests and use
core `HTTP::Tiny` otherwise.

## MCP Client

Praxo::Adapters::MCP implements MCP initialize, paginated tool listing, and
tool calls over an injected transport callback.

## Harmovela Event Sink

`Praxo::Adapters::Harmovela` posts each event to `{base_url}/events`.

```perl
use Praxo::Adapters::Harmovela ();

my $sink = Praxo::Adapters::Harmovela->new(
    base_url => 'http://127.0.0.1:8790/aep/api',
);
$options->{events} = $sink;
```

A 2xx status is success; other statuses raise `HARMOVELA_HTTP` with the status
and a bounded body. Inject `transport` (and `clock`) to test without a network.
The sink adds no authentication, retries, buffering, ordering, or exactly-once
delivery. Use HTTPS and filter sensitive event data first.

## Layout

- `lib/Praxo/` package source.
- `conformance/run.pl` vector runner.
- `api-snapshot.pl` and `api/` public API snapshot.
- `tests/run.pl` test suite.

## Release

Tag shape: `perl/v0.4.0`. The tag targets `SPEC_VERSION` `0.2.0`. CPAN
publication uses `.github/workflows/perl-release.yml`; see
[PUBLISHING.md](PUBLISHING.md).