BPS Agent Framework

Autonomous agent orchestration, enforcement, and continuous self-improvement

What This Is

This framework builds, governs, and optimizes autonomous AI agents. It is the central nervous system (CNS) for all BPS AI projects — it authors sprint backlogs, dispatches work to project-level agents, reviews their output, catches process gaps, and improves its own execution protocol after every cycle.

The self-improving loop: Agents build the tool. The tool enforces better behavior. Better agents emerge. The CNS observes patterns across projects, prescribes fixes, and the agents implement those fixes. Each cycle gets tighter.

Product Hierarchy

The framework produces value at three levels:

Level 1 — Individual Agents. Each agent is a deployment of the same six-layer architecture with different configuration. Agents BPS has built or is building:

Level 2 — A2A Marketplace. Every agent speaks the A2A protocol (JSON-RPC 2.0). Agents are discoverable via verified agent cards, metered by tier, and queryable by third-party agents. BPS agents become products that other agents consume.

Level 3 — The Orchestration Layer as Product. The CNS pattern itself — portfolio planning, sprint backlog authoring, cross-project PR review, retrospective-driven process improvement, deterministic enforcement — is a repeatable system. Organizations deploy their own orchestration spine: custom agents governed by the same framework, with the same self-improving feedback loop. A custom agile PM intelligence agent for an external organization is one potential early use case.

Each level compounds: better agents (L1) feed a richer marketplace (L2), and the orchestration patterns that govern them (L3) become the deployable product for organizations that want their own agent teams.

Architecture

Six layers, composable per agent:

Context Ingestion → Reasoning/Planning → Generation/Voice → Enforcement → Distribution → Reception/Learn
       ^                                                                                          |
       |                                                                                          |
       +------------------------------  State Push (A2A)  <--------------------------------------+

Key Architectural Patterns

• Signal → Route → Dispatch → Compose — unifying pattern across memory, PM abstraction, content pipeline, and A2A
• "The model codes, Python enforces" — enforcement is deterministic Python, not prompt instructions. Failed generation returns None. Silence over garbage.
• Config, not code — each agent is a configuration (voice profile, enforcement rules, distribution targets), not a fork
• Provider abstraction everywhere — same pattern for PM, distribution, connectors, A2A skills (ProviderProtocol, TypedRegistry, capabilities())

Modules

bpsai-framework/
├── engine/                  # Voice engine, enforcement pipeline, generation
│   ├── generation.py        # generate() → enforce → retry loop
│   ├── pipeline_factory.py  # Public API: build_voice_pipeline(), build_enforcement_config()
│   ├── enforcement.py       # Sync + async enforcement pipelines
│   ├── enforcement_*.py     # L1 hard rules, L2 soft rules, L3 model-based
│   ├── voice_engine.py      # VoiceProfile dataclass + schema
│   ├── prompt_builder.py    # Voice + knowledge + episodic → LLM prompts
│   ├── episodic_index.py    # Local vector index (pure Python, cosine similarity)
│   ├── knowledge_layer.py   # Distilled knowledge loader (positions, arguments, anti-patterns)
│   ├── memory.py            # Grounded memory from human edits
│   └── llm_adapters.py      # Claude API + Ollama adapters
├── orchestration/           # Cross-project provider abstractions
│   ├── provider_protocol.py # ProviderProtocol ABC (capabilities, async, structured results)
│   ├── typed_registry.py    # TypedRegistry (register/get/list/discover)
│   ├── workflow_engine.py   # Config-driven WorkflowEngine
│   ├── lifecycle_manager.py # No-arg construct + connect() pattern
│   └── sync_manager.py      # SyncResult envelope, sync adapters
├── a2a/                     # Agent-to-Agent protocol schemas
│   ├── schemas.py           # SkillResult, AgentCard, SkillDescriptor, RouteResult
│   └── skill_registry.py    # SkillRegistry (TypedRegistry composition)
├── providers/               # Distribution layer
│   ├── base.py              # DistributionProvider ABC
│   ├── linkedin.py          # LinkedInProvider
│   └── content_router.py    # ContentRouter (multi-platform dispatch)
├── voices/                  # Agent voice profiles (YAML)
├── docs/                    # Architecture docs, portfolio plan, orchestration protocol
├── plans/                   # Sprint backlogs + reports (all projects)
│   ├── backlogs/            # Authored by CNS, delivered to project agents
│   └── reports/             # Sprint reports + retrospectives
└── tests/                   # 720 tests across 50 files

Cross-Project Orchestration

This repo is the portfolio-level source of truth for all BPS AI projects. The Framework Navigator acts as the CNS:

1. Authors sprint backlogs for all projects based on portfolio priorities
2. Delivers backlogs to project agents via .paircoder/context/sprint-backlog.md
3. Reviews PRs from project Navigators for alignment and contract compliance
4. Dispatches fix agents directly when issues are scoped and safe
5. Writes retrospectives and updates the execution protocol when process gaps surface

See docs/ORCHESTRATION.md for the full coordination protocol, branch model, PR review process, and sprint execution sequence.

Enforcement Model

Three levels, all deterministic Python:

Enforcement runs locally. No user code leaves the machine.

Status

Sprints 1-7 complete. 720 tests. Code reviewed + security audited.

Development

# Install
pip install -e ".[llm]"    # With Claude API support
pip install -e .            # Core only (Ollama adapters included)

# Run tests
python -m pytest tests/ -v

# Run with coverage
python -m pytest --cov

License

Proprietary — BPS AI Software LLC