Metadata-Version: 2.4
Name: hypershub-agent-core
Version: 0.2.0
Summary: Policy-aware, provider-neutral agent runtime built on Pydantic AI
Author: HypersHub
License-Expression: MIT
License-File: LICENSE
Keywords: agent,agentic,ai,llm,mcp,pydantic-ai
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: beautifulsoup4<5,>=4.12
Requires-Dist: httpx<1,>=0.28.1
Requires-Dist: markdownify<2,>=0.13
Requires-Dist: packaging<27,>=24
Requires-Dist: pydantic-ai-slim[anthropic,evals,mcp,openai,retries,spec]<2.28,>=2.27.1
Requires-Dist: pydantic-evals==2.27.1
Requires-Dist: pydantic>=2.12
Requires-Dist: python-dotenv>=1.0
Requires-Dist: pyyaml>=6.0.2
Description-Content-Type: text/markdown

# hypershub-agent-core

`hypershub-agent-core` is a typed, policy-aware Agent runtime built on Pydantic AI. It
provides a stable application boundary around models, prompts, tools, Skills,
MCP servers, runtime events, evaluation gates, and release governance.

This is an Alpha release. The `agentic.core/v1alpha1` configuration schema and
the Python API may change before 1.0. The library supports Pydantic AI
`>=2.27.1,<2.28`; the repository lockfile pins the exact CI/runtime version.

## Capabilities

- Strict YAML/JSON Agent specs with deterministic inheritance and fingerprints
- OpenAI-compatible and Anthropic-compatible model registries using lazy secret references
- Explicit plugin registration and policy-gated tool execution
- Selectable standard Workspace, Todo, Web Fetch, and Shell toolsets
- Filesystem Skills with confined resources, integrity checks, and trusted-source boundaries
- Allowlisted MCP stdio commands and remote endpoint aliases with lazy Bearer authentication
- Stable events, usage accounting, cancellation, idempotency, concurrency, and queue limits
- Agent evaluation suites, repeat baselines, regression diffs, and release gates
- A loopback-only Agent Studio and debug UI for trusted development environments
- Optional `EventSink` / JSONL event output without coupling Runtime to a backend

## Requirements

- Python 3.11 or newer
- A supported model endpoint and API credential for live Agent runs
- Trusted application code that defines the allowed plugins, Skills, tools, MCP commands,
  remote endpoints, and workspace roots

## Install

```bash
python -m pip install hypershub-agent-core
```

The distribution name is `hypershub-agent-core`, the import package is
`agentic_core`, and the CLI command is `agentic-core`.

## Quick start

Create `models.yaml`. Credentials are references, never plaintext values:

```yaml
models:
  - id: default
    provider: openai_chat
    model: gpt-4.1-mini
    base_url: https://api.openai.com/v1
    api_key: env://OPENAI_API_KEY
```

Create `agent.yaml`:

```yaml
schema_version: agentic.core/v1alpha1
id: math-agent
name: Math Agent
model:
  ref: default
prompts:
  stable:
    - Use the add_numbers tool for integer addition and return its exact result.
toolsets:
  - plugin: core.arithmetic
run_policy:
  request_limit: 4
  tool_calls_limit: 4
  timeout_seconds: 60
```

Compile and run it from trusted application code:

```python
import asyncio

from agentic_core import (
    AgentCompiler,
    AgentRuntime,
    RuntimeAgent,
    ModelRegistry,
    PluginRegistry,
    load_agent_spec,
    register_builtin_plugins,
)


async def main() -> None:
    models = ModelRegistry.from_file("models.yaml")
    plugins = register_builtin_plugins(PluginRegistry())
    spec = load_agent_spec("agent.yaml")
    compiled = AgentCompiler(models=models, plugins=plugins).compile(spec)
    result = await AgentRuntime().run(compiled, "Add 37 and 58.")
    print(result.output)

    # UI/channel integrations must use the governed facade rather than
    # calling ``compiled.agent`` directly.
    runtime_agent = RuntimeAgent(compiled, channel="example")
    result = await runtime_agent.run("Add 37 and 58.")
    print(result.output)


asyncio.run(main())
```

## Standard tools

Core 0.2 ships standard agent-facing tool contracts while trusted applications retain control of
workspace and process authority. Configure backends once, register the plugins, then select them in
the Agent Spec:

```python
from agentic_core import (
    CallableShellBackend,
    CallableWorkspaceBackend,
    PluginRegistry,
    StandardToolRuntime,
    register_standard_tool_plugins,
)

runtime = StandardToolRuntime(
    workspace=CallableWorkspaceBackend(
        read_file_fn=read_file,
        glob_fn=glob,
        grep_fn=grep,
        write_file_fn=write_file,
        edit_file_fn=edit_file,
    ),
    shell=CallableShellBackend(
        run_shell_fn=run_shell,
        read_background_shell_fn=read_background_shell,
        list_background_shells_fn=list_background_shells,
        kill_background_shell_fn=kill_background_shell,
    ),
)
plugins = register_standard_tool_plugins(PluginRegistry(), runtime=runtime)
```

Available plugin ids are `core.workspace.standard`, `core.todo`, `core.web.fetch`, and
`core.shell.standard`. Merely registering them does not enable them; the Agent Spec must select each
toolset. Workspace and Shell selection fails during compilation when the corresponding trusted
backend is absent.

Validate configuration without making a model request:

```bash
agentic-core models validate models.yaml
agentic-core spec validate agent.yaml
agentic-core spec fingerprint agent.yaml
```

## Security model

This package is a library for trusted application processes; it is not a
sandbox. Agent YAML cannot introduce raw MCP URLs or arbitrary executable
commands. The application must inject reviewed command aliases, endpoint
rules, plugin registries, Skill sources, workspace roots, and approval policy.

Keep provider and MCP credentials in a secret manager or environment variables
referenced with `env://` or `file://`. Do not put plaintext secrets in Agent
specs, prompts, tool arguments, logs, or evaluation artifacts. See
[SECURITY.md](./SECURITY.md) for reporting and deployment guidance.

## Scope and compatibility

The package supports a tested Pydantic AI compatibility window of
`>=2.27.1,<2.28`. Consumers should pin their application lockfile and verify
the selected version in CI while the project is below 1.0.

The filesystem Agent store and Debug UI are local reference implementations:
they use process-local locks and are intended for one process at a time. Use a
database-backed store and authenticated control plane for multi-process or
multi-tenant deployments. Debug UI API requests require the random token shown
in the startup URL; it remains loopback-only and is not a production control plane.

`AgentRuntime.run` supports idempotency keys. `stream_events` is a live event
stream and intentionally has no idempotency-key contract; use `run` or a
durable event sink when retry/replay semantics are required.

For Pydantic AI UI and channel protocols, use `RuntimeAgent`. It preserves the
native `run_stream_events` event contract while routing execution through
`AgentRuntime` for timeout, cancellation, concurrency, Scope, usage, and error
normalization. Application code should not call `compiled.agent.run(...)`
directly.

Spec inheritance merges mappings recursively but replaces list/tuple fields with
the child value. A child `toolsets` list therefore replaces, rather than appends
to, the parent list.

The bundled arithmetic and guidance plugins demonstrate the plugin contract.
Production applications are expected to register their own reviewed plugins
and policies. Provider credentials are resolved only when a model is built.

## License

[MIT](./LICENSE)
