Skip to content

Migration Guide

This guide covers upgrading between versions of the FCC Agent Team Framework, including the transition from editable installs to PyPI installs and the data path relocation introduced in v0.2.0.

Upgrading from Editable Install to PyPI Install

If you have been using a local clone with pip install -e ., you can switch to the PyPI-published package.

Step 1: Remove the editable install

pip uninstall fcc-agent-team-ext

Step 2: Install from PyPI

pip install fcc-agent-team-ext

Or pin to a specific version:

pip install fcc-agent-team-ext==0.2.0

Step 3: Verify

python -c "from fcc import __version__; print(__version__)"
fcc --version

When to keep the editable install

Continue using pip install -e ".[dev]" if you are:

  • Developing or contributing to the FCC framework itself.
  • Modifying persona YAML files or Jinja2 templates in src/fcc/data/ or src/fcc/templates/.
  • Running the test suite or building documentation.

The editable install points directly at your source tree, so changes take effect immediately without reinstalling.

Version Upgrade Guide

Upgrading to the latest version

pip install --upgrade fcc-agent-team-ext

Upgrading to a specific version

pip install fcc-agent-team-ext==0.3.0

Checking your current version

python -c "from fcc import __version__; print(__version__)"

Or via the CLI:

fcc --version

Reviewing changes before upgrading

Check the Changelog for breaking changes, new features, and bug fixes before upgrading. Pay particular attention to entries under Changed, Removed, and Deprecated.

Breaking Changes in v0.2.0: Data Path Relocation

Version 0.2.0 relocated all package data from the project-root data/ directory into src/fcc/data/. This change ensures that data files are included in the wheel and available to non-editable installs. If your code directly referenced data/ paths, it will need updating.

What changed

Before (v0.1.x) After (v0.2.0)
data/personas/*.yaml src/fcc/data/personas/*.yaml
data/schemas/*.json src/fcc/data/schemas/*.json
data/workflows/*.json src/fcc/data/workflows/*.json
data/scenarios/*.json src/fcc/data/scenarios/*.json
data/governance/*.yaml src/fcc/data/governance/*.yaml
data/docs/*.yaml src/fcc/data/docs/*.yaml

Why it changed

In v0.1.x, data files lived at the project root and were only accessible from a cloned repository with an editable install. When installing from a wheel (pip install fcc-agent-team-ext), those files were not included. Moving data inside the src/fcc/ package tree and configuring package-data in pyproject.toml ensures data ships with the wheel.

The _resources module

Version 0.2.0 introduced fcc._resources, a centralized module for resolving data paths using importlib.resources. This works correctly in all installation modes (editable, wheel, system-wide).

from fcc._resources import (
    get_data_dir,
    get_personas_dir,
    get_schemas_dir,
    get_workflows_dir,
    get_scenarios_dir,
    get_governance_dir,
    get_docs_data_dir,
    get_templates_dir,
)

Each function returns a pathlib.Path:

from fcc._resources import get_personas_dir

personas_path = get_personas_dir()
# Returns: <site-packages>/fcc/data/personas  (wheel install)
#      or: <repo>/src/fcc/data/personas        (editable install)

Migrating custom code

If your code constructed data paths manually, update it to use _resources:

Before (v0.1.x):

from pathlib import Path

# Fragile: assumes specific working directory or project structure
data_dir = Path("data/personas")
personas_yaml = data_dir / "core_personas.yaml"

After (v0.2.0):

from fcc._resources import get_personas_dir

personas_dir = get_personas_dir()
personas_yaml = personas_dir / "core_personas.yaml"

Before (v0.1.x) -- schema loading:

import json
from pathlib import Path

schema_path = Path("data/schemas/persona.schema.json")
with open(schema_path) as f:
    schema = json.load(f)

After (v0.2.0):

import json
from fcc._resources import get_schemas_dir

schema_path = get_schemas_dir() / "persona.schema.json"
with open(schema_path) as f:
    schema = json.load(f)

Before (v0.1.x) -- workflow loading:

from fcc.workflow.graph import WorkflowGraph

graph = WorkflowGraph.from_json("data/workflows/base_sequence.json")

After (v0.2.0):

from fcc._resources import get_workflows_dir
from fcc.workflow.graph import WorkflowGraph

graph = WorkflowGraph.from_json(str(get_workflows_dir() / "base_sequence.json"))

Checking for old references

Search your codebase for hardcoded data/ paths:

grep -rn '"data/' src/ tests/ --include='*.py'
grep -rn "Path(.*data/" src/ tests/ --include='*.py'

Any matches should be updated to use fcc._resources functions.

Custom data files

If you have added custom persona YAML files or scenario JSON files to the old data/ directory, move them into src/fcc/data/ under the appropriate subdirectory. The PersonaRegistry.from_yaml_directory() and ScenarioLoader.from_directory() methods will discover them automatically.

If you prefer to keep custom data outside the package (e.g., in a separate project directory), pass explicit paths to the loader methods rather than relying on the default _resources paths:

from fcc.personas.registry import PersonaRegistry

# Load from a custom directory outside the package
registry = PersonaRegistry.from_yaml_directory("/path/to/my/personas")

Next Steps