bpsai-framework 0.3.0

Composable agent infrastructure for BPS AI Software

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:

Agent	What It Does	Status
PairCoder CLI	AI pair programming with enforcement, orchestration, query layer	Production. ~10K tests.
Moltbot (marketing bot)	Autonomous social content on Moltbook — all 6 layers live	Production. 2,145 tests. Systemd.
Digital Twins (David & Mike)	Voice-authentic content across LinkedIn, Reddit, blog (David: business + AI, Mike: architecture + engineering)	Voice + distribution ready. Deployment pipeline next.
Support Triage Agent	AI-augmented ticket triage, agentic code investigation, suggested responses	Production. Backend 611 + Functions 732 + Frontend 308 tests.
Aurora	Meeting transcription, intent capture, structured A2A state push	Existing project. A2A integration deferred.
Platform Impact	Nightly changelog scrape, classify, surface relevant changes	Live as GitHub Action in CLI.

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

Repo	Purpose	Relationship
paircoder (CLI)	AI pair programming tool, orchestration, query layer	First framework consumer. ~10K tests.
paircoder_api	Licensing, telemetry, A2A server	A2A server migrating to framework. 910 tests.
paircoder_bot	Moltbot — autonomous social agent (all 6 layers)	Pattern source for framework extraction. 2,145 tests.
bpsai-support	Support SDK — ticket triage, agentic investigation, portal	Backend 611 + Functions 732 + Frontend 308 tests.
paircoder.ai	Website, blog, documentation	Content updates with feature releases.

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:

Level	Type	Behavior	Examples
L1	Hard rules	Block + retry	Forbidden patterns, word count, formatting
L2	Soft rules (advisory)	Warn, don't block	Specificity, question detection
L3	Model-based (Ollama)	Soft warning	Confabulation, generic analogy detection

Enforcement runs locally. No user code leaves the machine.

Status

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

Sprint	Theme	Key Deliverables
1-4	Voice Engine + Pipeline	Voice profiles, enforcement pipeline, prompt builder, episodic retrieval, async enforcement, memory capture
5	Provider Convergence	orchestration/ module — ProviderProtocol, TypedRegistry, WorkflowEngine, lifecycle patterns
6	Distribution + Orchestration	LinkedInProvider, ContentRouter, ORCHESTRATION.md, cross-project PR review, bot S30 reviewed/merged
7	Voice Packaging + A2A	PairCoder voice profile, pipeline factory (public API), A2A schemas + SkillRegistry, public __init__.py surfaces

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