Metadata-Version: 2.4
Name: bpsai-framework
Version: 0.3.0
Summary: Composable agent infrastructure for BPS AI Software
Author-email: BPS AI Software <support@bpsaisoftware.com>
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://github.com/BPSAI/bpsai-framework
Project-URL: Repository, https://github.com/BPSAI/bpsai-framework
Project-URL: Issues, https://github.com/BPSAI/bpsai-framework/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Requires-Dist: httpx>=0.27
Requires-Dist: bpsai-agent-enforce<0.2,>=0.1.3
Requires-Dist: bpsai-agent-lounge<0.2,>=0.1.0
Provides-Extra: llm
Requires-Dist: anthropic>=0.40; extra == "llm"
Provides-Extra: dev
Requires-Dist: pytest>=9.0; extra == "dev"
Requires-Dist: pytest-asyncio>=1.0; extra == "dev"
Dynamic: license-file

# 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

```bash
# 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
