Repo inconsistencies found during docs site build

[jkbennitt]

Context

While building the documentation site at felix-sdk.appsprout.dev (AppSprout-dev/AppSprout-Site#21), I reviewed the SDK repo structure, README, __init__.py exports, and pyproject.toml against each other. Found several inconsistencies that should be resolved before v0.1.0.

Findings

1. pyproject.toml missing provider extras mentioned in README

The README documents [bedrock] and [vertex] install extras, but pyproject.toml only defines:

• [anthropic]
• [openai]
• [local]
• [all] (which only includes anthropic + openai)

Action: Either add the extras to pyproject.toml (even as empty placeholders) or update the README to note they're planned.

2. core/ directory incomplete vs package structure doc

The package structure document defines three files:

• core/helix.py — exists
• core/config.py — missing
• core/position.py — missing

HelixConfig and HelixPosition are referenced in __init__.py exports but presumably live in helix.py currently. Should these be split out per the design doc, or is the single-file approach intentional?

3. CLI entry point references nonexistent module

pyproject.toml defines:

[project.scripts]
felix = "felix_agent_sdk.cli.main:main"

But there is no cli/ directory in src/felix_agent_sdk/. This will cause pip install to succeed but felix CLI to fail at runtime.

Action: Either add a stub cli/main.py or remove the entry point until the CLI is implemented.

4. Provider file naming

The OpenAI provider file is providers/openai_provider.py (presumably to avoid shadowing the openai package), but the package structure doc calls it providers/openai.py. Minor, but the docs site now references the actual filename.

5. [all] extra is incomplete

pyproject.toml:

all = [
    "anthropic>=0.30",
    "openai>=1.0",
]

This doesn't include the local extra's dependency (also openai>=1.0, so it works by coincidence), and doesn't include bedrock/vertex when those are added.

6. README quickstart vs actual API

The README quickstart uses a simplified API:

central = CentralPost(helix, provider=provider)
factory = AgentFactory(helix, provider)
team = factory.spawn_team(roles=[...])
for agent in team:
    central.register_agent(agent)

The __init__.py exports suggest FelixWorkflow and run_felix_workflow as the high-level entry points. The README should probably show both: the quick way (run_felix_workflow) and the manual way (current example).

Impact

The docs site (PR AppSprout-dev/AppSprout-Site#21) has been updated to reflect the actual repo state — bedrock/vertex marked as "coming soon", correct file names, correct class names from __init__.py. These findings are for the SDK repo itself to resolve.