Metadata-Version: 2.4
Name: fred-sdk
Version: 0.1.5
Summary: Authoring SDK for Fred agents — graph, ReAct, and team agent primitives.
Author-email: Thales <noreply@thalesgroup.com>
License: Apache-2.0
Project-URL: Homepage, https://fredk8.dev
Project-URL: Repository, https://github.com/ThalesGroup/fred
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Requires-Python: <3.13,>=3.12
Description-Content-Type: text/markdown
Requires-Dist: fred-core>=1.3.1
Requires-Dist: fred-portable>=0.1.1
Requires-Dist: pydantic<3.0.0,>=2.7.0
Requires-Dist: langchain-core>=0.3.0
Requires-Dist: langchain>=0.3.0
Requires-Dist: langgraph>=1.1.3
Requires-Dist: deepagents>=0.4.11
Requires-Dist: httpx>=0.28.1
Provides-Extra: dev
Requires-Dist: bandit>=1.8.6; extra == "dev"
Requires-Dist: basedpyright==1.31.0; extra == "dev"
Requires-Dist: detect-secrets>=1.5.0; extra == "dev"
Requires-Dist: pytest>=8.4.2; extra == "dev"
Requires-Dist: pytest-cov>=6.2.1; extra == "dev"
Requires-Dist: ruff>=0.12.5; extra == "dev"

# Fred SDK

`fred-sdk` is the authoring SDK for Fred agents. It provides the public APIs and abstractions required to define agents, workflows, and multi-agent compositions without depending on platform-specific runtime internals.

It is intended to be used together with `fred-runtime`, which provides the execution layer used to run those agents inside an application.

---

## Overview

The Fred architecture separates **agent definition** from **agent execution**.

This separation is reflected in two complementary API layers:

### 1. Authoring APIs (`fred-sdk`)

These APIs are used to define agents declaratively.

They cover concerns such as:

- agent identity and metadata
- prompts and policies
- tool declarations
- workflow structure
- team and multi-agent composition
- human-in-the-loop patterns
- abstract runtime contracts

This is the layer used by agent authors.

### 2. Runtime APIs (`fred-runtime`)

These APIs are used to execute agents inside a real application environment.

They cover concerns such as:

- application creation
- registry wiring
- runtime configuration
- checkpointing
- tracing and observability
- security integration
- infrastructure adapters

This is the layer used by application and platform developers.

In summary:

- `fred-sdk` defines the agent
- `fred-runtime` runs the agent

---

## What `fred-sdk` is for

Developers use `fred-sdk` to build Fred agents in a portable and structured way.

It supports several paradigms, including:

- ReAct-style agents
- graph-based workflows
- team and multi-agent systems
- human-in-the-loop workflows

The goal is to let developers focus on behavior and orchestration without wiring runtime infrastructure directly into agent definitions.

---

## Installation

```bash
pip install fred-sdk
```

---

## Quickstart

A realistic minimal example is to declare an agent with `fred-sdk`, then run it through an application created with `fred-runtime`.

### Agent definition with `fred-sdk`

```python
from fred_sdk.contracts.models import ReActAgentDefinition, ReActPolicy


class GeneralAssistantDefinition(ReActAgentDefinition):
    agent_id: str = "fred.samples.assistant"
    role: str = "General-purpose assistant"
    description: str = (
        "A helpful, concise assistant for general questions and conversation. "
        "No external tools or document retrieval required."
    )
    tags: tuple[str, ...] = ("general", "react")
    system_prompt_template: str = """\
You are a helpful, knowledgeable, and concise assistant.
Answer questions clearly and directly. When you are uncertain, say so.
You have no access to external tools or documents — work only from your own knowledge.
"""

    def policy(self) -> ReActPolicy:
        return ReActPolicy(system_prompt_template=self.system_prompt_template)


GENERAL_ASSISTANT_AGENT = GeneralAssistantDefinition()
```

This example illustrates the **authoring API**: the agent is defined declaratively through a public SDK model.

### Application startup with `fred-runtime`

```python
from fastapi import FastAPI
from fred_runtime.app import AgentPodConfig, create_agent_app, load_agent_pod_config

from fred_samples_agents.registry import REGISTRY


def create_app(config: AgentPodConfig | None = None) -> FastAPI:
    resolved_config = config if config is not None else load_agent_pod_config()
    return create_agent_app(registry=REGISTRY, config=resolved_config)


app = create_app()
```

This example illustrates the **runtime API**: the registry and configuration are assembled into an executable FastAPI application.

---

## Understanding the two API levels

The distinction between the two layers is intentional.

### In `fred-sdk`, developers declare agents

For example, an agent author defines:

- the agent identifier
- the role and description
- the system prompt
- the policy
- optional tool and workflow contracts

This code should remain portable and mostly independent from deployment concerns.

### In `fred-runtime`, developers run agents

For example, an application developer or platform team:

- creates an agent registry
- loads runtime configuration
- wires checkpointing and runtime services
- exposes the agents through an application

This code is responsible for effective execution.

---

## Relationship with `fred-runtime`

`fred-sdk` and `fred-runtime` are designed to be used together, with a clean separation of responsibilities.

- `fred-sdk` provides the public authoring surface
- `fred-runtime` provides the execution environment

Behind the scenes, Fred uses LangChain and LangGraph for orchestration and runtime behavior, but these concerns are intentionally separated from the authoring layer as much as possible.

---

## Design principles

- **Separation of concerns**: authoring and runtime are distinct layers
- **Portability**: agent definitions should not depend on a specific backend
- **Composability**: simple agents, workflows, and team agents should share a coherent model
- **Extensibility**: runtime implementations can evolve without changing the authoring model
- **Clarity**: public APIs for agent authors should remain stable and easy to understand

---

## Notes

- `fred-sdk` depends on `fred-core` and `fred-portable`, which are installed automatically
- The public SDK surface is exposed through `fred_sdk/__init__.py` for convenient top-level imports
- Runtime-specific application bootstrapping belongs in `fred-runtime`, not in `fred-sdk`

---

## Resources

- Homepage: https://fredk8.dev
- Repository: https://github.com/ThalesGroup/fred
- Runtime package: https://pypi.org/project/fred-runtime/

---

## Conceptual model

- `fred-sdk`: authoring APIs used to define agents
- `fred-runtime`: runtime APIs used to execute them
