Metadata-Version: 2.4
Name: hypershub-agent-core
Version: 0.1.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: httpx<1,>=0.28.1
Requires-Dist: packaging<27,>=24
Requires-Dist: pydantic-ai-slim[anthropic,evals,mcp,openai,retries,spec]==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 initial release intentionally pins
Pydantic AI `2.27.1` so that runtime behavior is reproducible.

## 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
- 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

## 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,
    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)


asyncio.run(main())
```

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 initial package deliberately favors reproducible behavior over dependency
flexibility and therefore requires Pydantic AI `2.27.1`. Consumers should pin
`hypershub-agent-core` to a compatible minor version while the project is below 1.0.

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)
